Com o objetivo de padronizar a integrações com outros produtos, foi definida uma nova diretriz para os projetos de integração: os produtos podem se comunicar com uma mensagem XML ou Json única, evitando desta forma o processo de transformação de mensagens.


Neste cenário, teríamos o seguinte quadro:

Neste cenário, qualquer produto parceiro trabalhará com o mesmo XML, para uma mesma entidade, ou seja, supondo que tenhamos um Xml/Json correspondente à mensagem de Cadastro de Clientes, ela poderá ser enviada para qualquer um dos produtos que suporte o recebimento desta entidade.

Uma vez que os vários produtos terão um “idioma” em comum, o Xml/Json único, as integrações entre estes produtos não exigirão mais que as mensagens sejam transformadas de um formato para outro.


1 - Configurações primordiais

Tabelas utilizadas na Integração EAI:

  • De/Para de Empresas/Filiais Mensagem única (XXD)
  • De/Para de Conteúdos Mensagem Única (XXF)
  • Transações E.A.I. (XX3)
  • Adapters E.A.I. (XX4)

Parâmetros utilizados na Integração EAI:

  • MV_EAIMETH: Não deve ser alterado
  • MV_EAIUSER
  • MV_EAIPASS
  • MV_EAIURL2: Endereço do WS para comunicação. Podemos informar a Rota da integração neste parâmetro ou através da rotina CFGA020.  Saiba mais: Roteamento E.A.I. Protheus (CFGA020 - SIGACFG)
  • MV_EAIWS: Não precisa ser alterado 

A integração do Top RM com o Protheus envolve o módulo Gestão de Projetos (SIGAPMS), neste módulo não é necessário realizar alguns cadastros de De/Para na tabela XXF e sim configurar alguns parâmetros. 

Lista dos parâmetros que envolve as integrações deste módulo: Parâmetros da Integração

Os Adapters são responsáveis por realizar o processamento das mensagens enviadas e recebidas, possibilitando a inclusão, alteração e exclusão de dados.
Veja a Lista Completa dos Adapters utilizados na integração E.A.I (Enterprise Application Integration).

Veja o vídeo do processo de cadastro do Adapter em: 01. Cadastro do Adapter

As integrações via Mensagem Única propõem dois modelos de envio e recebimento de mensagens: 

  • Síncronas: A mensagem é enviada e o sistema que enviou aguarda o processamento da mensagem pelo receptor;
  • Assíncronas: A mensagem é enviada e o sistema que a enviou não aguarda o seu processamento. Posteriormente a mensagem será processada no receptor.


O modelo de mensagem que será utilizado na integração deve ser avaliado com muito cuidado. Apesar do modelo síncrono parecer o mais adequado para uma integração, isto não é de todo verdade. Em um modelo síncrono deve ser levado em consideração o tempo de processamento: O processamento do sistema que envia, a velocidade do trânsito de dados da rede e o tempo de processamento e resposta do receptor.
Isto pode acarretar um tempo de resposta ao usuário muito maior do que o normal, o que pode transformar a integração de solução ao problema. Já o modelo assíncrono, por não aguardar o retorno do processamento do receptor torna o processo mais rápido, porém, neste modelo de mensagem deve-se levar em consideração que o dado será gravado no sistema que envia a mensagem e que o processamento no receptor ocorrerá posteriormente.

Desta maneira, em algumas situações os dados irão existir no sistema de envio, mas enquanto não forem processados no receptor eles não existirão lá.

O Cadastro de De/Para de empresas/filiais irá definir quais empresas e filiais serão integradas entre os dois sistemas.

Veja o vídeo do processo de cadastro do De/Para de Empresas/Filiais: 02. De Para de Empresas Filiais

No XML é necessário identificar a Aplicação de Origem, a Empresa e a Filial para cadastrar o De/Para. As tags a serem verificadas são:

  • SourceApplication = Aplicação de Origem (XXD_REFER)
  • CompanyId = Empresa (XXD_COMPA)
  • BranchId = Filial (XXD_BRANCH)

Na maioria das vezes, os códigos dos registros utilizados nos sistemas que se comunicam via Mensagem Única não são os mesmos, a XXF é a tabela que ira guardar os códigos para relacionar os registros, por exemplo um cliente pode possuir o código no Protheus, e no RM esse mesmo cliente possui o código C0100001. Por isso o sistema realiza o cadastro de um "De/Para de Mensagem Única". 

Ao realizar a inclusão de um cadastro, o sistema verifica se já existe um "De/Para de Mensagem Única", caso já exista, o sistema entende que trata-se de uma alteração, caso não exista, trata-se de uma inclusão, então ele cria automaticamente o "De/Para de Mensagem Única" (XXF).

Veja o vídeo do processo de cadastro do De/Para de Mensagem Única (XXF): De Para de Mensagem Única

O vídeo está no Google Drive do Suporte FAT / SERV / JUR, caso execute no navegador Google Chrome, a qualidade do vídeo pode ficar mais baixa, sendo esse o caso, é possível fazer o Download do arquivo para superior qualidade.

Caso trate-se de uma inclusão que referencia códigos de outros cadastros, esses códigos necessitam de um "De/Para de Mensagem Única", por exemplo, ao incluir um Pedido de Vendas você precisa referenciar um código de Produto e um código de cliente, mas, nesse momento, você não está incluindo o cliente ou o produto, você está incluindo o Pedido, portanto o cliente e o produto precisam ter um "De/Para de Mensagem Única" (XXF) cadastrado. 

Todos os fontes de integração contém a letra "I" no final do nome da rotina, fontes com processamento a parte em JSON possuem a letra "O" ou "Json" no final.

Exemplos:

  • A rotina de Pedidos de Venda tem seu fonte com nome "MATA410";
  • Na integração de Pedido de Venda via XML, o fonte que trata a integração chama-se "MATI410";
  • Na integração de Pedido de venda via JSON o fonte que trata a integração chama-se  "MATI410O"

  • A movimentação do Estoque tem seu fonte com nome "MATA240";
  • Na integração da Movimentação via XML, o fonte que trata a integração chama-se "MATI241"
  • Na integração da Movimentação via JSON o fonte que trata a integração chama-se "MATI241JSON"

Para realizar os testes e analises de ocorrências envolvendo integração EAI, é necessário validar o Xml/Json de envio e de resposta, para extrair os arquivos para análise, realise os passos abaixo:

  • Acesse o ambiente SIGACFG: Ambiente > Schedule > Adapter EAI

Na integração do Software com o Protheus, são criados os arquivos de transações.

  • Selecione o arquivo que integrou e para extrair clique na lupa  . Será exibido as opções para extrair
    • ENVIO: Visualizar mensagem original: Xml/Json com os dados que o sistema tentou integrar;
    • RESPOSTA: Visualizar mensagem de resposta: Xml/Json com a resposta da tentativa de integração.

Através da Tag <Product> consegue visualizar o Software que esta recebendo ou enviando. Exemplo:

XML de envio (original): <Product version="12.1.18.0" name="RM"/>

XML de recebimento (resposta): <Product version="12" name="PROTHEUS"/>

Durante a análise de ocorrências no processo de integração, pode ser necessário gerar o Profile para analise das funções executadas ou do tempo de processamento.

Para gerar o Profiler no processo de integração é necessário:

  • Em seu appserver.ini na chave/bloco que carrega o nome do JOB do WebServices [JOB_WS_XXXX]
  • Inclua uma linha: "PROFILE=1" e depois salve o arquivo (Atalho: CTRL + S)

[JOB_WS_9901]
TYPE=WEBEX
ENVIRONMENT=12.1.2310
INSTANCES=1,1
SIGAWEB=WS
INSTANCENAME=ws
ONSTART=__WSSTART
ONCONNECT=__WSCONNECT
PREPAREIN=99,01
PROFILE=1            <-------- Insira essa chave
SECURITY=0
  • Para desabilitar a geração do log, basta alterar para "PROFILE=0"


Ao integrar/tentar integrar, será gerado um arquivo .txt de log na pasta protheus > protheus_data > wsprofiler:


2 - Configuração do WebService (caso XML) ou REST (caso JSON)

Para realizar a integração EAI utilizando arquivos Json, é necessário ter um REST funcionando no ambiente.

Para configurar o REST siga as orientações do vídeo: Configuração do REST

Exemplo de configuração do REST: Exemplo de REST

Configurando Web Services

A configuração inicia-se habilitando o serviço HTTP e configurando a porta que todos os outros serviços dependentes deste irão utilizar para a publicação das informações:

  • Acesse o Wizard de configuração dos Serviços;
  • Em Servidor Internet (HTTP/FTP), verifique se o serviço de HTTP já existe, confirme se está habilitado e para qual porta está configurada. Pois estas são informações indispensáveis para o correto funcionamento dos WebServices e Portais.
  • Caso não tenha o Servidor Internet <HTTP> criado, é necessário seguir o procedimento abaixo:

  • Realize o Download dos Arquivos de Portais (web_files) do Portal do Cliente
  • Inclua uma pasta web dentro da Protheus Data do Sistema e insira os web_files
  • Selecionar a opção: <HTTP> e clicar na barra superior <Editar> conforme exemplo
  • O sistema apresentará a tela para Configuração da Seçãoonde os principais campos são:
    1. Flag para Habilitar o Protocolo
    2. Path de Arquivos = Caminho da Pasta Web
    3. Ambiente = Nome do Ambiente
    4. Porta de Conexão = Porta de configuração dos Serviços

Na configuração da Seção, inserimos como exemplo a porta 92, porém ela pode ser alterada caso prefira.

Caso definida a porta padrão do serviço HTTP que é a 80, não é necessário especificá-la na configuração do WS e Portais.


Basta confirmar e gravar as configurações


  • Realize as configurações básicas, campos importantes:
    1. Módulo Web = WS - TOTVS Linha Protheus Web Services
    2. Nome da Instância = ws
    3. Diretório Raiz das Imagens (Web Path) = Diretório da Pasta Web onde o sistema irá criar a pasta "ws"
    4. Selecione o Environment = Nome do Ambiente
    5. Flag para habilitar processos na inicialização do Servidor

  • Realize a Configuração de Host x Empresas/Filiais, campos importantes:
    1. Host = Server e porta dos Web Services (Deve ser informada a porta informada na Configuração HTTP/FTP)
    2. Selecione a Empresa/Filial = Empresa e Filial de acesso (Para configuração Multifilial, consulte a respectiva aba)
    3. Clique em "Relacionar" e em "Avançar"

  •  Realize a Configuração de Usuários, onde irá definir o número mínimo e máximo de usuários para acesso

Finalizar e confirmar a configuração.


Após as configurações acima, o sistema irá inserir as informações de acesso aos Web Services no arquivo AppServer.ini do Protheus, verifique se as informações estão de acordo com o exemplo abaixo, caso não estejam realize ajustes (Lembrando que a Porta e o Nome do Ambiente serão os que preencheu durante a configuração):

[HTTP]

ENABLE=1

PORT=81


[localhost:92/ws]

ENABLE=1

PATH=c:\seuambiente\Protheus_Data\web\ws

ENVIRONMENT=12.1.025

INSTANCENAME=ws

RESPONSEJOB=JOB_WS_9901

DEFAULTPAGE=wsindex.apw


[JOB_WS_9901]

TYPE=WEBEX

ENVIRONMENT=12.1.025                                         

INSTANCES=1,1

SIGAWEB=WS

INSTANCENAME=ws

ONSTART=__WSSTART

ONCONNECT=__WSCONNECT

LOGPROFILE = 0

PREPAREIN=99,01

SECURITY=0

Veja o vídeo do processo de configuração dos Web Services: Configurando os Web Services

O vídeo está no Google Drive do Suporte FAT / SERV / JUR, caso execute no Navegador do Chrome, a qualidade do vídeo pode ficar mais baixa, sendo esse o caso, é possível fazer o Download do arquivo e a qualidade será bem melhor.

A partir da release 12.1.33, torna-se obrigatório o uso da chave SECURITY = 0 na configuração dos WebServices no appserver.ini do AppServer: https://tdn.totvs.com/x/aiErI

Fique atento ao utilizar o parâmetro de configuração com a chave Security=0, pois isso fará com que as integrações (APIs) não exijam autenticação, consequentemente dados do seu ambiente poderão ser consultados sem qualquer controle de autorização.

Escolha sua ferramenta preferida para testes:

SoapUI

O SOAPUI é uma ferramenta de mercado onde conseguimos simular o envio do Xml/Json na integração via Mensagem Única, simulando o envio de outros sistemas para o Protheus.
Ou seja, ao invés de termos que instalar o outro sistema e aprender como fazer o processo neles, nós pegamos um Xml/Json de modelo enviamos para o Protheus usando esta ferramenta.

Link para baixar o Soap: https://www.soapui.org/downloads/latest-release/

Veja o vídeo do processo de configuração do SOAPUI: Configurando a ferramenta SoapUI

O vídeo está no Google Drive do Suporte FAT / SERV / JUR, caso execute no navegador Google Chrome, a qualidade do vídeo pode ficar mais baixa, sendo esse o caso, é possível fazer o Download do arquivo para superior qualidade.

Caso a integração seja via arquivo Xml, a seguinte Tag deve ser acrescentada:

<![CDATA[

(XML Conteúdo que irá dentro da TAG)

]]>



Este teste permite testar o recebimento da Mensagem Única de outro sistema para o Protheus.

Para iniciar os testes é necessário que tenha realizado as etapas:

  1. Cadastro do Adapter
  2. De/Para de Empresas e Filiais
  3. De/Para de Mensagem Única (Se for o teste da rotina MATA410)
  4. Configurando os Web Services
  5. Configurando o SOAPUI


Simulação da integração:


Exemplos de XML para testes de integração EAI:

Integração EAI Protheus (SIGAFAT) com destino à outros sistemas


Este teste permite testar o recebimento da Mensagem Única de outro sistema para o Protheus.

Para iniciar os testes é necessário que tenha realizado as etapas:

  1. Cadastro do Adapter
  2. De/Para de Empresas e Filiais
  3. Exemplo de REST
  4. Configuração do REST
  5. Configurando o SOAPUI


  • Caso seja necessário a utilização de um Json enviado pelo cliente no teste, é necessário criar um De/Para de Mensagem única para os códigos referenciados no cadastro
    Exemplo: Código de Vendedor no campo A1_VEND, é necessário criar um de/para de mensagem única usando o " VendorInformationInternalID" como "Valor Externo" e no "Valor interno" é preciso informar a empresa, a filial e o código do vendedor como neste exemplo.

Este teste permite testar o envio da Mensagem única do Protheus para outro sistema.

Para iniciar os testes é necessário que tenha realizado as etapas:

  1. Cadastro de Rotas EAI
  2. Cadastro do Adapter
  3. Cadastro do Schedule
  4. Cadastro do Agent
  5. Teste de Envio




4 - Testando