ER_DEAI1_Suporte ao endpoint contents no Datasul

Informações Gerais

   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
    
• PUT: para alterar entidades (individuais apenas);
  • 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.
    

 No fluxo de envio, de forma geral, tem-se o seguinte:

1. O cliente envia um JSON para o endpoint /contents;
2. A implementação do endpoint, na camada JAVA do Datasul, repassa o JSON para o Engine Progress;
3. O Engine Progress, baseado no JSON recebido, e nos demais parâmetros da requisição,
   
   1. Determina o adapter que processará o conteúdo;
   2. Transforma o JSON recebido em objeto de negócio.
      
4. 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;
5. O Engine Progress recebe a resposta como objeto de negócio e a transforma em JSON.
6. 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