Histórico da Página
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 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 regras de dependência – XXADicioná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étodo | URI | Metadado | |||
---|---|---|---|---|---|
PUT | /question | Dicionário de perguntas | |||
PUT | /table | Dicionário de tabelas | |||
PUT | /field | Dicionário de campos | |||
PUT | /genericTable | Tabelas genéricas | |||
PUT | /parameter | Dicionário de parâmetros | |||
PUT | /folder | Dicionário de pastas e agrupamentos | |||
PUT | /lookup | Dicionário de consultas padrão | |||
PUT | /??? | Dicionário de regras de dependência | PUT | /???fieldGroup | Dicionário de grupos de campos |
PUT | /help | Help de campo | |||
PUT | /programText | Strings de programas | |||
PUT | /menu | Menus 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 AtuSXAtuSX (parâmetro não obrigatório)
- package: Código do pacote no AtuSXAtuSX (parâmetro não obrigatório)
- key: Array contendo os valores que representam a chave da tabela de destino no AtuSX. (Mais adiante listaremos todos os valores possíveis para esse item).property: Mnemonico
Esta opção poderá conter os seguinte valores:
URI | Valores | Exemplo 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ódigo | Sigla | Descrição |
---|---|---|
1 | ALL | Todos |
2 | BRA | Brasil |
3 | ARG | Argentina |
4 | EUA | Estados Unidos |
5 | CHI | Chile |
6 | COL | Colômbia |
7 | VEN | Venezuela |
8 | MEX | México |
9 | POR | Porto Rico |
10 | PAR | Paraguai |
11 | URU | Uruguai |
12 | PER | Peru |
13 | COS | Costa Rica |
14 | DOM | Rep. Dominicana |
15 | EQU | Equador |
16 | PAN | Pana |
17 | BOL | Bolívia |
18 | SAL | El Salvador |
19 | PTG | Portugal |
20 | ANG | Angola |
21 | HAI | Haiti |
22 | TRI | Trinidad e Tobago |
23 | PAD | Padrão |
24 | AUS | Austrália |
25 | RUS | Russia |
Informações | ||
---|---|---|
| ||
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.
(Mais adiante listaremos todos os
item).
Os valores possíveis para esseparâmetro são:
URI Valores /question description, definition1, definition2, definition3. definition4, definition5 /table description /field title, description, options /genericTable description /parameter description1, description2, description3 /folder description /lookup description /fieldGroup description /help problemtext, solutiontext /programText text /menu text, key - idiom: Idioma no qual se deseja incluir o temo traduzido. (Mais adiante listaremos todos os valores possíveis para esse itemA 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 | ||||||
---|---|---|---|---|---|---|
| ||||||
[
{
"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 | ||||
---|---|---|---|---|
| ||||
[ {"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á um JSON correspondente a um UPDATE na tabela do AtuSX. Esses JSONs deverão 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.
<Regra de negócio é o que define a forma de fazer o negócio, o processo definido e/ou as regras que devem ser contempladas. Devem ser descritas restrições, validações, condições e exceções do processo. Caso necessário, incluir neste capítulo também regras de integridade que devem ser observadas no momento do desenvolvimento>.
<Na tabela abaixo informe quais são as rotinas envolvidas, o tipo de operação, a opção de menu e se necessário uma breve descrição das regras de negócio relacionadas a rotina>.
Rotina | Tipo de Operação | Opção de Menu | Regras de Negócio |
[ACAA040 – Parâmetros] | [Alteração] | [Atualizações -> Acadêmico-> Tesouraria] | - |
[ACAA050 – Negociação Financeira] | [Envolvida] | [Atualizações -> Acadêmico-> Tesouraria] | - |
[ACAA060 – Cadastro de Pedidos] | [Criação] | [Atualizações -> Acadêmico-> Cadastros] | - |
Exemplo de Aplicação:
- Criar o campo “% Mínimo Espécie” (AAA_PERESP) onde o usuário informará o % que o aluno pagará em dinheiro. Esse % poderá ser alterado durante a negociação.
- Criar o campo “Referência Mínima para Cálculo” (AAA_REFCAL) onde o usuário informará um dos 4 valores disponíveis para pagamento das mensalidades como a referência mínima para calcular o débito total do aluno.
- Criar o parâmetro MV_ACPARNE que definirá se as informações de “% Mínimo Espécie” e “Referência Mínima para Cálculo” serão obrigatórias.
- O parâmetro MV_ACPARNE deve ter as seguintes opções: 1=Obrigatório e 2=Opcional. Deve ser inicializado como opcional>.
Tabelas Utilizadas
- SE2 – Cadastro de Contas a Pagar
- FI9 – Controle de Emissão de DARF>.
Opcional
Protótipo de Tela
<Caso necessário inclua protótipos de telas com o objetivo de facilitar o entendimento do requisito, apresentar conceitos e funcionalidades do software>.
Protótipo 01
Opcional
Fluxo do Processo
<Nesta etapa incluir representações gráficas que descrevam o problema a ser resolvido e o sistema a ser desenvolvido. Exemplo: Diagrama - Caso de Uso, Diagrama de Atividades, Diagrama de Classes, Diagrama de Entidade e Relacionamento e Diagrama de Sequência>.
Opcional
Dicionário de Dados
Arquivo ou Código do Script: AAA – Negociação Financeira / *Versao=CP.2014.12_03*/
Índice | Chave |
01 | <FI9_FILIAL+FI9_IDDARF+FI9_STATUS> |
02 | <FI9_FILIAL+FI9_FORNEC+ FI9_LOJA+FI9_EMISS+FI9_IDDARF> |
03 | <FI9_FILIAL+FI9_FORNEC+ FI9_LOJA+FI9_PREFIX+FI9_NUM+FI9_PARCEL+FI9_TIPO> |
Campo | <AAA_PERESP> |
Tipo | <N> |
Tamanho | <6> |
Valor Inicial | <Varia de acordo com o tipo informado. Por exemplo, quando o campo “tipo” for date, neste campo pode ser informado uma data>. |
Mandatório | Sim ( ) Não ( ) |
Descrição | <Referência Mínima para Cálculo> |
Título | <Ref.Calc.> |
Picture | <@E999.99> |
Help de Campo | <Informar o % que o aluno pagará em dinheiro. Esse % poderá ser alterado durante a negociação> |
(Opcional)
Grupo de Perguntas
<Informações utilizadas na linha Protheus>.
Nome: FINSRF2
X1_ORDEM | 01 |
X1_PERGUNT | Emissão De |
X1_TIPO | D |
X1_TAMANHO | 8 |
X1_GSC | G |
X1_VAR01 | MV_PAR01 |
X1_DEF01 | Comum |
X1_CNT01 | '01/01/08' |
X1_HELP | Data inicial do intervalo de emissões das guias de DARF a serem consideradas na seleção dos dados para o relatório |
(Opcional)
Consulta Padrão
<Informações utilizadas na linha Protheus>
Consulta: AMB
Descrição | Configurações de Planejamento |
Tipo | Consulta Padrão |
Tabela | “AMB” |
Índice | “Código” |
Campo | “Código”; ”Descrição” |
Retorno | AMB->AMB_CODIGO |
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étodo | URI | Metadado |
---|---|---|
GET | /question | Dicionário de perguntas |
GET | /table | Dicionário de tabelas |
GET | /field | Dicionário de campos |
GET | /genericTable | Tabelas genéricas |
GET | /parameter | Dicionário de parâmetros |
GET | /folder | Dicionário de pastas e agrupamentos |
GET | /lookup | Dicionário de consultas padrão |
GET | /fieldGroup | Dicionário de grupos de campos |
GET | /help | Help de campo |
GET | /programText | Strings de programas |
GET | /menu | Menus 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:
URI | Valores | Exemplo 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 | ||
---|---|---|
| ||
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. |
(Opcional)
Estrutura de Menu
<Informações utilizadas na linha Datasul>.
Procedimentos
Procedimento |
|
|
|
Descrição | (Max 40 posições) | (Max 40 posições) | (Max 40 posições) |
Módulo |
|
|
|
Programa base |
|
|
|
Nome Menu | (Max 32 posições) | (Max 32 posições) | (Max 32 posições) |
Interface | GUI/WEB/ChUI/Flex | GUI/WEB/ChUI/Flex | GUI/WEB/ChUI/Flex |
Registro padrão | Sim | Sim | Sim |
Visualiza Menu | Sim/Não | Sim/Não | Sim/Não |
Release de Liberação |
|
|
|
Programas
Programa |
|
|
|
Descrição | (Max 40 posições) | (Max 40 posições) | (Max 40 posições) |
Nome Externo |
|
|
|
Nome Menu/Programa | (Max 32 posições) | (Max 32 posições) | (Max 32 posições) |
Nome Verbalizado[1] | (Max 254 posições) | (Max 254 posições) | (Max 254 posições) |
Procedimento |
|
|
|
Template | (Verificar lista de opções no man01211) | (Verificar lista de opções no man01211) | (Verificar lista de opções no man01211) |
Tipo[2] | Consulta/Manutenção/ Relatório/Tarefas | Consulta/Manutenção/ Relatório/Tarefas | Consulta/Manutenção/ Relatório/Tarefas |
Interface | GUI/WEB/ChUI/Flex | GUI/WEB/ChUI/Flex | GUI/WEB/ChUI/Flex |
Categoria[3] |
|
|
|
Executa via RPC | Sim/Não | Sim/Não | Sim/Não |
Registro padrão | Sim | Sim | Sim |
Outro Produto | Não | Não | Não |
Visualiza Menu | Sim/Não | Sim/Não | Sim/Não |
Query on-line | Sim/Não | Sim/Não | Sim/Não |
Log Exec. | Sim/Não | Sim/Não | Sim/Não |
Rotina (EMS) |
|
|
|
Sub-Rotina (EMS) |
|
|
|
Localização dentro da Sub Rotina (EMS) |
|
|
|
Compact[4] | Sim/Não | Sim/Não | Sim/Não |
Home[5] | Sim/Não | Sim/Não | Sim/Não |
Posição do Portlet[6] | 0 – Top Left 1 – Top Right 2 – Bottom Left 3 – Bottom Right | 0 – Top Left 1 – Top Right 2 – Bottom Left 3 – Bottom Right | 0 – Top Left 1 – Top Right 2 – Bottom Left 3 – Bottom Right |
Informar os papeis com os quais o programa deve ser vinculado |
|
|
|
Cadastro de Papéis
<O cadastro de papéis é obrigatório para os projetos de desenvolvimento FLEX a partir do Datasul 10>.
<Lembrete: o nome dos papeis em inglês descrito neste ponto do documento, devem ser homologados pela equipe de tradução>.
Código Papel | (máx 3 posições) |
Descrição em Português* |
|
Descrição em Inglês* |
|
[1] Nome Verbalizado é obrigatório para desenvolvimentos no Datasul 10 em diante.
[2] Tipo é obrigatório para desenvolvimento no Datasul 10 em diante
[3] Categorias são obrigatórias para os programas FLEX.
[4] Obrigatório quando o projeto for FLEX
[5] Obrigatório quando o projeto for FLEX
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|