Histórico da Página

Tempo aproximado para leitura: 00 min

01. Apresentação

Este documento tem por objetivo apresentar as responsabilidades dos adapters de envio , juntamente com os requisitos de software e boas práticas necessárias para o correto desenvolvimentode Mensagens Padronizadas TOTVS.

02. Responsabilidades

O adapter Os Adapters de envio de mensagens é responsável por executar, dentre outras funções acessórias, as funções e os padrões listados abaixo.

Padrões de integração (EAI Patterns)

Os padrões de desenvolvimento de integração listados abaixo são os principais para este contexto. É aconselhável o estudo dos demais padrões, sendo melhor descritos no site Enterprise Integration Patterns e outras referências bibliográficas.

Funções principais

As funções listadas abaixo são executadas utilizando os padrões de desenvolvimento necessários.

1. Tr

De forma superficial podemos analisar os adapters de envio como responsáveis, dentre outras tarefas acessórias, pela transformação do dado original e o pela transformação.

Os adapters de envio são responsáveis por fazer a transformação do dado original para o formato de Mensagem Padronizada TOTVS definido.

02.01. Análise de compatibilidade

A análise de compatibilidade do cliente com o EAI 2.0 deve ser realizada pelo consultor de implantação ou analista de suporte, que deve considerar as características:

1. 1. Todos os pacotes de integração utilizados pelo cliente devem estar disponíveis no EAI 2.0
   2. Caso haja planejamento de implantação de novos pacotes de integração, deve-se garantir que estes estejam disponíveis no EAI 2.0 até o prazo da implantação pois a conversão da base de dados é irreversível
   3. Verificar se o cliente possui customizações em suas Transformações XSLT ou nos SourceCodes
      1. Todas as customizações de integração do EAI 1.0 deverão ser re-codificadas pois o modelo de customização do EAI 2.0 não é retro-compatível.

02.02. Script de liberação

Caso após a análise acima seja constatado que o cliente é compatível com o EAI 2.0, deve-se solicitar ao suporte o script de liberação de acesso ao conversor. Sem a execução deste script o menu de acesso não é invisível ao cliente.

02.03. Caminho do menu

O processo de conversão está disponível no contexto de integrações, na árvore de menus de Mensagem Única.

Image Removed 

03. Processo de conversão

O processo de conversão passa por 3 passos, melhor descritos nas sub-sessões a seguir.

03.01. Avisos e confirmação

A primeira etapa do processo de conversão é declarar-se ciente dos riscos e procedimentos de segurança.

 Image Removed

Ao passar do primeiro para o segundo passos o conversor tentará obter automaticamente (vide imagem abaixo) a informação do SourceApplication de cada pacote integrado a partir do envio de uma mensagem única WhoIs para o WebService parametrizado no pacote.

Image Removed

Logo após a consulta automática será apresentada a tela de parametrização da conversão, disponibilizando a lista de integrações a serem convertidas e a parametrização de mensagens a migrar para as novas tabelas.

Image Removed

Podemos observar que na imagem acima o pacote de integração não teve seu SourceApplication identificado automaticamente, devendo assim ser parametrizado de forma manual através do botão "Atualizar por Sistema Integrado".

O SourceApplication pode ser identificado a partir de uma Mensagem Única trafegada via EAI 1.0, copiando o conteúdo de uma Tag de mesmo nome.

Image Removed

A rotina de conversão não migrará mensagens com sucesso para a nova estrutura de tabelas, ficando a cargo do consultor no momento da conversão definir se deve-se ou não importar as mensagens de erro. É aconselhável que todas as análises do ambiente 1.0 sejam realizadas previamente, tornando assim a conversão das mensagens de erro desnecessárias.

03.03. Execução dos conversores por pacote de integração

Após finalizar da conversão por parte do EAI (dados de integração) serão executados os processos de conversão específicos de cada pacote de integração.

A ocorrência de erro em um dos processos por pacote de integração não fará com que a conversão por parte do EAI seja desfeita, ficando a cargo do consultor responsável pela conversão realizar os ajustes necessários e executar novamente o processo em questão.

04. Dados convertidos

O processo de conversão realiza a consolidação e migração de dados das tabelas do EAI 1.0 para o EAI 2.0.

Segue abaixo os dados trabalhados pelo conversor padrão do EAI:

1. 1. Conversão dos pacotes de integração
      1. Os pacotes de integração são convertidos em Aplicativos e Pacotes Instalados, conforme descrito no documento de Entidades Relacionadas.
   2. Conversão dos Mapas de integração para a tabela de Rotas.
   3. Cópia das informações de De-Para para a nova tabela.
   4. Cópia das informações de mensagens trafegadas para a nova estrutura de tabelas
      1. A cópia ou não destas informações depende da parametrização apresentada na sessão 03.02.
   5. Conversão de parâmetros e execução de scripts de conversão por transação
      1. São realizados procedimentos necessários para compatibilização entre o comportamento de adapters do EAI 1.0 com os novos adpters do EAI 2.0.
      2. Exemplo: O adapter de Centro de Custo possuía três versões diferentes que utilizavam três parâmetros diferentes para definir se utiliza código auto-incremental. O adapter do EAI 2.0 padronizou estes três parâmetros em um só e o conversor é responsável por gerenciar esta unificação.

05. Inclusão de novos pacotes ou transações

Durante os projetos de migração dos pacotes de integração do EAI 1.0 para o EAI 2.0 podem surgir necessidades específicas de adapters ou destes pacotes de integração. Estas necessidades devem ser analisadas e ter suas regras de negócio implementadas na respectiva sessão do conversor.

Os fontes do conversor estão disponíveis no projeto RM.EAI.TotvsMessage.Conversor.Server e as sub-sessões a seguir apresentam os pontos de desenvolvimento para cada necessidade.

05.01. Conversão de parâmetros de adapter

Este ponto de desenvolvimento deve ser utilizado para implementação de ajustes de base de dados relacionados a um adapter específico.

O fonte com o conversor do adapter deve seguir as regras citadas abaixo:

são responsáveis por preparar os dados a serem enviados, gerando uma BusinessMessage no padrão definido para esta, e processar a ResponseMessage retornada pelo sistema integrado, utilizando para isso os corretos padrões de desenvolvimento.

O diagrama abaixo apresenta de forma macro a série de eventos que ocorrem durante o processamento de uma mensagem de envio, exemplificando com a origem em DataServer mas esta pode ocorrer nos Subscribers, Process ou qualquer outro objeto de negócio.

Principais funções do adapter de envio

1. Gerar o conteúdo de negócio da mensagem a enviar (BusinessContent).
   1. O adapter é responsável por implementar os padrões apresentados anteriormente, transformando o formato do dado original, enriquecendo ou empobrecendo o mesmo, além de realizar as validações necessárias.
   2. Após o adapter encaminhar ao EAI o dado de negócio (BusinessContent), todo o fluxo de envelopamento, salvamento na fila de mensagens e envio ao destinatário é de responsabilidade do EAI.
2. Transformar e/ou processar as informações de negócio da resposta (ReturnContent).
   1. Em integrações para consulta de dados a mensagem de resposta deve ser transformada do formato da Mensagem Padronizada TOTVS para o modelo de retorno, esperado pelo módulo que originou a mensagem.
      1. Ex.: Mensagens de consulta de informações devem transformar o dado recebido antes de encaminhar para o módulo de consulta.
   2. Caso a mensagem trafegada demande algum processamento de responsabilidade da camada de integração, este deve ser implementado no método correspondente do adapter.
      1. Ex.: Mensagens de cadastro devem ter o De-Para armazenado na base de dados.
      2. Ex2.: Mensagens assíncronas que devam desbloquear o registro no momento do retorno de sucesso.

03. Implementação de um adapter de envio

Para que uma classe seja um adapter de envio, deve-se atender aos pré-requisitos listados abaixo e realizar as funções de integração listadas anteriormente.

Pré-requisitos

1. Implementar a interface IAdapterSend, implementando em cada método a sua respectiva responsabilidade, internamente a um projeto cuja Dll gerada siga o padrão "RM.*.TotvsMessage.Adapter.dll".

   1. InitializeAdapter - Método responsável pela inicialização do Adapter, recebendo o contexto de execução por referência.

   2. CanExecute - Método que permite ao adapter realizar verificações e informar se a mensagem deve ser processada, ignorada ou gerar exceção.

   3. Prepare - Método responsável por retornar ao EAI o BusinessContent a ser enviado ao destinatário, juntamente com outras demandas específicas de negócio.

   4. ProcessResponseMessage - Método responsável por processar os dados retornados pelo aplicativo integrado, como atualizar algum campo de controle ou transformar o dado em caso de consultas, como esta mensagem.

2. Decorar a classe do adapter com o atributo "AdapterAttr".

   1. O atributo deve receber as informações obrigatórias, como nome da mensagem, versão, descrição e tipo (event/request).

3. Implementar as classes de modelo referentes ao BusinessContent e ao ReturnContent da Mensagem Padronizada TOTVS, que serão utilizadas na serialização e deserialização das mensagens.

4. As classes de modelo devem ser decoradas com o atributo "MessageContentTypeAttr" informando os atributos, descritos abaixo.
   1. TransactionName - Nome da transação referente a este modelo.
   2. MajorVersion - Versão cheia da mensagem. 
      1. Exemplo: Versão 1.003 possui MajorVersion 1. 
      2. Exemplo 2: Versão 3.023 possui MajorVersion 3.
   3. MessageType -  Tipo da transação a ter seu conteúdo de negócio serializado/deserializado utilizando esta classe (BusinessMessage ou ResponseMessage).

Código Fonte

using RM.Eai.TotvsMessage.Intf;
using RM.Eai.TotvsMessage.IService;
using RM.Eai.TotvsMessage.Lib;
using RM.Lib;
using System.Collections.Generic;
using System.Data;

namespace RM.Eai.TotvsMessage.Adapter
{
  [AdapterAttr(typeof(Properties.Resources),nameof(Properties.Resources.sEaiCaptionWhoIs), "WHOIS", "1.000", SubTypeEnum.teRequest)]
  public class WhoIs_Send_1000 : IAdapterSend
  {
    #region Properties
    private EAIAdapterContext AdapterContext { get; set; }
    #endregion 

    /// <summary>
    /// Método de inicialização do Adapter.
    /// </summary>
    /// <param name="adapterContext">Contexto de execução do Adapter</param>
    public void InitializeAdapter(EAIAdapterContext adapterContext)
    {
      AdapterContext = adapterContext;
    }

    /// <summary>
    /// Método responsável por informar ao EAI se a mensagem deve ser processada, ignorada ou gerar exceção.
    /// </summary>
    /// <param name="parms">Parametros</param>
    /// <returns>Retorno</returns>
    public EAICanExecuteSendResult CanExecute(EAICanExecuteSendParams parms)
    {
      //Não existe condicional, sempre permitindo enviar.
      return new EAICanExecuteSendResult() { CanExecute = EAICanExecuteEnum.csEnviar };
    }

    /// <summary>
    /// Método responsável por transformar os parâmetros de entrada no BusinessContent a ser enviado
    /// </summary>

    /// <param name="

parms"

>Parâmetros 

originais</param>
    

/// 

<returns>Resultado 

do método de preparação, com o Objeto BusinessContent</returns>
    public EAIPrepareSendResult 

Prepare(

EAIPrepareSendParms parms)
    {
  

  EAIPrepareSendResult result = 

new EAIPrepareSendResult();
      

      //A mensagem 

de WhoIs não possui dados no BusinessContent
      result.BusinessContent = 

new WhoIsModel_V1_BusinessContent();

      return result;
    }

    /// <summary>
    /// Processa ReturnContent recebido, transformando no objeto no formato esperado pelo método chamador.
    /// </summary>
    /// <param name="parms">Parâmetros de entrada</param>
    /// <returns>Resultado</returns>
    public EAIProcessResponseMessageSendResult 

ProcessResponseMessage(EAIProcessResponseMessageSendParams parms)
  

 {
      EAIProcessResponseMessageSendResult result = new EAIProcessResponseMessageSendResult(parms.ResponseMessageItem);

      //Obtém o ReturnContent deserializado para o tipo 

definido
      WhoIsModel_V1_ReturnContent returnContent = (WhoIsModel_V1_ReturnContent)parms.ResponseMessageItem.ResponseMessage.ReturnContent.ReturnContentObj;

      //Converte lista de transações no tipo de retorno.
      EAIWhoIsResult listaTransacoes = new EAIWhoIsResult(AdapterContext.ContextItem.CurrentRoute.IdApp);

      

//Percorre todas as transações
      

foreach 

(WhoIsModel_V1_EnabledTransaction enabledTransaction in returnContent.EnabledTransactions)
      {
        EAIWhoIsTransaction transacao = new EAIWhoIsTransaction()
        {
          

ModoHabilitado = ConvertModoHabilitado(RMSConvert.ToString(enabledTransaction.Mode)),//DONOTLOCALIZE
        

  NomeMensagem 

= RMSConvert.ToString(enabledTransaction.Name),//DONOTLOCALIZE
        

  Versao 

= RMSConvert.ToString(enabledTransaction.Version)//DONOTLOCALIZE
   

     };
        

listaTransacoes.Add(transacao);
      }

     

Este ponto de desenvolvimento é reservado para ajustes específicos de um pacote de integração que devem ser executados na mesma transação dos scripts do EAI, como ajustes de roteamento e de parâmetros de integração.

Estes ajustes devem ser adicionados como uma sessão no método "ExecutarScriptsPacotes" da classe "EAIConverteEAI2", conforme exemplo de código abaixo.

 //Obtém o UUID da mensagem original
      listaTransacoes.BusinessMessageUUID = this.AdapterContext.ContextItem.Message.UUID;
      //Obtém o UUID da mensagem de resposta
      listaTransacoes.ResponseMessageUUID = parms.ResponseMessageItem.MessageInformation.UUID;

      //Adiciona no objeto de retorno
      result.Data = listaTransacoes;
      
      //Retorna o dado processado, no tipo de retorno esperado.
      

return 

result;
 

 }

    private EnabledModeEnum ConvertModoHabilitado(string Mode)
    {
  

switch (Mode.ToUpperInvariant())
      {
    

 case "SEND_ENABLED"://DONOTLOCALIZE
          return 

EnabledModeEnum.emSend;
        

case "RECEIVE_ENABLED"://DONOTLOCALIZE
         

 return EnabledModeEnum.emReceive;
        

case "BOTH_ENABLED"://DONOTLOCALIZE
          return 

EnabledModeEnum.emBoth;
        

default:
          

RMSException.Throw(string.Format(Properties.Resources.sEaiErroWhoIsModoInvalido, Mode));
         

 //O método acima gera exceção, mas o compilador não compreende.
  

      //A linha abaixo foi inserida para permitir 

compilação 

mas nunca será executada.
          

return 0;//EnabledModeEnum
      }
    }
  

05.03. Processos de conversão específicos por pacote de integração

Após finalizar a execução do processo de conversão do EAI são executadas também todas as actions de processos parametrizadas para os pacotes de integração convertidos. Este fluxo de execução deve ser utilizado na conversão de informações que necessitem de iteração do usuário, para processamentos de longa duração ou que devam ser executados fora da transação do conversor padrão.

}
}

using RM.Eai.TotvsMessage.IService;
using RM.Eai.TotvsMessage.Lib;
using System.Collections.Generic;

namespace RM.Eai.TotvsMessage.Adapter
{
  [System.SerializableAttribute()]
  [System.ComponentModel.DesignerCategoryAttribute("code")]
  [System.Xml.Serialization.XmlTypeAttribute(AnonymousType = true)]
  [System.Xml.Serialization.XmlRootAttribute(ElementName = "BusinessContent", IsNullable = false)]
  [MessageContentTypeAttr("WHOIS", 1, MessageTypeEnum.tmBusinessMessage)]
  public partial class WhoIsModel_V1_BusinessContent
  {
	//O BusinessContent da mensagem WhoIs não possui propriedades.
  }
}

using RM.Eai.TotvsMessage.IService;
using RM.Eai.TotvsMessage.Lib;
using System.Collections.Generic;

namespace RM.Eai.TotvsMessage.Adapter
{
  [System.SerializableAttribute()]
  [System.ComponentModel.DesignerCategoryAttribute("code")]
  [System.Xml.Serialization.XmlTypeAttribute(AnonymousType = true)]
  [System.Xml.Serialization.XmlRootAttribute(ElementName = "ReturnContent", IsNullable = false)]
  [MessageContentTypeAttr("WHOIS", 1, MessageTypeEnum.tmResponseMessage)]
  public partial class WhoIsModel_V1_ReturnContent
  {
    [System.Xml.Serialization.XmlArrayItemAttribute("Transaction", IsNullable = false)]
    public List<WhoIsModel_V1_EnabledTransaction> EnabledTransactions { get; set; } = new List<WhoIsModel_V1_EnabledTransaction>();
  }

  /// <remarks/>
  [System.SerializableAttribute()]
  [System.ComponentModel.DesignerCategoryAttribute("code")]
  [System.Xml.Serialization.XmlTypeAttribute(AnonymousType = true)]
  public partial class WhoIsModel_V1_EnabledTransaction
  {
    public string Mode { get; set; }
    public string Version { get; set; }
    public string Name { get; set; }
  }
}

Implementações de produto

Os times dos segmentos tiveram iniciativa de desenvolver classes base e auxiliares para executar ações comuns e assim aumentar a produtividade no desenvolvimento de adapters. Estas classes estão disponíveis no projeto "RM.EAI.TotvsMessage.Adapter", que mesmo estando na solution do EAI é de domínio e manutenção dos times de produto.

A forma de uso destas classes foi documentada pelo produto no link a seguir: Desenvolvimento - EAI 2.

04

1. Desenvolvimento do Processo
   1. Deve-se passar por todo o desenvolvimento padrão de um Processo da Framework RM, como o desenvolvimento do Form, ParamsProc, Process e a Action.
   2. Este processo deve conter todas as regras de negócio necessárias, bem como o tratamento de erros.
2. Adição da Action desenvolvida no retorno do método "GetProcessBeforeConvertEai2" do server "EAIConversorServer".
   1. Este é o método responsável por retornar a lista de Actions a serem executadas.

. Assuntos Relacionados

• Entidades Relacionadas ao EAI 2.0
  • 1. Entidades relacionadasdo EAI
• Documento técnico da criação do Conversor para EAI 2.0
  
  • DT_ConversorEAI1_EAI2
• Desenvolvimento de Adapters com as classes base dos segmentos.
  • Desenvolvimento - EAI 2