A camada do EAI Protheus

          A camada do EAI Protheus compreende uma série de ferramentas para auxiliar o envio e recebimento de mensagens e o seu gerenciamento.

Schedule Protheus

          O Schedule Protheus é utilizado para o envio e recebimento de mensagens do EAI no modelo Assíncrono. Mensagens do tipo síncrona não necessitam de schedule Protheus configurado.
          A fila de integrações do EAI (tabela XX3) guarda as mensagens enviadas e recebidas pelo EAI Protheus.
Para entender os termos e a configuração do Schedule Protheus consulte o artigo disponível no TDN clicando aqui.

 Status das mensagens no EAI Protheus

Atualmente, existem 7 status disponíveis para uma mensagem na fila do EAI Protheus:

• Aguardando execução - A mensagem está na fila do EAI e ainda não começou a execução (o seu envio ou o seu processamento pelo adapter);
• Executando - A mensagem está sendo enviada para o sistema integrado ou a mensagem recebida está sendo processada;
• Finalizada - A mensagem foi processada sem erros ou foi enviada sem erros;
• Falhou - Houve um erro no envio da mensagem ou no seu recebimento;
• Bloqueado - A mensagem foi bloqueada para execução pelo usuário;
• Não entregue - A mensagem não foi enviada para o destino (ou ainda, ocorreu um erro por time-out e não foi possível definir se a mensagem foi recebida e processada);
• Recusada - A mensagem foi recusada por conter divergências entre a mensagem e o seu XSD.
  
  

Status das mensagens na fila do EAI Protheus

Envio de mensagens Assíncronas

          Quando um evento de integração é disparado no Protheus, o adapter cadastrado é chamado para executar o envio da mensagem.  A rotina de processamento gera o XML de integração, e esta mensagem é gravada na tabela XX3 (a fila de mensagens do EAI Protheus). De acordo com a recorrência cadastrada para a rotina de transmissão das mensagens do EAI esta fila é lida e os registros que se encontram em condições de envio são enviados para o sistema receptor. Um registro está em condições de envio se respeitar as condições a seguir:

• A mensagem seja do tipo assíncrona e o número de tentativas de envio para o sistema receptor seja menor que 4;
• A Mensagem esteja com o status de 'aguardando execução','falhou','Não entregue' ou 'Recusada'.

          Uma rotina que já tenha o seu número de execuções maior ou igual a 4 somente será reprocessada caso exista intervenção do usuário, através do botão 'tentar novamente'. Desta maneira, o número de tentativas da mensagem é reiniciado e o status da mensagem retorna para 'Aguardando execução'. Este processo somente pode ser realizado em mensagens assíncronas e que estejam nos status de 'aguardando execução','falhou','Não entregue' ou 'Recusada'.

Detalhe da barra de botões da interface do EAI, no Schedule Protheus. O primeiro botão destacado é o botão de 'tentar novamente'.

          Para que o envio das mensagens assíncronas seja realizado, é necessário que seja realizado o cadastramento, no Schedule Protheus, da rotina FWEAI. Esta rotina é responsável pelo envio e recebimentos das mensagens na fila do EAI. Caso necessário, pode ser realizado o agendamento da rotina FWEAISEND. Esta rotina é exclusiva para o envio das mensagens da fila do EAI. O agendamento desta rotina é realizado por Empresa cadastrada no sistema. No envio da mensagem, um canal de comunicação é aberto com o webservice do produto integrado, e esta comunicação é encerrada após o recebimento  da mensagem de retorno (no caso das Mensagens Única Totvs, após o recebimento da  ReceiptMessage, indicando que que o processo ocorreu corretamente) ou por timeout (mensagem com status de falha).

     Posteriormente, o outro sistema integrado poderá gerar uma outra mensagem de resposta (no caso das Mensagens Única Totvs, será gerada uma ResponseMessage) após o processamento da mensagem. Esta mensagem será gravada na fila do EAI e seu comportamento será idêntico ao destacado no tópico recebimento de mensagens assíncronas.

Envio de mensagens assíncronas para webservices com erro

     Existe um mecanismo de controle que interrompe momentaneamente o envio de mensagens da fila do EAI. Este mecanismo verifica se o erro recebido ao enviar uma mensagem assíncrona é decorrente de um erro de regra de negócios (valor inválido de código de registro, registro duplicado, etc.) ou se é um erro decorrente da conexão com o servidor web (servidor web não encontrado, servidor web com erro, etc.). Neste último caso, não faria sentido enviar as outras mensagens para este serviço, pois todas as mensagens retornariam com erro, o que iria acarretar em lentidão no processo e , após 4 tentativas, no reprocessamento manual das mensagens pelo usuário.

     Desta maneira, quando uma das rotinas de envio do EAI é chamada pelo Schedule Protheus (a FWEAI ou a FWEAISEND), as mensagens são enviadas uma a uma para o outro sistema. Caso seja retornado um erro de conexão (uma conexão HTTP com status diferente de 200) o EAI faz o seguinte tratamento:

• Se a mensagem com erro for uma mensagem direcionada para o TOTVS ESB, a fila do EAI é filtrada, e as mensagens com destino para o TOTVS ESB não são mais enviadas neste momento pelo schedule;
• Se a mensagem com erro não é direcionada para o TOTVS ESB (direcionada para o canal EAI), a fila do EAI será filtrada da seguinte maneira:
  • Se esta mensagem possuir rota de mensagens (roteamento Protheus) nenhuma mensagem com destino para aquele par de Produto e Aplicação de origem serão enviados;
  • Se esta mensagem não possuir rota, nenhuma mensagem sem rota será enviada neste momento;

Estes eventos se acumulam. Exemplo:

Suponha uma fila do EAI com quatro mensagens aguardando execução. Duas mensagens com destino ao TOTVS ESB e duas mensagens com canal de envio EAI sem roteamento. Ao enviar a primeira mensagem do ESB, este retorna um erro de conexão. A próxima mensagem a ser enviada então será a mensagem com canal de envio EAI (a outra mensagem para o ESB será desconsiderada para envio). Se esta mensagem para o EAI também retornar com erro o agendamento finaliza, como  se todas as mensagens tivessem sido enviadas (a próxima mensagem para o EAI será desconsiderada).

     Quando a rotina do EAI agendada no Schedule for executada novamente (a FWEAI ou a FWEAISEND) o processo é reavaliado outra vez (envia, e em caso de erro, verifica se é um erro de webservices).

     Lembrando que uma mensagem com 4 tentativas não é enviada novamente enquanto não houver o reprocessamento manual da mesma.

Recebimento de mensagens Assíncronas

          Neste tipo de transação uma mensagem é enviada de outro sistema para o EAI Protheus. A camada de Webservices realiza a gravação desta mensagem na tabela XX3 (fila de mensagens do EAI Protheus). De acordo com a recorrência cadastrada para a rotina de recebimento esta fila é lida e as respectivas rotinas de processamento das mensagens são disparadas. Para que uma rotina tenha o seu processo de recebimento iniciado ela deve estar em condições de recebimento, respeitando os seguintes pontos:

• A mensagem seja do tipo assíncrona e o número de tentativas de processamento seja menor que 4;
• A Mensagem esteja com o status de 'aguardando execução' ou 'falhou'.

          Uma rotina que já tenha o seu número de execuções maior ou igual a 4 somente será reprocessada caso exista intervenção do usuário, através do botão 'tentar novamente'. Desta maneira, o número de tentativas da mensagem é reiniciado e o status da mensagem retorna para 'Aguardando execução'. Este processo somente pode ser realizado em mensagens assíncronas e que estejam nos status de 'Falhou' ou 'Bloqueado'. O detalhe deste botão pode ser visualizado na figura acima.
           Para que o recebimento das mensagens assíncronas seja realizado, é necessário que seja realizado o cadastramento, no Schedule Protheus da rotina FWEAI. Esta rotina é responsável pelo envio e recebimentos das mensagens na fila do EAI. Caso necessário, pode ser realizado o agendamento da rotina FWEAIRECE. Esta rotina é exclusiva para o recebimento das mensagens da fila do EAI. O agendamento desta rotina é realizado por Empresa cadastrada no sistema.

          Se uma mensagem assíncrona encontra-se na fila e ela for uma mensagem recebida  pelo Protheus o adapter é chamado para processamento da mesma .Nas Mensagens Única TOTVS essa Receive pode ser do tipo Business (uma mensagem de algo a ser processado no Protheus) ou ainda uma ResponseMessage (uma mensagem de resposta de um evento enviado a outro ERP). Caso essa mensagem seja uma Business, será realizado o seu processamento e após isto, será gravada uma nova mensagem na fila do EAI Protheus com a resposta para o outro sistema.

Rotinas de EAI disponíveis para agendamento no Schedule Protheus

          Estão disponíveis para agendamento no Schedule Protheus as seguintes rotinas do EAI:

• FWEAI: - Rotina de envio e recebimento de mensagens do EAI Protheus. Quando agendada, esta rotina executa dois passos:
  
  
  1. Inicia o processamento das mensagens recebidas na fila do EAI Protheus;
     
     
  2. Inicia o envio das mensagens que estão na fila do EAI Protheus.

          O processo de envio somente é inicializado após o término do processamento de todas as mensagens recebidas que estão na fila em condições de serem processados.

• FWEAIRECE: - Rotina de recebimento das mensagens do EAI Protheus. Quando configurada esta rotina inicia o processamento das mensagens disponíveis para processamento na fila do EAI Protheus.
  
  
• FWEAISEND: - Rotina de envio das mensagens do EAI Protheus. Quando configurada esta rotina inicia o envio das mensagens disponíveis na fila do EAI Protheus.
  
  
• FWEAICLEAR: - Rotina de limpeza da fila do EAI Protheus. Quando configurada esta rotina faz a deleção física de todos os registros com o status de 'finalizado', na fila do EAI. Esta limpeza é importante devido ao volume de dados que a tabela XX3 (fila do EAI Protheus) pode atingir.

Envio de mensagens síncronas

          No envio de mensagens síncronas o comportamento do EAI é mais simples. Após iniciar a integração, um canal de comunicação com o webservice do produto integrado é aberto, e a mensagem enviada no mesmo momento. A comunicação é encerrada após o recebimento da resposta ou por timeout.

  Cadastro de Adapters no Configurador Protheus

          As rotinas que são responsáveis por realizar o processamento das mensagens enviadas e recebidas são cadastradas no ambiente do Configurador Protheus. Em Ambiente/Schedule/Adapter E.a.i, no Cadastro de Adapter EAI (APCFG20) é possível incluir, alterar e excluir um adapter no Protheus.

Tela do browse do Cadastro de Adapters

          O adapter APCFG060 é nativo do próprio EAI Protheus, e seu cadastro é realizado automaticamente. Mesmo que este adapter seja excluído pelo usuário ele será recriado automaticamente. Este adapter é utilizado nas mensagens de EAI que utilizam a arquitetura da Mensagem Única TOTVS.

 Parte superior do Cadastro de Adapters no Protheus

          São campos importantes deste cadastro:

• Mensagem Única (XX4_UNMESS) – Um combo que identifica se o adapter cadastrado é do tipo Mensagem Única TOTVS ou não.
  
  
• Rotina (XX4_ROTINA) – Identifica qual rotina no Protheus é a responsável por realizar o processamento da mensagem. Lembrando que o EAI Protheus não é o responsável pelo processamento da mensagem, esta é a rotina que irá realizar as execuções necessárias e validar a regra de negócio da mensagem trafegada. A regra para preenchimento deste campo é:
  
  
  • Campo Mensagem Única =Não – A rotina a ser cadastrada deve possuir a função Static Modeldef declarada. Para detalhes do funcionamento do Modeldef e MVC Protheus consulte o TDN, clicando aqui;
    
    
  • Campo Mensagem Única=Sim – A rotina trabalha com o conceito de Mensagem Única TOTVS. Neste caso, a rotina deverá possuir a função Static Integdef.
    
    
• Mensagem (XX4_MODEL) – O nome da mensagem que é processada por esta rotina. Nas mensagens que usam a arquitetura de Mensagem Única TOTVS deverá ser incluído neste campo o nome da mensagem acordado pelo comitê e utilizado para a transação em questão. Para as rotinas que não são desta arquitetura neste campo deverá ser incluído o nome do modelo de dados principal da rotina;
  
  
• Descrição (X4_DESCRI)– Descrição da mensagem. Utilizada para facilitar o entendimento do processo;
  
  
• Envia (XX4_SENDER) – Define se o adapter envia mensagens para outro sistema;
  
  
• Recebe(XX4_RECEIV) – Define se o adapter pode receber mensagens de outro sistema. Quando o Protheus recebe uma mensagem de outro sistema e este campo, para a mensagem em questão, está cadastrado como 'não', é retornado para o outro sistema que o adapter não está disponível;
  
  
• Método (XX4_METODO) – Define o método de envio da mensagem. Importante – O Método de processamento é sempre definido por quem envia a mensagem. Logo, independentemente do valor deste campo, uma mensagem recebida como síncrona será sempre processada como síncrona;
  
  
• Operação (XX4_TPOER) – Indica o tipo de operação utilizado na mensagem. Só é possível cadastrar uma mesma rotina mais de uma vez (até o limite de 2) caso possuam o tipo de operação diferente entre elas, e também diferente do tipo 'Todas'. A operação é validada no momento de envio do adapter. Desta maneira, ao alterar um registro no ERP e a condição do adapter for igual a 3=exclusão a integração não será ativada;
  
  
• Condição (XX4_EXPFIL) – Campo que pode receber uma expressão ou ainda uma função advpl. Em ambos os casos, é esperado um resultado lógico deste campo. Com um retorno.T. deste campo, o adapter é executado. Um retorno.F. indica que o adapter não deve ser executado naquele momento. Este campo é avaliado no envio das mensagens;
  
  
• Expressão SQL (XX4_EXPSQL) – Campo que pode receber uma expressão SQL. Esse filtro será executado juntamente com a condição do campo XX4_EXPFIL, caso esteja preenchido. Este campo é utilizado somente para o processo de carga inicial a fim de se ter um ganho de performance. Exemplo de um filtro utilizado no adapter FINA010 (Naturezas): EXISTS (SELECT A1_COD FROM  SA1010 WHERE  ED_CODIGO = A1_NATUREZ AND ED_COND = 'D'). OBS: O Filtro deve ser escrito no campo sem aspas; Para uso desse campo é necessário estar no release 12.1.2510 ou utilizar do FWRebuilIndex para sua criação;
  
  
• Compl. Recep. (XX4_LOADRE) – Este campo é utilizado para mensagens que não utilizam a arquitetura de Mensagem Única TOTVS. Neste campo deve ser informado uma rotina de processamento complementar para o processamento do XML recebido na mensagem. Esta rotina é chamada antes no ponto da gravação dos dados e somente para mensagens recebidas, porém depois das validações do modelo e recebe como parâmetros o modelo de dados e o XML (este passado por valor) recebido. Não é esperado retorno desta rotina e o xml não é alterado.
  
  
• Compl. Envio (XX4_LOADSE) – Rotina para complementar o envio das mensagens. Esta rotina é chamada antes do envio do XML e recebe como parâmetro o xml (passado por valor) que será enviado. Esta rotina não altera o xml que será enviado, somente é chamada para que o sistema possa realizar algum tratamento interno.
  
  
• Canal Envio (XX4_CHANEL) – Indica o canal para o qual o EAI Protheus irá enviar a mensagem. Para detalhes sobre a diferença entre os dois canais, verifique o tópico Parâmetros importantes do EAI Protheus;
  
  
• XSD (XX4_XSD) – Indica o nome do arquivo de validação dos XMLs recebidos. Este arquivo pode ter ou não sua extensão omitida. O diretório onde o arquivo de validação se encontra é definido por um parâmetro de sistema (veja o tópico Parâmetros importantes do EAI Protheus). Para cada uma das mensagens do tipo Business recebidas, caso este campo esteja preenchido, a mensagem é validada e em caso de não conformidade com o XSD é gerada uma mensagem de SoapFault, indicando o problema encontrado. Este campo é utilizado somente para Mensagens Únicas Totvs. Para mensagens do Totvs ESB o Schema é validado a partir do modelo de dados utilizado por aquele adapter (o MVC Protheus consegue gerar um arquivo XSD automaticamente);
  
  
• Filial Execução (XX4_FILEXE) – Indica a filial de execução do adapter. Caso não seja informada nenhuma filial a rotina será processada em todas as filiais do grupo no qual o adapter está cadastrado. Neste campo deve ser sempre informado o valor completo do campo Filial. Exemplo para a filial D MG 01. Neste layout temos o valor de 'D ' para a Empresa, 'MG ' para a Unidade de Negócios e o valor '01 ' para a Filial do sistema. Neste caso, devemos incluir no campo o valor completo - 'D MG 01'. Um adapter com filial de execução somente é executado na filial em questão (tanto envio quanto recebimento);
  
  
• Manipulação XML (XX4_CHGXML) – Este campo é utilizado para mensagens que não utilizam a arquitetura de Mensagem Única TOTVS. Esta rotina é chamada antes das validações da mensagem  recebida(é executada somente no recebimento das mensagens e é executado até mesmo antes da validação do XSD, caso exista). Esta rotina recebe como parâmetro o XML recebido e espera como retorno o XML alterado;
  
  
• Versão Envio (XX4_SNDVER) – Campo de versão da mensagem trafegada. As Mensagens Únicas TOTVS tem a sua versão definida no adapter de processamento, e este valor é retornado pelo adapter WhoIs (APCFG060). Para este campo só são permitidos os valores indicados no adapter, sendo inicializado este campo com o maior valor de versão disponível. Para as mensagens que não são da arquitetura de Mensagem Única TOTVS este campo não tem uso, e seu valor default é 1.000;
  
  
• Alias (XX4_ALIASP) – Este campo é utilizado somente nas mensagens da arquitetura Mensagem Única TOTVS e deve ser utilizado somente em mensagens que trafegam cadastros e nunca para movimentos. Para a utilização deste campo as equipes envolvidas no desenvolvimento do adapter devem ser consultadas, para determinar e avaliar os riscos do seu uso. Em situações normais, este campo não deve ser preenchido. Este campo define o Alias principal da mensagem. Quando este campo é preenchido são enviadas no cabeçalho as seguintes tags:
  
  
  • CompanySharingMode – Indica o compartilhamento desta tabela no nível de Empresas;
    
    
  • BusinessUnitySharingMode – Indica o compartilhamento desta tabela no nível de Unidade de Negócios;
    
    
  • BranchSharingMode – Indica o compartilhamento desta tabela no nível de Filial.

          O conteúdo destas tags pode conter dois valores: E – Para exclusivo e C para compartilhado.

          Alguns EAIs utilizam esta informação para realizar a replicação de dados entre as bases de dados. Alguns sistemas não possuem o mesmo nível de entidades de empresa e filial do Protheus (Grupo, Empresa, Unidade de Negócios e Filial) e a partir desta informação eles identificam como realizar a gravação destas informações. Consulte a documentação de cada ERP para verificar o tratamento a ser realizado no recebimento destas tags.

Cadastro de rotas de mensagens (Roteamento EAI Protheus)

O cadastro de rotas do Protheus foi normalizado para facilitar e centralizar o cadastramento das informações relativas aos produtos integrados via EAI a partir do label 08062016.

A partir da lib label 08062016 as rotas deverão ser cadastradas através do Cadastro de Rotas (Sigacfg/Ambientes/Schedule/Cadastro Rotas EAI) no ambiente do configurador Protheus.

Cadastro de Rotas do EAI Protheus

Podemos incluir ou alterar uma rota neste cadastro:

Tela de inclusão de uma rota

Neste cadastro devemos incluir o Produto (nas Mensagens Únicas Totvs este valor é conteúdo do atributo name, da tag Product), a Aplicação  (valor da tag SourceApplication do Xml).

Exemplo de cabeçalho de trecho do Xml de Mensagem Única TOTVS

Devemos incluir também a Url (a url do outro sistema integrado), o client de WS utilizado (por padrão o cliente WsEaiService, um client de WebServices disponibilizado pelo Framework,  é utilizado), o método que será consumido neste WebService (o padrão para a Mensagem Única TOTVS é o receiveMessage) e caso necessário, o usuário e senha de acesso a este serviço Web (somente para produtos que necessitam de autenticação (o EAI TOTVS trabalha com autenticação do tipo basic, conforme a RFC (Request for Comments) 2617.).

 É possível, para adapters do tipo Mensagem Única Totvs (campo XX4_UNMESS = 1-Sim) com canal de Envio EAI  (campo XX4_CHANEL =2-EAI) o envio de mensagens para mais de um destino e também o envio de ResponseMessage (respostas de mensagens assíncronas) para valores diferentes dos especificados nos parâmetros MV_EAIURL2, MV_EAIMETH, MV_EAIWS, MV_EAIPASS e MV_EAIUSER (para detalhes sobre estes parâmetros, veja o tópico parâmetros importantes do EAI Protheus.).

Cadastro do adapters de Natureza

Para mensagens Sincronas é possível somente cadastrar uma única rota de envio, para mensagens assíncronas não existe este limite.

No exemplo acima, quando realizarmos uma operação sobre o cadastro de naturezas a mensagem será enviada para a rota cadastrada no adapter. Quando for necessário gerar uma responsemessage de uma Mensagem Única TOTVS assíncrona que tenha chegado ao Protheus ele buscará qual é o produto e aplicação de origem contidos na mensagem original e caso seja encontrado o roteamento, a mensagem é enviada para a rota cadastrada.

          Caso não exista rota cadastrada no adapter, o seu comportamento padrão não será alterado.

          Na parte inferior deste cadastro existe um último grid de Tags para Busca. É possível incluir neste campo tags nas quais se deseja pesquisar o valor, e o valor destas tags é gravada concatenada com '|', posteriormente no campo XX3_REFER, no mesmo registro da mensagem.

De-para do EAI Protheus

Cadastro de De/Para de Empresas

         No EAI Protheus existe a possibilidade de se cadastrar, para as Mensagens Únicas TOTVS, um relacionamento entre a Empresa e Filial de processamento que chegou na mensagem com uma existente no Protheus. Isto se deve ao fato de que, na Mensagem Única TOTVS os valores trafegados na mensagem são sempre do sistema que enviou a mensagem, cabendo ao sistema receptor a tradução das informações trafegadas. Desta forma é enviada na mensagem o valor do correspondente a Empresa e Filial do sistema que originou a mensagem o que, em muitas vezes, não coincide com o código destas entidades no Protheus.
Vamos observar os campos deste cadastro, no menu Ambiente/Schedule/Emp.Fil Msg. Unica (APCFG050):

Figura 5 - Tela do cadastro de De/para de Empresas e FiliaisDe

• Referência (XXD_REFER) – Marca de referência do de/para. Esta marca é o atributo name da tag Product no path /TOTVSMessage/MessageInformation/;
  
  
• Company (XXD_COMPA) – Valor da empresa recebida na mensagem. Este valor é o conteúdo da tag CompanyId no path /TOTVSMessage/MessageInformation/;
  
  
• Branch (XXD_BRANCH) Valor da filial recebida na mensagem. Este valor é o contéudo da tag BranchId no path /TOTVSMessage/MessageInformation/;
  
  
• Emp. Protheus (XXD_EMPPRO) – Código da empresa/Grupo correspondente no Protheus;
  
  
• Fil.Protheus (XXD_FILPRO) – Código da filial correspondente no Protheus. Deve ser incluído o valor completo da filial no Protheus.

          Estes valores podem ser encontrados no cabeçalho da mensagem. Veja a imagem do cabeçalho aqui.

          A transformação dos valores recebidos para os valores de contexto do Protheus é realizada automaticamente pelo EAI Protheus. Como isto é realizado pode ser verificado no tópico Montagem de ambientes no recebimento das mensagens pelo EAI Protheus.

Cadastro de De/para de Mensagens Únicas

          De acordo com as definições da Mensagem Única TOTVS os valores transitados nas mensagens refletem sempre os códigos dos produtos que as enviam. Por este motivo existe um facilitador que pode ser utilizado pelas Mensagens Únicas TOTVS. Através do cadastro de De/Para de mensagens é possível realizar o relacionamento dos códigos recebidos e associar com os códigos internos do Protheus.
      Vamos verificar os campos deste cadastro, no menu Ambientes/Schedule/De.Para Msg.Unica (APCFG070):

Tela do Cadastro de De/Para de Mensagem Única TOTVS

        Os campos do formulário deste cadastro são:

• Referência (XXF_REFER) – Marca do produto que enviou a mensagem para o Protheus;
  
  
• Tabela (XXF_TABLE) – Nome físico da tabela na qual o registro que será realizado o de/para será inserido. Exemplo para a tabela SA1, no grupo de empresas 18: SA1180;
  
  
• Alias(XXF_ALIAS) – Alias da tabela do registro ao qual o de-para se refere. Exemplo: SA1;
  
  
• Campo (XXF_FIELD) – Nome do Campo ao qual se refere o de-para.

       O grid deste cadastro possui dois campos:

• Valor Externo (XXF_EXTVAL) – Valor que é recebido na mensagem;
  
  
• Valor Interno (XXF_INTVAL) – Correspondente do valor no Protheus.

         Normalmente não há necessidade de manipulação deste cadastro pelo usuário. Os adapters da Mensagem Única TOTVS realizam a manutenção e consulta do mesmo.

        Importante: O preenchimento do formulário deste cadastro é definido para cada mensagem no Protheus, e a regra para os campos Tabela, Alias, Campo, Valor Externo e Valor Interno é definida pelo criador da mensagem. O acesso e manipulação das informações deste facilitador não são realizados pela camada do EAI Protheus e sim pela camada do adapter. A utilização ou não deste recurso pelo adapter é de responsabilidade da equipe que o criou.
         As rotinas utilizadas internamente pelos adapters para realizar a manipulação destes registros são demonstradas no tópico funções utilizáveis no EAI Protheus.

InternalId e ResponseMessage em eventos de exclusão

Os adapters de Mensagem Única TOTVS trafegam uma informação importante: As chaves de relacionamento entre os códigos existentes no Protheus e os códigos existentes no outro sistema integrado. Esta informação sempre trafega em pares, e é conhecida como InternalId. Esta informação é incluída dentro do ReturnContent da ResponseMessage, e  é trafegada dentro do nó ListOfInternalId. Como ela é utilizada?

Supomos que no Protheus seja incluído um novo produto, que será enviado, via Mensagem Única TOTVS para um outro sistema, que chamaremos de Sistema B. O código do produto que será gerado no Sistema B pode ser diferente do código gerado no Protheus. Desta maneira, após realizar a inclusão do produto em seu sistema, o Sistema B devolve uma ResponseMessage para o Protheus, indicando que o processo foi bem sucedido e devolve também o seu InternalId criado e o InternalId enviado pelo Protheus.

O InternalId pode trafegar em ResponseMessages originadas de eventos de upsert ou ainda de delete mas para este último, existe uma regra na camada de Framework. Caso seja recebida uma ResponseMessage  e dentro dessa ResponseMessage, especificamente dentro do nó ReceivedMessage, seja enviada a tag Event, com a operação de delete, o adapter EAI é invocado sem receber a informação dos pares de InternalId. Esta tag expressa qual foi o evento gerador dessa mensagem.

Por exemplo, suponha que seja recebido, na camada do EAI Protheus o seguinte xml :

Exemplo de Xml de ResponseMessage, retornando o InternalId e e a tag de Event

Recebendo o Xml acima este será enviado para dentro do adapter EAI, mas sem a informação de InternalId. O xml recebido dentro do adapter será como o exemplo abaixo:

Exemplo de Xml de ResponseMessage, enviado para dentro do adapter sem a informação de InternalId

Este comportamento somente é aplicado caso a tag de Event seja recebida dentro da ReceivedMessage, com o evento de delete. E somente o nó do ListOfInternalId é retirado. Caso este nó não esteja presente, nada é alterado na mensagem.

A mensagem é gravada na fila de integrações do EAI Protheus de maneira completa. O conteúdo do ListOfInternalId somente é omitido no processamento da mensagem pelo adapter.

O Protheus, a partir desta lib, passa também a enviar a informação de Event dentro da ReceivedMessage.

Para mais informações sobre o que é um InternalId, consulte a documentação do Padrão Mensagem Única TOTVS no TDN,clicando  aqui.

Parâmetros importantes do EAI Protheus

        O EAI Protheus utiliza alguns parâmetros de sistema para definir o comportamento da integração. Estes parâmetros são listados abaixo:

• MV_EAIURL – Parâmetro que indica ao EAI Protheus para qual endereço de Webservices a mensagem será disparada. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =ESB;
  
  
• MV_EAIPORT – Parâmetro que indica ao EAI Protheus qual o método de Webservices será consumido no envio da mensagem. Este parâmetro é carregado com o valor default WSCHANNELReceiver. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =ESB;
  
  
• MV_EAIESBC – Parâmetro que indica qual a versão do Webservice do TOTVS ESB para o qual o EAI Protheus irá realizar o envio da mensagem. Este parâmetro deve ser informado no formato <versão>.<release>. Exemplo: 11.1. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =ESB;
  
  
• MV_EAIXSD – Parâmetro com o diretório no qual estarão os XSDs utilizados na validação das mensagens do EAI. Possui como valor default o diretório relativo '\xsd\totvsmessage'. Este diretório é criado automaticamente no Protheus. Este parâmetro é utilizado somente quando a mensagem é do tipo Mensagem Única TOTVS. Para as mensagens do tipo TOTVSIntegrator que possuem adapter configurado a validação do XSD gerado pelo modelo de dados contra a mensagem é realizado de forma automática;
  
  
• MV_EAIURL2 - Parâmetro que indica ao EAI Protheus para qual endereço de Webservices a mensagem será disparada. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =EAI;
  
  
• MV_EAIWS - Parâmetro que indica ao EAI Protheus qual o cliente de Webservices utilizado para envio a outro EAI. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =EAI e tem como conteúdo default o valor WSEAISERVICE. O Client de Webservices do EAI TOTVS não precisa ser recompilado, pois ele é de controle interno. Importante: Para integrações com o produto DATASUL o valor deste parâmetro deve ser alterado para WSEAIDATASUL;
  
  
• MV_EAIMETH – Parâmetro que indica o método de Webservice que será consumido no envio da mensagem. . Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =EAI e tem como conteúdo default o valor receiveMessage. Normalmente este parâmetro não deve ser alterado, pois o método utilizado nas integrações via Mensagem Única TOTVS é padronizado com este nome.
  
  
• MV_EAIUSER – Parâmetro para envio do usuário de acesso a camada de Webservices no sistema destino. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =EAI. Este parâmetro somente deve ser configurado quando o sistema que irá receber a mensagem oriunda do EAI Protheus possuir autenticação de usuários na camada de Webservices;
  
  
• MV_EAIPASS – Parâmetro para envio da senha do usuário de acesso a camada de Webservices no sistema destino. Este parâmetro é utilizado quando o adapter está cadastrado com o Canal Envio (XX4_CHANEL) =EAI. Este parâmetro somente deve ser configurado quando o sistema que irá receber a mensagem oriunda do EAI Protheus possuir autenticação de usuários na camada de Webservices;

Montagem de ambientes no recebimento das mensagens pelo EAI Protheus

        O EAI Protheus permite o processamento das mensagens recebidas na empresa e filial indicadas no cabeçalho da mensagem como também da filial recebida no contexto do negócio (BusinessMessage,  somente para Mensagem Única TOTVS).
       Para mensagens do envelope TOTVSIntegrator o valor recebido nas tags DocCompany (empresa) e DocBranch (filial) são consultados e seus valores utilizados para determinar ao EAI Protheus qual será o par Empresa/Filial no qual o ambiente será criado. Caso o valor destas tags sejam inválidos no contexto do Protheus (empresa e filial inexistente ou inválidas) é retornado uma mensagem de SoapFault para o sistema que enviou a mensagem.

          Para mensagens da arquitetura de Mensagem Única TOTVS (TOTVSMessage) estes valores são recebidos nas tags CompanyId (Empresa) e BranchId (Filial)  no path /TOTVSMessage/MessageInformation do XML recebido ou ainda dentro da BusinessMessage, no path /TOTVSMessage/BusinessMessage/BusinessContent.

          A verificação da empresa/fiilal constantes no MessageInformation ocorre da seguinte forma:

•  Primeiramente é verificado se o par empresa/filial recebido na mensagem existe no De-para de Empresas no Protheus (tabela XXD). Caso seja encontrado o relacionamento de de-para no Protheus o ambiente é montado com os valores encontrados. Caso não seja encontrado o relacionamento é realizada a tentativa de montagem de ambiente com os valores recebidos diretamente na mensagem. Em ambos os casos (encontrando o relacionamento e não encontrando-o) a empresa e filial são validadas, e em caso de não possibilidade de processamento é retornada um SoapFault para o sistema que enviou a mensagem

          Após esta verificação a camada do EAI busca a tag BranchId dentro da BusinessContent. Caso exista esta informação, a seguinte regra é aplicada:

• Caso não seja enviada a tag CompanyId dentro da BusinessContent o valor assumido será o valor trafegado na MessageInformation;
• Caso este novo par empresa/filial seja idêntico ao trafegado na MessageInformation nada é alterado no processo;
• Em casos de diferença é buscado o relacionamento deste par na tabela de de-para de empresas no Protheus;
• Caso não exista relação de de-para para esta informação é retornado erro no EAI (A Empresa e filial constantes na BusinessContent não possui empresa e filial relacionados no Protheus.Verifique a configuração do de-para de empresa/filial);
• Caso exista relação de de-para é verificado se o correspondente a empresa no de-para é igual ao correspondente da empresa recebida na MessageInformation. Caso sejam diferentes, é retornado erro para o EAI (A Empresa enviada na BusinessContent é diferente da informada na MessageInformation. Verifique as configurações do sistema X). Vejamos o seguinte exemplo de Xml:
  
  
• Exemplo de Xml com empresa e filial na BusinessContent

           No exemplo acima, vamos supor que o de-para entre RM e Protheus identifique para um CompanyId 01 e BranchId  001 o par de Grupo 18 e filial D MG 01 e o correspondente na BusinessContent retorne para uma CompanyId 01 e BranchId 002 o par de Grupo 19 e filial D MG 02. Neste caso, o EAI irá retornar o erro, pois somente é aceita a troca de filial no contexto da mensagem, nunca do grupo de empresas.

          Pensando ainda no exemplo anterior vamos supor que o de-para entre RM e Protheus identifique para um CompanyId 01 e BranchId  001 o par de Grupo 18 e filial D MG 01 e o correspondente na BusinessContent retorne para uma CompanyId 01 e BranchId 002 o par de Grupo 18 e filial D MG 02. Neste caso será verificado se o EAI pode ser processado nesta filial (todas as validações pertinentes ao processamento realizados para as tags constantes na MessageInformation são averiguadas para este novo par de empresa/filial). Não é realizada troca de ambiente para este caso. No momento do processamento do adapter, e somente neste momento a filial do sistema é trocada automaticamente, para que o adapter seja processado na filial correta no Protheus.

O Ponto de entrada EAICHGEMP

          O Ponto de entrada EAICHGEMP é um ponto de entrada utilizado, no recebimento das mensagens únicas pelo EAI Protheus para que seja possível dizer para qual empresa e filial o ambiente deverá ser aberto. O array PARAMIXB enviado neste ponto de entrada recebe possui cinco elementos:

• Paramixb[1] =Marca recebida na mensagem. Esta marca é o atributo name da tag Product no path /TOTVSMessage/MessageInformation/;
  
  
• Paramixb[2] =Nome da aplicação recebida na mensagem. Este valor é o conteúdo da tag SourceApplication no path /TOTVSMessage/MessageInformation/. O Protheus envia nesta tag o nome do ambiente no qual a mensagem foi gerada;
  
  
• Paramixb[3] =Nome da mensagem única. Este valor é o conteúdo da tag Transaction no path /TOTVSMessage/MessageInformation/;
  
  
• Paramixb[4] =Código da empresa recebido na mensagem. Este valor é o conteúdo da tag CompanyId no path /TOTVSMessage/MessageInformation/;
  
  
• Paramixb [5] =Código da filial recebido na mensagem. Este valor é o conteúdo da tag CompanyId no path /TOTVSMessage/MessageInformation/.

          O retorno esperado deste ponto de entrada é um array de duas posições, sendo a primeira posição o valor da empresa/grupo e a segunda posição o valor completo da filial. Exemplo de retorno esperado do ponto de entrada = {'18',' D MG 01'}. A empresa e filial retornados no array devem ser válidas no contexto do Protheus.
           Caso seja retornado um array vazio neste ponto de entrada, o EAI segue o caminho descrito no tópico Montagem de ambientes no recebimento das mensagens pelo EAI Protheus.