Preparando Uma Rotina de Integração No Protheus

24/11/2014 View Source
Status do Concluído
Preparar uma rotina de integração no Protheus é bem simples.
DOCUMENTO
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.
DATA 18/11/2014
Versão 1.0
Versão 1.0
Gerando um Schema XML a partir de um anterior
adapter no Protheus AUTORES Jandir

Deodato
Girl Walks Around NYC With No Pants On And No One Even Notice! de Souza
(Buzzwok) Silva
Um XML Schema DEFINITION , ou XSD, é um arquivo que Índice resumido

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 Índice
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:
Anexos deste artigo
COMP011_MVC.prw
COMP011_MVC_COM_ADAPTER.xm
TOTVS_INTEGRATOR_SEM_ADAP
TSTEAI.prw
COMP_011_MVC_SEM_ADP_ENVIO
COMP_011_MVC_COM_INTEGDEF.
XML_MY_MESSAGE_ENVIO.xml
XML_MY_MESSAGE_RECEBIMENT
Figura 1 - 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
http://tdn.totvs.com/plugins/viewsource/viewpagesrc.action?pageId=173083052 1/16
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 para e 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:
Figura 2- Cadastro do adapter Comp011_MVC
Feito isto, vamos ENTRAR nesta rotina e incluir um registro.
Figura 3 - 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:
Figura 4 - 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:
Figura 5 - 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:
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:
Figura 6 - 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 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
a 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
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.
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 o processamento e cadastro do adapter
sejam realizados. Para utilizar os defines é necessário o include
FWADAPTEREAI.CH
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.
O retorno desta rotina será sempre um ARRAY , de duas 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.

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 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.
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.
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).
Figura 7 - Cadastro da Mensagem Única em fonte MVC no Protheus.
Vamos agora MOSTRAR o XML de envio, e o XML recebido no

Protheus:

Preparando Uma Rotina de Integração No Protheus

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Preparando Uma Rotina de Integração No Protheus

Enviado por

Direitos autorais:

Formatos disponíveis

24/11/2014 View Source

adapter no Protheus AUTORES Jandir

Um XML Schema DEFINITION , ou XSD, é um arquivo que Índice resumido

Para mensagens da estrutura do TOTVSIntegrator com adapters

Anexos deste artigo

Figura 1 - Geração de XSD pela rotina de Cadastro de Adapter. É necessário

Será criado no diretório especificado todos os arquivos XSD dos

Dúvidas sobre o que é um XSD? CONSULTE a página do W3C na

Integrações do tipo TOTVSIntegrator em

Baixe este arquivo aqui.

Para que o exemplo acima funcione, é necessário executar o

Figura 2- Cadastro do adapter Comp011_MVC

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

Figura 3 - Inclusão do cadastro do fonte TESTE

Perceba que não foi parametrizado os endereços de envio do EAI

tela, indicando o problema:

Figura 4 - Mensagem de erro em adapter construído em MVC Protheus,

Vamos verificar a fila do EAI Protheus e verificar o XML gerado e o

Figura 5 - Visualização do erro de integração na fila de mensagens do EAI

No nosso caso, não foi possível enviar a mensagem para o endereço

Baixe este arquivo aqui.

O XML gerado já contém os dados necessários para a gravação das

Figura 6 - Cadastro incluído via integração no Protheus

Note que todo o processamento realizado no Protheus foi realizado

estão cadastrados no Cadastro de

Recebendo uma mensagem pela estrutura

Vamos gerar o seguinte xml para envio ao Protheus. Lembrando que

Baixe este aquivo aqui.

No XML acima vamos incluir no Protheus um registro na mesma

encontra disponível no Cadastro de Adapters. Desta maneira, todo o

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

A rotina que irá processar o XML recebido irá receber os seguintes

cError – Variável passada por referência, serve para alimentar a

cWarning – Variável passada por referência, serve para alimentar

uma mensagem de warning para o EAI. A alteração deste valor por

cParams – Parâmetros passados na mensagem do EAI. Para o envio

Após o nome da função a ser executada deve ser colocado um

OS parâmetros são enviados na forma de uma string,

oFwEAI – O objeto de EAI criado na camada do EAI Protheus. A

Enviando uma mensagem

Ao contrário do exemplo anterior, onde a rotina em MVC Protheus já estava

Baixe este arquivo aqui.

No fonte acima, foi incluído no bloco de commit do MVC Protheus a

cType – Tipo de transação :

'0'- para mensagem sendo recebida (DEFINE

'1'- para mensagem sendo enviada (DEFINE

cTypeMessage – Tipo da mensagem do EAI:

'20' – Business Message (DEFINE

'21' – RESPONSE Message (DEFINE

'22' – Receipt Message (DEFINE EAI_MESSAGE_RECEIPT)

'23' WhoIs Message (DEFINE EAI_MESSAGE_WHOIS)

cVersion – Versão da Mensagem Única TOTVS.

O retorno desta rotina será sempre um ARRAY , de duas posições,

aArray[2] – Uma string contendo informações sobre o processamento.

IntegDef em rotinas MVC Protheus

Baixe este arquivo completo aqui.

A rotina IntegDef é a responsável por realizar o processamento da

A integração é disparada no momento do COMMIT dos dados do

Figura 7 - Cadastro da Mensagem Única em fonte MVC no Protheus.

Vamos agora MOSTRAR o XML de envio, e o XML recebido no

Você também pode gostar