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 | DATASUL | Módulo | EAI |
Segmento Executor | Tecnologia | ||
Projeto1 | DEAI1 | IRM/EPIC1 | XML para JSON - Datasul |
Requisito/Story/Issue1 | DEAI1-1702 | Subtarefa1 | DEAI1-1967 |
Chamado/Ticket2 | |||
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
Descrever as alterações necessárias para que o EAI do Datasul suporte o envio e recebimento de mensagens conforme definido para o endpoint /totvseai/standardmessage/v1/contents.
Definição da Regra de Negócio
De acordo com a especificação do endpoint /contents,o Datasul deve ser capaz de receber e enviar o trecho equivalente ao BusinessContent de uma TOTVSMessage no formato JSON.
Para isso, devem ser suportados os seguintes métodos HTTP:
- GET: para recuperar entidades (individuais ou em lote);
- Individual: GET /totvseai/standardmessage/v1/contents/Carrier_2_000/95|12345.
- Lote: GET /totvseai/standardmessage/v1/contents/Carrier_2_000.
- POST: para incluir entidades (individuais, ou em lote) e executar requisições;
- Exemplo: POST /totvseai/standardmessage/v1/contents/Carrier_2_000
- Exemplo: POST /totvseai/standardmessage/v1/contents/Carrier_2_000
- PUT: para alterar entidades (individuais apenas);
- Exemplo: PUT /totvseai/standardmessage/v1/contents/Carrier_2_000/95|12345.
- Exemplo: PUT /totvseai/standardmessage/v1/contents/Carrier_2_000/95|12345.
- DELETE: para remover entidades (individuais apenas).
- Exemplo: DELETE /totvseai/standardmessage/v1/contents/Carrier_2_000/95|12345.
- Exemplo: DELETE /totvseai/standardmessage/v1/contents/Carrier_2_000/95|12345.
No fluxo de envio, de forma geral, tem-se o seguinte:
- O cliente envia um JSON para o endpoint /contents;
- A implementação do endpoint, na camada JAVA do Datasul, repassa o JSON para o Engine Progress;
- O Engine Progress, baseado no JSON recebido, e nos demais parâmetros da requisição,
- Determina o adapter que processará o conteúdo;
- Transforma o JSON recebido em objeto de negócio.
- O adapter recebe o objeto de negócio e o processa, gerando uma resposta que também está no formato de objeto de negócio;
- O Engine Progress recebe a resposta como objeto de negócio e a transforma em JSON.
- O endpoint, na camada Java, recebe o JSON de resposta e o devolve para o cliente.
Ajustes gerais
Na camada Java, será necessária a implementação da classe que suporta o processamento do endpoint /totvseai/standardmessage/v1/contents. Este endpoint deve prever os métodos citados acima e os query parameters relacionados. Nos links abaixo é possível verificar exatamente quais são os parâmetros:
- GET: Recuperar um lote de entidades e Recuperar uma entidade.
- POST: Submeter uma entidade e Submeter um lote de entidades.
- PUT: Alterar uma entidade.
- DELETE: Eliminar uma entidade.
Na camada Progress, será necessário implementar o programa que realizará o trabalho de converter o JSON em objeto de negócio, determinar o adapter e repassar o objeto para processamento. Este programa - eai/receiveContentJson.p - será chamado pelo endpoint implementado na camada Java.
Ajustes para suportar o método GET
Especificamente para o método GET, os adapters deverão implementar métodos que permitam buscar os dados a partir do Internal ID recebido no endpoint, para recuperar uma entidade específica, ou para recuperar um conjunto de entidades da transação e versão informados. Mantendo o padrão de construção do EAI Datasul, deve-se criar uma nova interface - IEntityRetrieverAdapter - que indicará ao adapter a necessidade de implementar o método retrieveEntityData. Ao realizar este método dentro do adapter, o desenvolvedor deverá implementar o tratamento de paginação e filtro requeridos pela especificação do método GET do endpoint.
Ajustes para suportar o método POST
Devido a natureza do formato anterior da mensagem padronizada, os adapters foram desenvolvidos para realizar o que se chama de "upsert". Ou seja, se uma mensagem recebida corresponder a um registro novo, ele será incluído. Se o registro existir, ele será modificado.
Entretanto, não há maiores alterações nos adapters existentes, para suportar o POST individual. O que requer modificação são as classes Helper, geradas a partir do XSD, que precisam implementar a nova interface IJSONSerializable. Entretanto, não está no escopo dessa especificação detalhar a modificação. Para todos os efeitos, considera-se que as classes Helper já estão preparadas para gerar conteúdo em JSON.
Em relação ao POST em lote, o suporte será implementado na fase do desenvolvimento da mensagem em lote.
Ajustes para suportar o método PUT
O suporte ao método PUT será idêntico ao método POST, respeitando o fato de que não há PUT para lotes.
Ajustes para suportar o método DELETE
Para eliminar uma entidade apenas com o Internal ID, será necessário implementar um novo método nos adapters, pois o método atual - processMessage() - requer uma TOTVSMessage, e o método DELETE não prevê nenhum corpo de mensagem, a partir do qual seja possível construir uma mensagem.
O método a ser implementado - deleteEntity - será exigido para os adapters que implementarem a interface IEntityRetrieverAdapter. Nele, o desenvolvedor deverá utilizar o Internal ID recebido para obter o registro que será eliminado.
Ajustes para o envio de mensagens para o endpoint /contents
Para o envio de mensagens destinadas ao endpoint /contents, será necessário a implementação de um novo canal - RESTChannel - o qual enviará a mensagem para a URL informada. Este canal será indicado no aplicativo de destino cadastrado.
Porém, é preciso definir sobre a necessidade de se cadastrar um aplicativo externo e suas transações para definir uma rota.
Lista de fontes
Abaixo os principais fontes que precisam ser ajustados ou criado. Durante o desenvolvimento, pode-se identificar outros mais. Os fontes já alterados pelo desenvolvimento inicial do suporte a JSON no Datasul não serão listados aqui mas são pré-requisito para o desenvolvimento:
- eai/receiveContentJSON.p (novo)
- com/totvs/datasul/eai/RESTChannel.cls (novo)
- com/totvs/datasul/eai/IBusinessContent.cls (alterado)
- com/totvs/datasul/eai/IEntityRetrieverAdapter.cls (novo)
- com/totvs/datasul/eai/IReturnContent.cls (alterado)
- com/totvs/datasul/eai/MessageContentHelper.cls (alterado)
Fluxo do Processo
Figura 1 - Fluxo geral de recebimento
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|