Páginas filhas
  • API de tradução para o AtuSX

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Comentário: Migration of unmigrated content due to installation of a new plugin

 Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico.                                                             

  

Informações Gerais

 

Especificação

Produto

 

Módulo

 

Segmento Executor

 

Projeto1

 

IRM1

 

Requisito1

 

Subtarefa1

 

Chamado2

 

País

(  ) Brasil  (  ) Argentina  (  ) Mexico  (  ) Chile  (  ) Paraguai  (  ) Equador

(  ) USA  (  ) Colombia   (  ) Outro _____________.

Outros

<Caso necessário informe outras referências que sejam pertinentes a esta especificação. Exemplo: links de outros documentos ou subtarefas relacionadas>.

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

Disponibilizar uma API para busca e inclusão de strings de tradução no AtuSX.

 

Definição da Regra de Negócio

REST

Para o correto desenvolvimento, utilização e configuração veja a documentação do REST antes de utilizar esta API: Documentação do REST no Protheus.

API - Put

Deverá ser desenvolvida uma API de integração com o AtuSX para permitir a busca e inclusão de strings de tradução diretamente em sua base de dados.

O nome da rotina RESTFul deverá ser ATUSX.

A API deverá ser desenvolvida usando os fundamentos do RESTFul e deverá contemplar os seguintes metadados do AtuSX:

  • Dicionário de perguntas – SX1
  • Dicionário de tabelas – SX2
  • Dicionário de campos – SX3
  • Cadastro de tabelas genéricas – SX5
  • Dicionário de Parâmetros – SX6
  • Dicionário de Pastas e agrupamentos – SXA 
  • Dicionário de consultas padrões – SXB
  • Dicionário de grupo de campos – SXG
  • Help e help de campos
  • Tabela de strings de tradução de programas – arquivos .CH
  • Menus do sistema

As chamadas do REST deverão ser organizadas da seguinte forma

MétodoURIMetadado
PUT/questionDicionário de perguntas
PUT/tableDicionário de tabelas
PUT/fieldDicionário de campos
PUT/genericTableTabelas genéricas
PUT/parameterDicionário de parâmetros
PUT/folderDicionário de pastas e agrupamentos
PUT/lookupDicionário de consultas padrão

PUT

/fieldGroupDicionário de grupos de campos
PUT/helpHelp de campo
PUT/programTextStrings de programas
PUT/menuMenus do sistema


Exemplo de como deverá ser composta uma URL: http://<servidor>:<porta>/rest/atusx/v1/<URI>

O v1 descrito na URL da API se refere a sua versão. Esta poderá mudar caso haja novas implementações na API.

 Todos os métodos REST deverão receber um JSON no corpo da mensagem que deverá conter as seguintes informações:

  • version: Versão do dicionário no AtuSX (parâmetro não obrigatório)
  • project: Código do projeto no AtuSX (parâmetro não obrigatório)
  • package: Código do pacote no AtuSX (parâmetro não obrigatório)

  • key: Array contendo os valores que representam a chave da tabela de destino no AtuSX.
    Esta opção poderá conter os seguinte valores:
URIValoresExemplo de preenchimento
/question[Grupo de Perguntas, ID do filtro padrão, Ordem do Pergunte, País]"key":["ABSENT","","01","BRA"]
/table[Alias da tabela, País]"key":["SA1","BRA"]
/field[Nome do campo, País]"key":["A1_NOME","BRA"]
/genericTable[Código da tabela, Chave da Tabela, País]"key":["00","01","BRA"]
/parameter[Nome do parâmetro, País]"key":["MV_1DUP","BRA"]
/folder[Alias da tabela, Ordem da Folder, Grupo da Folder]"key":["SA1","1",""]
/lookup[Código da SXB, Tipo da consulta padrão, Sequencia, Coluna, País]"key":["A2A","1","01","DB","BRA"]
/fieldGroup[Código do grupo, País]"key":["001","BRA"]
/help[Nome do help, País]"key":[".A014NOPR.","BRA"]
/programText [ Nome do fonte, Código da String, País]"key":["FATA010.CH","STR0001","BRA"]
/menu[Módulo, Função, País] ou [Código do menu]"key":["02","MATA065","RUS"] ou "key":["0000000116"]


Observação: Para o campo País do Menu, sempre é considero o país informado (para menus localizados) e caso não seja encontrado também o país * (para menus do tipo ALL).

 
Lista de possíveis países:

CódigoSiglaDescrição
1ALLTodos
2BRABrasil
3ARGArgentina
4EUAEstados Unidos
5CHIChile
6COLColômbia
7VENVenezuela
8MEXMéxico
9PORPorto Rico
10PARParaguai
11URUUruguai
12PERPeru
13COSCosta Rica
14DOMRep. Dominicana
15EQUEquador
16PANPana
17BOLBolívia
18SALEl Salvador
19PTGPortugal
20ANGAngola
21HAIHaiti
22TRITrinidad e Tobago
23PADPadrão
24AUSAustrália
25RUSRussia
Informações
titleObservação

Sempre opte por traduzir um campo usando um código de país diferente de ALL, internamente a API fará a busca usando o país especificado, caso não consiga localiza-lo fazemos uma segunda busca usando o país ALL.

 

 

  • property: Mnemônico que representa alguma coluna específica da tabela que será atualizada.
    Os valores possíveis para esse parâmetro são:

    URIValores
    /questiondescription, definition1, definition2, definition3. definition4, definition5
    /tabledescription
    /fieldtitle, description, options
    /genericTabledescription
    /parameterdescription1, description2, description3
    /folderdescription
    /lookupdescription
    /fieldGroupdescription
    /helpproblemtext, solutiontext
    /programTexttext
    /menutext, key
  • idiom: Idioma no qual se deseja incluir o temo traduzido. A lista de possíveis valores para esse parâmetro são: pt-br (português do Brasil), pt (português de Portugal), en (ingles), es (espanhol), ru (russo).
  • value: Valor traduzido

 

O JSON deverá ser montado seguindo o seguinte modelo:

Bloco de código
languagejs
titleModelo do JSON
linenumberstrue
[
	{
		"version" : "<AtuSX version -non obligatory->",
		"project" : "<AtuSX project -non obligatory->",
		"package" : "<AtuSX package -non obligatory->",
		"key" : [
			<Index Keys separate by ",">
		],
		"property" : "<Field to update>",
		"idiom" : "<pt-br, pt, en, es, ru>",
		"value" : "<Tranlated term>"
	},
	...
]


Exemplo de JSON formatado com valores reais para alterações de registros de SX1:

URI: /atusx/v1/question

Bloco de código
languagejs
titleExemplo de JSON preenchido
[
	{"version":"","project":"","package":"","key":["ABSENT","","01","RUS"],"property":"description","idiom":"ru","value":"?????? ????"},
	{"version":"","project":"","package":"","key":["ABSENT","","01","RUS"],"property":"definition1","idiom":"ru","value":"??"},
	{"version":"","project":"","package":"","key":["ABSENT","","01","RUS"],"property":"definition2","idiom":"ru","value":"???"}
]

 

De modo geral o JSON enviado deverá ser um array onde cada linha será correspondente a um UPDATE na tabela do AtuSX. Cada item do array deverá ter todas as informações necessárias para a localização do registro que será atualizado e o valor a ser incluído.

Autenticação

A principio utilizaremos autenticação HTTP Basic.

Erros e Validações

A própria API deverá possuir tratamento para diversos erros nas requisições. Segue a lista dos principais erros tratados:

  • Problema na estrutura do JSON.
  • Não preenchimento da tag Key.
  • Não preenchimento da tag Property.
  • Não preenchimento da tag Idiom.
  • Não preenchimento da tag Value.
  • Não preenchimento de um idioma válido (o conteúdo deve ser: pt-br, pt, en, es ou ru).
  • Conteúdo da tag Property ser inválido.
  • Tamanho do array passado na tag Key difere do tamanho da chave de índice correspondente.
  • Registro não pode ser encontrado.

Casso seja passado mais de um JSON pra ser processado de uma só vez, o erro deverá retornar qual posição do array apresentou erro. Porém, neste caso, todos os JSONs anteriores terão sido processados e o processo será abortado ao localizar um erro.


 

API - Get

Criação da API para poder recuperar os valores que precisam ser traduzidos baseados em um idioma de referência, ou seja, a API deverá receber o idioma para o qual se deseja traduzir e o idioma de referencia, o JSON resultante da busca retornará o texto do idioma de referência para ser enviado para tradução.

As validações dos Gets deverão ser as mesmas do Put (descritas no item Erros e Validações) assim como a autenticação (descrita no item Autenticação).

As chamadas disponíveis para os Gets também serão as mesmas do Put

 
MétodoURIMetadado
GET/questionDicionário de perguntas
GET/tableDicionário de tabelas
GET/fieldDicionário de campos
GET/genericTableTabelas genéricas
GET/parameterDicionário de parâmetros
GET/folderDicionário de pastas e agrupamentos
GET/lookupDicionário de consultas padrão

GET

/fieldGroupDicionário de grupos de campos
GET/helpHelp de campo
GET/programTextStrings de programas
GET/menuMenus do sistema

 

A chamada dos Gets deverão ser complementadas com a seguinte query string:

Idiom=<Idioma a ser traduzido>&RefIdiom=<Idioma de referência>&Country=<País a ser traduzido>&RefCountry=<País de referência>&Filter={<Array com os filtros>}&Page=<Página a ser retornada>&MaxPerPage=<Número de registros por página>&AllRegs=<1=Retorna tudo, 0=Apenas pendente de tradução | Padrão=0>

 

Os filtros terão as seguintes opções para cada Get:

URIValoresExemplo de preenchimento
/question{Grupo de Perguntas, ID do filtro padrão, Ordem do Pergunte}Filter={"ABSENT","","01"}
/table{Alias da tabela}Filter={"SA1"}
/field{Nome do campo}Filter={"A1_NOME"}
/genericTable{Código da tabela, Chave da Tabela}Filter={"00","01"}
/parameter{Nome do parâmetro}Filter={"MV_1DUP"}
/folder{Alias da tabela, Ordem da Folder, Grupo da Folder}Filter={"SA1","1",""}
/lookup{Código da SXB, Tipo da consulta padrão, Sequencia, Coluna}Filter={"A2A","1","01","DB"}
/fieldGroup{Código do grupo}Filter={"001"}
/help{Nome do help}Filter={".A014NOPR."}
/programText {Módulo ao qual a string pertence, Programa ao qual a string pertence, Código da String}Filter={"SIGAFAT","FATA010.CH","STR0001"}
/menu{Código do menu}Filter={"SIGAFAT"}

 

Exemplo de chamada:

Nesta chamada serão retornados apenas as strings a serem traduzidas, contidas no FATA010.CH

http://localhost:8090/rest/atusx/v1/programText?Idiom=ru&RefIdiom=pt-br&Country=rus&RefCountry=bra&Filter={,"FATA010.CH"}&Page=1&MaxPerPage=50&AllRegs=0

O JSON de resposta contém os seguintes dados:

  • Values = Valores a serem traduzidos, estes já são acompanhados de seus mnemonicos
  • Recno = recno do registro
  • Package = pacote do registro no AtuSX
  • Project = projeto do registro no AtuSX
  • Key = chave única do item
  • Idiom = idioma de referência
  • Version = versão do registro no AtuSX

 

{
"values": 
{
"TEXT": ""Processo de Venda" "
}
-
"recno": 30795
"package": " "
"project": " "
"key": 
[3]
0:  982
1:  "STR0001"
2:  "ALL"

"idiom": "POR"
"version": "000001"
}
1:  
{
"values": 
{
"TEXT": ""Pesquisar" "
}
-
"recno": 30796
"package": " "
"project": " "
"key": 
[3]
0:  982
1:  "STR0002"
2:  "ALL"
"idiom": "POR"
"version": "000001"
}
. . .
Informações
titleAtenção

O número de registros por página pode impactar muito na velocidade de retorno da API, portanto, caso o tempo de resposta esteja muito alto, tente diminuir esse valor.

 

 



 


 

 

 

 

 

 

 Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico.