Configuração para fonte customizada

Objetivo

O objetivo da fonte customizada é permitir que seja configurada uma fonte de pesquisa própria do cliente. Desta forma, clientes que possuam customizações no Protheus e criam documentações dessas customizações poderão utilizar a Central de Ajuda para trazer também a sua própria documentação.

A Central de Ajuda permitirá acessar uma API específica do cliente aplicando os filtros relacionados ao contexto em que a Central foi acionada. 

Por exemplo, quando o cliente possuir o Confluence para documentar as próprias customizações, a Central de Ajuda irá acionar a API do Confluence do cliente passando os filtros do contexto (segmento, verão do Protheus, módulo, rotina, idioma, etc) e irá exibir seus documentos específicos.

O conteúdo retornado pela API do cliente será exibido na aba "Customizações".

Definições

• Será permitida a configuração de apenas uma fonte customizada.
• A API que será consultada deverá permitir a realização de chamadas via REST com requisições do tipo GET e o seu retorno deverá ser no formato JSON. .
• Não há suporte à autenticação
• Deverá ser configurada 3 URL's, uma para busca inicial, uma para a busca adicional e uma para o link "Veja Mais" 
• Para que as URL's configuradas recebam os parâmetros do sistema em tempo de execução, foram criados algumas tags específicas que poderão ser colocadas na URL e serão substituídas pelos parâmetros filtrados de acordo com o contexto no momento da abertura da Central de Ajuda.

Comportamento da Central de Ajuda

Ao ser aberta, a Central de Ajuda irá tratar as URL's configuradas, trocando os parâmetros pelos valores do contexto e irá realizar uma requisição REST via método GET na API configurada.

Ao receber o retorno, a Central irá ler o JSON recebido para montar os links que serão exibidos na aba Customizações.

Lista de parâmetros suportadas

Todas os parâmetros devem iniciar e terminar com chaves duplas {{ }}

• {{linhaproduto}} 
  • Irá receber a linha de produto utilizada, no caso, PROTHEUS.
• {{segmento}}
  • Irá receber o segmento do cliente
• {{versao}}
  • Irá receber a versão com release do ambiente Protheus com underline ao invés de pontos. Exemplo: 12_1_8
• {{modulo}}
  • Irá receber a sigla do módulo que acionou a central. Exemplo: SIGAFAT
• {{rotina}}
  • Irá receber o código da rotina de menu que acionou a central. Exemplo: mata410
• {{texto}}
  • Irá receber o texto digitado na caixa de pesquisa da central. Este parâmetro é utilizado apenas na busca adicional.
• {{idioma}}
  • Irá receber o idioma do ambiente Protheus no seguinte formato "en", "pt", "es".

Removendo parâmetros não obrigatórios

Alguns parâmetros podem não existir dependendo do contexto. Por exemplo, no acionamento da central antes de abrir uma rotina, o parâmetro de rotina virá vazio.

Quando isso ocorre, pode ser necessário remover alguns trechos da URL além do próprio parâmetro. Para isso, o trecho deve ser colocado entre duplos colchetes [[ ]] 

Por exemplo:

http://tdn-homolog.totvs.com/rest/api/content/search?cql= label={{modulo}} [[and label={{rotina}} ]] &limit=10

Na URL acima, quando o parâmetro {{rotina}} vier vazio, todo o trecho [[and label={{rotina}} ]]  será removido da chamada REST.

Retorno da API

Obrigatoriamente, a API deverá retornar um JSON com os dados que deverão ser exibidos na central.

A Central irá exibir apenas links para outras páginas, portanto o JSON deve possuir no seu conteúdo uma lista com as URL's dos links e os títulos que deverão ser exibidos.

Para que a Central de Ajuda consiga ler o JSON retornado pela API do cliente, deverão ser configuradas as seguintes informações:

• caminho completo do array com os itens retornados no JSON
• nome do campo do array que deverá ser utilizado como título 
• nome do campo do array que deverá ser utilizado para obter a URL do link
  
  

Configurando a fonte customizada

Para configurar uma fonte customizada no Protheus, o administrador do ambiente deverá acessar no módulo Configurador (SIGACFG) a rotina Ambiente -> Central de Ajuda -> Config Central de Ajuda

Nesta tela ele deverá cadastrar os seguintes campos:

Título

Título da coluna de fonte customizada exibido na central, conforme exemplo abaixo:

URL busca inicial

ULR que será utilizada na busca inicial. Poderá utilizar os parâmetros descritos anteriormente.

Na busca inicial, a central irá fazer uma chamada REST via GET para esta URL, substituindo os parâmetros pelos valores recebidos na central de acordo com o contexto.

Exemplo de URL:

http://tdn-homolog.totvs.com/rest/api/content/search?cql= label={{modulo}} [[and label={{rotina}} ]] &limit=10

No exemplo acima, o parâmetro {{modulo}} será substituído pela sigla do módulo que acionou a central e o parâmetro rotina será substituído pela rotina. Como o parâmetro rotina está entre colchetes duplos [[ ]] , caso o seu valor venha vazio, todo conteúdo dentro dos colchetes será removido da URL.

URL busca avançada

URL que será utilizada na busca avançada. Segue a mesma regra da URL de busca inicial, porém utiliza também o parâmetro {{texto}} para receber o texto digitado pelo usuário na caixa de pesquisa.

Exemplo: http://tdn-homolog.totvs.com/rest/api/content/search?cql= label={{modulo}} [[and label= {{rotina}} ]] and TEXT ~ {{texto}} &limit=10

URL veja mais

URL utilizada na montagem do link "Veja Mais" que será exibido abaixo dos links na coluna. Pode utilizar os parâmetros, com exceção do {{texto}}.

Exemplo: http://tdn-homolog.totvs.com/label/{{modulo}}

URL base 

URL utilizada na montagem dos links exibidos. Será concatenado com o conteúdo retornado no "Campo URL" (descrito abaixo).

Exemplo: http://tdn-homolog.totvs.com/                                                                       

Campo URL

Nome do campo que contém a URL dos links no JSON retornado na requisição. 

Exemplo: _links.webui                                      

Array com os itens de retorno

Deve conter todo caminho para acessar o array com os itens retornados no JSON

Exemplo: results                                           

Campo Título

Deve conter o nome do campo que contém a descrição do link que será exibido na central

Exemplo: title                                             

Limite de caracteres

Quantidade limite de caracteres exibidos no link da Central de Ajuda.

Exemplo completo de configuração de fonte customizada.

Considerando que a fonte customizada é um ambiente confluence no seguinte domínio: tdn-homolog.totvs.com.

As URL's podem ser configuradas da seguinte forma:

O retorno de uma chamada rest na API deste ambiente retorna um conteúdo semelhante ao exemplo abaixo:

{
"results": [
{
"id": "557074",
"type": "page",
"title": "Relatórios MATR263/MATR264/MATR266",
"_links": {
"webui": "/pages/viewpage.action?pageId=557074",
"tinyui": "/x/EoAI",
"self": "http://tdn-homolog.totvs.com/rest/api/content/557074"
},
"_expandable": {
"metadata": "",
"operations": "",
"children": "",
"history": "/rest/api/content/557074/history",
"ancestors": "",
"body": "",
"version": "",
"descendants": "",
"space": "/rest/api/space/MP"
}
},
{
"id": "557072",
"type": "page",
"title": "OX100AIP - Item do Pedido de Venda na Matriz Enviada ao Pedido de Venda",
"_links": {
"webui": "/display/MP/OX100AIP+-+Item+do+Pedido+de+Venda+na+Matriz+Enviada+ao+Pedido+de+Venda",
"tinyui": "/x/EIAI",
"self": "http://tdn-homolog.totvs.com/rest/api/content/557072"
},
"_expandable": {
"metadata": "",
"operations": "",
"children": "",
"history": "/rest/api/content/557072/history",
"ancestors": "",
"body": "",
"version": "",
"descendants": "",
"space": "/rest/api/space/MP"
}
}
],
"start": 0,
"limit": 25,
"size": 2,
"_links": {
"self": "http://tdn-homolog.totvs.com/rest/api/content/search?LIMIT=10&cql=SPACE=MP%20and%20label=manufatura%20and%20label=%2712_1_4%27",
"base": "http://tdn-homolog.totvs.com",
"context": ""
}
} 

De acordo com este padrão de retorno (destacado nos campos em vermelho), para que a central de ajuda consiga interpretar o JSON, o Protheus poderá ser configurado da seguinte forma: