Preparar uma rotina de integração no Protheus é bem simples. Existem três formas de realizar este tratamento. Vamos explicar então como desenvolver este adapter e como criar um XSD a partir de um modelo de dados MVC Protheus.

Gerando um Schema XML a partir de um adapter no Protheus

          Um XML Schema Definition, ou XSD, é um arquivo que descreve a estrutura de um documento XML. Para enviar um XML para o outro sistema é necessário conhecer a estrutura do XML esperado por ele.

           Para mensagens da estrutura do TOTVSIntegrator com adapters criados na arquitetura de MVC Protheus é possível, pelo Cadastro de Adapters no Protheus gerar este arquivo e descobrir qual a estrutura esperada por esta rotina. Para isto, no Cadastro de Adapters (CFGA020), em Ações Relacionadas/Schema XML é possível gerar este arquivo:

Geração de XSD pela rotina de Cadastro de Adapter. É necessário escolher o local de criação do arquivo e também se é necessário criar o cabeçalho dos mesmos (schema TOTVSIntegrator).

           Será criado no diretório especificado todos os arquivos XSD dos adapters cadastrados, e também o Schema do TOTVSIntegrator (desde que a opção 'Todos com cabeçalho?' esteja selecionada), este com o nome MpSchemas.xsd.
As integrações da arquitetura Mensagem Única TOTVS possuem XSDs específicos para cada mensagem trafegada, e não é possível realizar a geração dos mesmos por esta interface. Estes arquivos são criados e disponibilizados pelas áreas responsáveis por cada adapter.

           Dúvidas sobre o que é um XSD? Consulte a página do W3C na internet, clicando aqui.

Integrações do tipo TOTVSIntegrator em rotinas MVC Protheus com cadastro de Adapter

           Vamos agora explicar o funcionamento das integrações do envelope TOTVSIntegrator e como ela se comporta no EAI Protheus. Para este tipo de integração é necessário que o adapter esteja escrito em MVC Protheus. Detalhes do funcionamento do MVC Protheus podem ser encontrados clicando aqui.
           Para que o EAI identifique que a mensagem recebida é uma mensagem de processamento do EAI Protheus o valor enviado na tag GlobalFunctionCode no path /TOTVSIntegrator/ deverá ser EAI.
           Um fonte construído em MVC Protheus já possui a capacidade de enviar e receber dados automaticamente através do envelope TOTVSIntegrator, desde que a definição de XSD do mesmo seja respeitada. Para detalhes de como gerar um XSD a partir de um adapter no Protheus verifique o tópico Gerando um Schema XML a partir de um adapter no Protheus.
           O exemplo abaixo demonstra um cadastro simples realizado em MVC Protheus. Os exemplos completos destes fontes estão disponíveis na Comunidade do Desenhador MVC, no Fluig e os arquivos disponíveis neste artigo. Este exemplo foi modificado, onde a  User Function foi trocada para uma function. Clique aqui para visualizar a comunidade no Fluig.

          Baixe este arquivo aqui.

           Para que o exemplo acima funcione, é necessário executar o fonte UPDMVC, disponível na comunidade do FLUIG, para que a estrutura da tabela ZA0 seja criada.
           No exemplo acima, o fonte já está totalmente preparado para o envio das mensagens pelo EAI Protheus. Vamos cadastrar o adapter desta rotina no configurador:

Cadastro do adapter Comp011_MVC

           Feito isto, vamos entrar nesta rotina e incluir um registro.

  Inclusão do cadastro do fonte Teste

           Perceba que não foi parametrizado os endereços de envio do EAI Protheus, desta maneira a integração não será bem sucedida. Importante: Rotinas na arquitetura MVC Protheus fazem a consistência da integração quando configurada. Isto quer dizer que, caso a integração não seja bem sucedida os dados não serão gravados no Protheus.
          Como este fonte está escrito em MVC Protheus a mensagem surge em tela, indicando o problema:

Mensagem de erro em adapter construído em MVC Protheus, indicando que a integração não foi bem sucedida

           Vamos verificar a fila do EAI Protheus e verificar o XML gerado e o status da mensagem:

Visualização do erro de integração na fila de mensagens do EAI Protheus

           No nosso caso, não foi possível enviar a mensagem para o endereço especificado. Como configuramos nossa mensagem como síncrona não será realizada outra tentativa de envio da mesma. Vamos observar o XML gerado:

          Baixe este arquivo aqui.

           O XML gerado já contém os dados necessários para a gravação das informações. Podemos enviar este mesmo XML, através de qualquer ferramenta de envio de XMLs para o serviço do EAI Protheus, e os dados serão gravados na tabela indicada. Vamos enviar este XML para o Protheus, através de uma ferramenta de envio de dados à Webservices. Entraremos agora na rotina e veremos que o cadastro agora foi incluído:

Cadastro incluído via integração no Protheus

           Note que todo o processamento realizado no Protheus foi realizado pelo adapter COMP011_MVC. Uma dica para testes é tentar integrar duas bases Protheus diferentes.

Integrações da estrutura TOTVSIntegrator em fontes que não estão cadastrados no Cadastro de Adapters

           Existe a possibilidade de realizar a integração de dados do Protheus com outros sistemas, utilizando a estrutura do TOTVSIntegrator. Nestes casos a rotina não deverá estar no Cadastro de Adapters do Protheus. A rotina de processamento somente poderá ser uma rotina que esteja no menu do Protheus ou uma função de usuário (user function). Qualquer tentativa de execução de uma função que não obedeça estes critérios resultará em um retorno de SoapFault para o sistema que enviou a mensagem.

Recebendo uma mensagem pela estrutura TOTVSIntegrator em adapters que não estão no cadastro

          Para que o EAI identifique que a mensagem recebida é uma mensagem de processamento do EAI Protheus o valor enviado na tag GlobalFunctionCode no path /TOTVSIntegrator/ deverá ser EAI.

           Vamos gerar o seguinte xml para envio ao Protheus. Lembrando que o XML enviado deve respeitar o XSD do TOTVSIntegrator. Para gerar o XSD do TOTVSIntegrator, consulte o tópico Gerando um Schema XML a partir de um adapter no Protheus.

          Baixe este aquivo aqui.

          No XML acima vamos incluir no Protheus um registro na mesma tabela do exemplo Integrações do tipo TOTVSIntegrator em fontes em MVC Protheus com cadastro de Adapter no Protheus. Porém, neste caso a nossa rotina de processamento (adapter) não é um fonte em MVC e nem se encontra disponível no Cadastro de Adapters. Desta maneira, todo o processamento da mensagem deverá ser realizado manualmente. Isto significa que a rotina deverá ser capaz de ler o XML recebido, executar as validações de regra de negócio necessárias e realizar o processamento da mensagem recebida.
           No exemplo abaixo, a User Function TSTEAI irá receber o XML recebido pelo EAI Protheus, e irá realizar a chamada do Modelo de dados da rotina COMP011_MVC e irá realizar a gravação do dado recebido (realizar a chamada do Modelo de dados de uma rotina é o equivalente, no MVC Protheus, de se realizar a chamada de uma MsExecAuto). Como a rotina COMP011_MVC está na arquitetura MVC Protheus ela já possui, nativamente, uma maneira de se gravar os seus dados sem a necessidade de interface, de maneira semelhante as MsExecAuto. Para detalhes de como isto funciona, consulte no TDN a documentação do MVC Protheus clicando aqui.

           Abaixo o exemplo da rotina para processamento do XML recebido

          Baixe este arquivo aqui.

           Veja que no exemplo acima foi necessário um conhecimento maior da estrutura da tabela a ser integrada. O retorno desta rotina (no caso um lógico) é enviado como resposta para o sistema que enviou a mensagem. Retornos lógicos são devolvidos como T (true) ou F (falso). Todos os outros retornos são enviados como Strings para o sistema que enviou a mensagem. Desta maneira, é possível enviar uma mensagem para o outro sistema, indicando o que ocorreu.

           A rotina que irá processar o XML recebido irá receber os seguintes parâmetros:

• cXml – O conteúdo da tag Content do XML recebido pelo EAI Protheus;
  
  
• cError – Variável passada por referência, serve para alimentar a mensagem de erro, nos casos em que a transação não foi bem sucedida;
  
  
• cWarning – Variável passada por referência, serve para alimentar uma mensagem de warning para o EAI. A alteração deste valor por rotinas tratadas neste tópico não causam nenhum efeito para o EAI;
  
  
• cParams – Parâmetros passados na mensagem do EAI. Para o envio destes parâmetros é utilizada a seguinte regra:
  • Estes parâmetros são passados após o nome da função, na tag FunctionCode, no path /TOTVSIntegrator/Message/Layouts/
    
    
  • Após o nome da função a ser executada deve ser colocado um '.' e após cada um dos parâmetros mais um. Exemplo: <FunctionCode>U_TSTEAI.01.02.03</FunctionCode>.
    
    
  • OS parâmetros são enviados na forma de uma string, separados por ','. No exemplo acima, a variável cParams irá receber a string 01,02,03
    
    
• oFwEAI – O objeto de EAI criado na camada do EAI Protheus. A manipulação deste objeto deve ser realizada com o máximo de cautela, e deve ser evitada ao máximo.

Enviando uma mensagem pela estrutura TOTVSIntegrator em adapters que não estão no cadastro

           Ao contrário do exemplo anterior, onde a rotina em MVC Protheus já estava preparada para o recebimento e envio da mensagem, neste caso, além de realizar o tratamento de recebimento da mensagem é necessário criar também realizar a chamada da integração em algum ponto do sistema (normalmente, após a validação e gravação dos dados no sistema).
Para o nosso exemplo, a integração será chamada após a gravação dos dados no Protheus. Para detalhes do funcionamento da classe FWEAI consulte o TDN clicando aqui.

          Baixe este arquivo aqui.

           No fonte acima, foi incluído no bloco de commit do MVC Protheus a chamada da integração. Foi realizado também um tratamento para caso a integração não seja bem sucedida, o valor não seja gravado no Protheus. Esta rotina gera um XML idêntico ao XML recebido no exemplo Recebendo uma mensagem pela estrutura TOTVSIntegrator em adapters que não estão no cadastro.

Integrações via Mensagem Única TOTVS

           As integrações via Mensagem Única TOTVS são integrações que usam a arquitetura de mensagem TOTVSMessage. Ao contrário do exemplo da TOTVSIntegrator um adapter de Mensagem Única sempre deverá estar cadastrado para que a integração aconteça.
           A arquitetura da mensagem única prevê um adapter com uma função estática, de nome IntegDef, para que o processamento e cadastro do adapter sejam realizados. Para utilizar os defines abaixo é necessário o include FWADAPTEREAI.CH

A função Static IntegDef

Sintaxe:

      Static Function IntegDef(cXml,cType,cTypeMessage,cVersion,cTransaction)

     A função IntegDef recebe como parâmetros:

• cXml – O XML recebido pelo EAI Protheus. Diferente do TOTVSIntegrator é passado neste caso todo o XML recebido pelo EAI;
  
  
• cType – Tipo de transação :
  
  
  • '0'- para mensagem sendo recebida (DEFINE TRANS_RECEIVE);
    
    
  • '1'- para mensagem sendo enviada (DEFINE TRANS_SEND)
    
    
• cTypeMessage – Tipo da mensagem do EAI:
  
  
  • '20' – Business Message (DEFINE EAI_MESSAGE_BUSINESS)
    
    
  • '21' – Response Message (DEFINE EAI_MESSAGE_RESPONSE)
    
    
  • '22' – Receipt Message (DEFINE EAI_MESSAGE_RECEIPT)
    
    
  • '23' WhoIs Message (DEFINE EAI_MESSAGE_WHOIS)
    
    
• cVersion – Versão da Mensagem Única TOTVS.

• cTransaction  - Informa qual o nome da mensagem iniciada no adapter. Ex. "CUSTOMERVENDOR". Esta informação é importante quando temos a mesma rotina cadastrada para mais de uma mensagem.

  Importante

  A varíavel cTransaction somente é alimentada em libs a partir do label 10102016, com previsão de liberação em dezembro de 2016.

      O retorno desta rotina será sempre um array, de três posições, sendo estas:

• aArray[1] – Deve retornar uma variável lógica, indicando se o processamento foi executado com sucesso (.T.) ou não (.F.);
  
  
• aArray[2] – Uma string contendo informações sobre o processamento;
  
  
• aArray[3] – Uma string com o nome da mensagem única desta mensagem. A utilização deste parâmetro foi incluída para facilitar o cadastramento de uma Mensagem Única TOTVS. O EAI Protheus somente utiliza esta informação a partir da lib label 08062015. Ao iniciar o cadastro de uma mensagem única, após incluir o nome da Rotina do adapter, é gatilhado, no campo Mensagem (XX4_MODEL) o valor deste elemento do array. Em libs anteriores esta informação não é utilizada, mas também não gera qualquer inconsistência caso seja retornada na rotina.
  
  
• aArray[4] – Valor Logico indicando se o Adapter esta apto a trabalhar com o padrão do FWEAIOBJ. A utilização deste parâmetro foi incluída para facilitar o cadastramento de uma Mensagem Única TOTVS. O EAI Protheus somente utiliza esta informação a partir da lib label 10012019. Em libs anteriores esta informação não é utilizada, mas também não gera qualquer inconsistência caso seja retornada na rotina.
  
  
• aArray[5] – Valor Lógico que indica se deve  realizar o processo de retirada de ListofInternalID em mensagens de response de Delete(.T. será executado, processo padrão, .F. não será executado).A utilização deste parâmetro foi incluída para alterar um comportamente de uma Mensagem Única TOTVS sem afetar outras mensagens. O EAI Protheus somente utiliza esta informação a partir da lib label 10012019. Em libs anteriores esta informação não é utilizada, mas também não gera qualquer inconsistência caso seja retornada na rotina.

        Para os próximos exemplos vamos utilizar a rotina COMP011_MVC mostrada nos exemplos anteriores. A IntegDef deve ser capaz de ler o xml recebido e enviar um XML.

IntegDef em rotinas MVC Protheus

          Seguindo o exemplo da rotina COMP011_MVC, vamos incluir a função IntegDef neste fonte.

          Baixe este arquivo de exemplo completo aqui.

           A rotina IntegDef é a responsável por realizar o processamento da mensagem a ser enviada e da mensagem recebida. Perceba que os tratamentos de InternalId (o de/para de registros) é realizado, quando necessário, por esta rotina, e nunca pela camada de EAI Protheus, exceto na chegada de uma ResponseMessage.

           A integração é disparada no momento do commit dos dados do modelo. Caso a rotina possua um bloco de commit próprio, a integração somente é disparada automaticamente se a função FWFormCommit for utilizada para a gravação do modelo.

           O adapter EAI deve sempre tratar os dois sentidos da mensagem: Envio e Recebimento.

           O Adapter EAI deve obrigatoriamente sempre tratar o recebimento da Mensagem Única Whois, que retorna informações sobre a mensagem e a sua versão. Para isto, as versões disponíveis da mensagem devem sempre ser enviadas com a seguinte máscara: V.RRR, onde V é a versão da mensagem e R o release da mesma. Para diferentes versões disponíveis dentro do mesmo adapter, estas devem ser devolvidas com o separador '|' entre elas. Exemplo para uma rotina que possua as versões 1.000, 1.001 e 2.000 disponíveis: '1.000|1.001|2.000'. O Cadastro de Adapters do Protheus somente permite que sejam cadastradas versões de mensagens disponíveis no adapter. As alterações de versões de mensagens são acordadas entre as equipes que fazem as manutenções das mesmas, e são sempre direcionadas ao Comitê de Integrações TOTVS, para a definição de qual será a versão/release de alteração da mesma.

     A função Integdef do adapter é chamada no momento do envio da mensagem e no recebimento da mensagem de resposta.

          Vamos agora cadastrar o adapter para a Mensagem Única MyMessage (lembrando que o nome da mensagem é acordado no Comitê de Integrações TOTVS. Este nome é usado apenas como exemplo). Caso o adapter EAI retorno um array de 3 posições (como o mostrado acima) com a última posição retornando o nome da mensagem, este é gatilhado no campo Mensagem (XX4_MODEL).

Cadastro da Mensagem Única em fonte MVC no Protheus.

           Vamos agora mostrar o XML de envio, e o XML recebido no Protheus:

          Baixe este arquivo aqui.

          E o XML retornado pelo outro sistema (no exemplo, integramos Protheus com Protheus)

          Baixe este arquivo aqui.

IntegDef em rotinas Não-MVC Protheus

           Nas rotinas escritas em MVC Protheus o disparo das integrações via Mensagem Única é realizado internamente no commit do modelo de dados. Rotinas que não são MVC Protheus devem realizar a chamada da integração manualmente. Este fato se deve ao fato de que, em rotinas que não são MVC Protheus não é possível saber o momento da gravação dos dados pela camada do EAI Protheus. Nestes casos, o desenvolvedor da rotina é o mais indicado a saber o momento correto de iniciar a integração. Para estas rotinas é necessário realizar a chamada da função FWIntegDef nos fontes. Veja o tópico Funções utilizáveis no EAI Protheus para detalhes do funcionamento desta rotina.

           Supondo que a rotina COMP011_MVC não estivesse escrita em MVC Protheus, e que em algum ponto do sistema a gravação fosse realizada por esta rotina. Segue abaixo um exemplo de chamada da FWIntegDef:

//.......................
BEGIN TRANSACTION
RecLock('ZA0',.T.)
ZA0->ZA0_CODIGO:=cCode
ZA0->ZA0_NOME:=cDescri
ZA0->ZA0_TIPO:='1'
MsUnlock()
FwIntegDef('COMP011_MVC')
END TRANSACTION
//..........................