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".
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".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.
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:
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 da coluna de fonte customizada exibido na central, conforme exemplo abaixo:
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 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 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 utilizada na montagem dos links exibidos. Será concatenado com o conteúdo retornado no "Campo URL" (descrito abaixo).
Exemplo: http://tdn-homolog.totvs.com/
Nome do campo que contém a URL dos links no JSON retornado na requisição.
Exemplo: _links.webui
Deve conter todo caminho para acessar o array com os itens retornados no JSON
Exemplo: results
Deve conter o nome do campo que contém a descrição do link que será exibido na central
Exemplo: title
Quantidade limite de caracteres exibidos no link da Central de Ajuda.
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:
