Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|
Especificação | |||||||||||||||||||
Produto | TOTVS | Módulo | EAI | ||||||||||||||||
Segmento Executor | Framework | ||||||||||||||||||
Projeto1 | FRAMEWORK SP - 005 | IRM1 |
| ||||||||||||||||
Requisito1 |
| Subtarefa1 |
| ||||||||||||||||
País | ( ) Brasil ( ) Argentina ( ) Mexico ( ) Chile ( ) Paraguai ( ) Equador ( ) USA ( ) Colombia ( X ) TODOS. | ||||||||||||||||||
Outros |
Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos).
Descrever os serviços necessários para que o monitor do TOTVS EAI consiga realizar o diagnóstico dos serviços/integrações habilitadas entre os produtos integrados.
Os serviços de diagnósticos disponibilizados pelos produtos deverão atender os seguintes pré-requisitos:
Todas as linhas de produto deverão definir uma URL base, a partir da qual os serviços REST do monitor de EAI serão disponibilizados. Todos os caminhos descritos neste documento serão relativos a esta URL base, conforme a especificação de requisitos ER_FRWJOI01-3_Serviços_para_monitoramento_de_EAI.
Os objetos de retorno dos métodos REST seguem o retorno especificado no requisito ER_FRWJOI01-3_Serviços_para_monitoramento_de_EAI.
Todas as linhas de produto deverão disponibilizar no monitor os caminhos dos serviços do EAI de seus produtos.
Todos os parâmetros de query string page e perPage, quando não especificados, assumem o valor default de 1 e 10, respectivamente.
GET /totvseai/monitor/v1/admin/companies?targetAppID={targetAppID}&companyID={companyID}&branchID={branchId}&page={page}&perPage={perPage} Âncora /totvseai/monitor/v1/admin/companies/{appID}/{companyID}/{branchID}?page={page}&perPage={perPage} /totvseai/monitor/v1/admin/companies/{appID}/{companyID}/{branchID}?page={page}&perPage={perPage}
Busca de empresas e filiais associadas (De-para de empresas)
Recebe | targetAppID - string - query param |
companyID - string - query param | |
branchID - string - query param | |
page - int - query param | |
perPage - int - query param | |
Retorna | Application/JSON |
Este método lista os de-para de empresas do aplicativo interno.
Caso o parâmetro targetAppID seja enviado, é buscado a informação do relacionamento somente para o aplicativo em questão. Caso contrário, é buscado todas as informações dos aplicativos disponiveis (no Protheus uma mesma instalação pode possuir mais de um aplicativo, pois cada Grupo de empresas Protheus comporta um aplicativo).
É possível buscar informações de um aplicativo externo a partir de um aplicativo interno (realizar a busca no Protheus somente das empresas associadas ao RM, por exemplo)
Pode-se também enviar os parâmetros de companyID (para buscar o mapeamento somente de uma empresa/grupo daquele aplicativo) e branchID, para buscar somente daquela filial.
Retorno esperado:
Exemplo de retorno
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages": [], "length": 2, "data": [ { "targetAppID": "PRODUCAO18", "product": "PROTHEUS", "companies": [ { "company": "18", "branch": "D MG 01", "integratedProducts": [ { "targetAppID": "AMBIENTE", "product": "RM", "company": "01", "branch": "01" }, { "targetAppID": "AMBX", "product": "DATASUL", "company": "1", "branch": "10" } ] }, { "company": "18", "branch": "D RJ 01", "integratedProducts": [ { "targetAppID": "AMBIENTE", "product": "RM", "company": "01", "branch": "02" }, { "targetAppID": "AMBX", "product": "DATASUL", "company": "1", "branch": "11" } ] } ] }, { "targetAppID": "PRODUCAO19", "product": "PROTHEUS", "companies": [ { "company": "19", "branch": "D MG 01", "integratedProducts": [ { "targetAppID": "AMBIENTE", "product": "RM", "company": "02", "branch": "02" } ] } ] } ] } |
Exemplo de retorno
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : { "targetAppID" : "PRODUCAO19", "product" : "PROTHEUS", "companies" : [{ "company" : "19", "branch" : "D MG 01", "integratedProducts" : [{ "targetAppID" : "AMBIENTE", "product" : "RM", "company" : "02", "branch" : "02" } ] } ] } } |
Âncora | ||||
---|---|---|---|---|
|
O método GET /totvseai/monitor/v1/apps/{targetAppID}/transactions?page={page}&perPage={perPage} já criado para o monitor EAI será alterado, e um novo atributo será incluído no JSON:
availableVersions - Indica as versões disponíveis para configuração da transação em questão. As diferentes versões disponíveis serão separadas por ";".
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : [{ "transactionID" : "order", "version" : "2.000", "supportedMode" : "both_enabled", "enabledMode" : "both_enabled", "allowAnonymous" : false, "includeOriginalMsg" : false "availableVersions" : "1.000;1.001" } ] } |
Âncora | ||||
---|---|---|---|---|
|
Recebe | targetAppID - string - Query param |
transactionID - string - query param | |
version - string - query param | |
supportedMode - string - query param | |
enabledMode - string - query param | |
allowAnonymous - boolean - query param | |
includeOriginalMsg - boolean - query param | |
availableVersions - string - query param | |
Retorna | Application/JSON |
Este serviço verifica a integridade da integração de acordo com as transações habilitadas em um aplicativo na camada do EAI (framework).
O parâmetro targetAppID informa o aplicativo na origem da requisição. Por exemplo, o monitor quer validar informações colhidas no RM e validar contra estas informações no Protheus. Neste caso, o targetAppID seria RM. O intuito deste parâmetro é poder verificar a consistência das rotas. Caso ele não seja enviado, informações de validações das rotas não serão verificadas.
Os parâmetros version, supportedMode, enabledMode, allowAnonymous, includeOriginalMsg e availableVersions, opcionais, quando enviados farão a consistência de uma transação (adapter) cadastrado em um aplicativo A contra um aplicativo B. Os valores permitidos para estes dados seguem os valores do retorno do método GET /totvseai/monitor/v1/apps/{targetAppID}/transactions?page={page}&perPage={perPage}.
O retorno esperado para este método é um outro jSON, que retornará a compatibilidade ou não das transações enviadas x transações no aplicativo.
O envio destes parâmetros é opcional pois existem validações internas que independem do cadastro de outro sistema.
JSON de retorno esperado:
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" :[ { "transactioIDtransactionID" : "order", "messages" : [{ "code" : "FW006" "text" : "Filial de execução - 001" } ] } ] } |
Âncora | ||||
---|---|---|---|---|
|
Recebe | targetAppID - string - Query param |
version - string - query param | |
supportedMode - string - query param | |
enabledMode - string - query param | |
allowAnonymous - boolean - query param | |
includeOriginalMsg - boolean - query param | |
availableVersions - string - query param | |
Retorna | Application/JSON |
Este serviço verifica a integridade da integração de acordo com as transações habilitadas em um aplicativo na camada de negócio (business).
O parâmetro targetAppID informa o aplicativo na origem da requisição. Por exemplo, o monitor quer validar informações colhidas no RM e validar contra estas informações no Protheus. Neste caso, o targetAppID seria RM. O intuito deste parâmetro é poder verificar a consistência das rotas. Caso ele não seja enviado, informações de validações das rotas não serão verificadas.
Os parâmetros version, supportedMode, enabledMode, allowAnonymous, includeOriginalMsg e availableVersions, opcionais, quando enviados farão a consistência de uma transação (adapter) cadastrado em um aplicativo A contra um aplicativo B. Os valores permitidos para estes dados seguem os valores do retorno do método GET /totvseai/monitor/v1/apps/{targetAppID}/transactions?page={page}&perPage={perPage}.
O retorno esperado para este método é um outro jSON, que retornará a compatibilidade ou não das transações enviadas x transações no aplicativo.
O envio destes parâmetros é opcional pois existem validações internas que independem do cadastro de outro sistema.
As áreas de negócio deverão ser responsáveis por permitir ou não validação de terceiros (customizações) em suas rotinas.
JSON de retorno esperado:
Caberá a cada framework como identificar a melhor maneira possível de realizar as chamadas as validações de cada área de negócio envolvida na integração.
No Protheus os adapters serão chamados e os dados recebidos na requisição REST serão repassados para cada um dos adapters, que serão responsáveis por realizar as validações internas necessárias. Caso não haja tratamento para a CHECKINTEGRITY é assumido que não existe validação necessária para o adapter.
O retorno esperado segue o proposto pelo método /totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?targetAppID={targetAppID}&transactionId={transactionID}&version={version}&supportedMode={supportedMode}&enabledMode={enabledMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&availableVersions={availableVersions}
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : [{ "transactioIDtransactionID" : "financing", "messages" : [{ "code" : "" "text" : "É necessário configurar o parâmetro MV_MULNATP e MV_MULNATR na integração com o TOTVS Incorporações." } ] } ] } |
Âncora | ||||
---|---|---|---|---|
|
Recebe | targetAppID - string - path param |
companyID - string - path param | |
branchId - string - path param | |
Retorna | Application/JSON |
Este serviço verifica a integridade dos mapeamentos de empresa/filial entre o aplicativo origem e destino
Somente o parâmetro branchID é opcional.
O JSon esperado por este método deve possuir os atributos a seguir:
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : { "originCompany" : "01", "originBranch" : "05", "destinationCompany" : "18", "destinationBranch" : "D MG 01", "destinationAppID" : "RM", "messages" : [{ "code" : "FI001" "text" : "" } ] } } |
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : { "originCompany" : "01", "originBranch" : "01" "destinationCompany" : "" "destinationBranch" : "" "messages" : [{ "code" : "FE009" "text" : "" } ] } } |
Âncora | ||||
---|---|---|---|---|
|
Recebe | targetAppID - string - path param |
companyID - string - path param | |
branchId - string - path param | |
Retorna | Application/JSON |
Este serviço realiza o teste de envio de WhoIs a outro sistema partindo de um erp (existe um método de verificação partindo do próprio monitor). O intuito deste serviço é testar se a comunicação entre os ERPs está funcionando de maneira satisfatória.
Este método é disparado visando validar a integração de um sistema A contra um sistema B. Neste cenário, o serviço REST é enviado ao sistema A, e o parâmetro targetAppID é enviado com o valor de B. O sistema A então irá validar se a integração com o sistema B está operante através de envio da mensagem WhoIS. O sistema A então devolve o status para o serviço do monitor.
O parâmetro targetAppID recebe o valor do aplicativo ao qual o destino deverá tentar conectar-se.
O parâmetro companyID recebe o valor da empresa/grupo de empresas.
o parâmetro branchID é opcional, e recebe o valor da filial buscada.
O jSon de retorno esperado para este método contém os seguintes atributos:
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : { "origintargetAppID" : "PRODUCAO18@PROTHEUS", "destinationtargetAppID" : "RM@RM", "originCompany" : "18", "originBranch" : "D MG 01", "messages" : [{ "code" : "F001" "text" : "" } ] } } |
Serviços SOAP - Originados do Monitor EAI para o serviço de EAI do aplicativo
Os serviços SOAP a seguir visam reutilizar os serviços de EAI - Mensagem Única já existentes nos produtos. Eles tem como originador o Monitor Totvs EAI e tem como destino os serviços de EAI dos aplicativos cadastrados.
Verificação de WSDL e autenticação Âncora WsGetStatus WsGetStatus
Serviço que verifica se o servidor do serviço do EAI está disponível.
O serviço irá gerar uma requisição de consulta ao WSDL do serviço do EAI cadastrado para o aplicativo.
A URL para obtenção do WSDL será obtida do retorno do serviço apps, no atributo wsdlUrl, e os dados para autenticação serão obtidos do arquivo monitor-url-list.json.
GET http://localhost:8080/eaiservice.apw
Bloco de código | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="utf-8"?> <!-- Generated 20160927 10:35:39 by ADVPL WSDL Server 1.110216 / Protheus 7.00.131227A-20160909 NG --> <definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:s0="http://www.totvs.com/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" targetNamespace="http://www.totvs.com/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <s:schema elementFormDefault="qualified" targetNamespace="http://www.totvs.com/"> <s:element name="RECEIVEMESSAGE"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="INMSG" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="RECEIVEMESSAGERESPONSE"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="RECEIVEMESSAGERESULT" type="s:string" /> </s:sequence> </s:complexType> </s:element> </s:schema> </types> <message name="RECEIVEMESSAGESOAPIN"> <part name="parameters" element="s0:RECEIVEMESSAGE" /> </message> <message name="RECEIVEMESSAGESOAPOUT"> <part name="parameters" element="s0:RECEIVEMESSAGERESPONSE" /> </message> <portType name="EAISERVICESOAP"> <operation name="RECEIVEMESSAGE"> <documentation>Metodo que recebe mensagens para processamento pelo Microsiga Protheus</documentation> <input message="s0:RECEIVEMESSAGESOAPIN" /> <output message="s0:RECEIVEMESSAGESOAPOUT" /> </operation> </portType> <binding name="EAISERVICESOAP" type="s0:EAISERVICESOAP"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" /> <operation name="RECEIVEMESSAGE"> <soap:operation soapAction="http://www.totvs.com/RECEIVEMESSAGE" style="document" /> <input> <soap:body use="literal" /> </input> <output> <soap:body use="literal" /> </output> </operation> </binding> <service name="EAISERVICE"> <documentation><b>Serviço genérico de integração com o Microsiga Protheus via EAI</b></documentation> <port name="EAISERVICESOAP" binding="s0:EAISERVICESOAP"> <soap:address location="http://172.16.32.191:89/pr12_bra/eai/EAISERVICE.apw" /> </port> </service> </definitions> |
Caso seja necessária autenticação no aplicativo destino, a mesma deverá ser enviada no header da requisição, via basic authentication. Para isto será necessário cadastrar o usuário de acesso ao EAI no monitor (o usuário de acesso nem sempre é o usuário logado no monitor).
Âncora | ||||
---|---|---|---|---|
|
Serviço que visa verificar se o aplicativo destino está recebendo requisições normalmente.
Este serviço irá realizar o post da Mensagem Única TOTVS WhoIs e irá aguardar o retorno da requisição.
A mensagem única TOTVS espera um código de empresa e filial para mapeamento de integrações. Este empresa e filial será capturada pelo método GET /totvseai/monitor/v1/admin/getcompanies. Para Datasul e Logix não existe a necessidade de envio destes valores.
O SourceApplication e Product enviados na mensagem serão padronizados como "TOTVSMONITOR". O atributo version da tag Product será enviado com a versão "1.000".
O retorno deste método definirá se o EAI está disponível para recebimento (serviço disponível no ar) e se houve sucesso na autenticação. A verificação será realizada pelo retorno do status da conexão HTTP e pelo retorno da mensagem do tipo ResponseMessage.
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tot="http://www.totvs.com/"> <soapenv:Header/> <soapenv:Body> <tot:receiveMessage> <tot:inMsg><![CDATA[ <?xml version="1.0" encoding="utf-8"?> <TOTVSMessage> <MessageInformation version="1.000"> <UUID>dee8c4da-1e19-4b44-df97-249443638a9d</UUID> <Type>BusinessMessage</Type> <Transaction>WHOIS</Transaction> <StandardVersion>1.000</StandardVersion> <SourceApplication>TOTVSMONITOR</SourceApplication> <CompanyId>18</CompanyId> <BranchId>D MG 01</BranchId> <Product name="TOTVSMONITOR" version="1.000"></Product> <GeneratedOn>2015-11-26T10:55:23</GeneratedOn> <DeliveryType>Sync</DeliveryType> </MessageInformation> <BusinessMessage> <BusinessRequest> <Operation>WhoIs</Operation> </BusinessRequest> <BusinessContent/> </BusinessMessage> </TOTVSMessage>]]></tot:inMsg> </tot:receiveMessage> </soapenv:Body> </soapenv:Envelope> |
O retorno esperado da Mensagem Única WhoIs deverá ser semelhante ao seguinte:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <RECEIVEMESSAGERESPONSE xmlns="http://www.totvs.com/"> <RECEIVEMESSAGERESULT><?xml version="1.0" encoding="utf-8"?><TOTVSMessage><MessageInformation version="1.001"><UUID>66a7fdd0-ec4d-ac9a-0915-4a0c17a75cd4</UUID><Type>Response</Type><Transaction>WHOIS</Transaction><StandardVersion>1.000</StandardVersion><SourceApplication>PR12_BRA</SourceApplication><CompanyId>18</CompanyId><BranchId>D MG 01 </BranchId><Product name="PROTHEUS" version="12"></Product><GeneratedOn>2016-09-27T17:05:16Z</GeneratedOn><DeliveryType>Sync</DeliveryType></MessageInformation><ResponseMessage><ReceivedMessage><SentBy>TOTVSMONITOR</SentBy><UUID>dee8c4da-1e19-4b44-df97-249443638a9d</UUID><MessageContent><![CDATA[<?xml version="1.0" encoding="utf-8"?><TOTVSMessage><MessageInformation version="1.000"><UUID>dee8c4da-1e19-4b44-df97-249443638a9d</UUID><Type>BusinessMessage</Type><Transaction>WHOIS</Transaction><StandardVersion>1.000</StandardVersion><SourceApplication>TOTVSMONITOR</SourceApplication><CompanyId>18</CompanyId><BranchId>D MG 01</BranchId><Product name="TOTVSMONITOR" version="1.000"></Product><GeneratedOn>2015-11-26T10:55:23</GeneratedOn><DeliveryType>Sync</DeliveryType></MessageInformation><BusinessMessage><BusinessRequest><Operation>WhoIs</Operation></BusinessRequest><BusinessContent></BusinessContent></BusinessMessage></TOTVSMessage>]]></MessageContent></ReceivedMessage><ProcessingInformation><ProcessedOn>2016-09-27T17:05:16Z</ProcessedOn><Status>ok</Status></ProcessingInformation><ReturnContent><EnabledTransactions><Transaction><Name>WHOIS</Name><Version>1.001 </Version><Mode>both_enabled</Mode></Transaction><Transaction><Name>MYMESSAGE</Name><Version>1.000 </Version><Mode>send_enabled</Mode></Transaction><Transaction><Name>COSTCENTER</Name><Version>2.000 </Version><Mode>both_enabled</Mode></Transaction><Transaction><Name>FINANCIALNATURE</Name><Version>2.000 </Version><Mode>both_enabled</Mode></Transaction><Transaction><Name>ACCOUNTRECEIVABLEDOCUMENTDISCHARGE</Name><Version>2.001 </Version><Mode>both_enabled</Mode></Transaction><Transaction><Name>CUSTOMERVENDOR</Name><Version>2.002 </Version><Mode>both_enabled</Mode></Transaction><Transaction><Name>BANK</Name><Version>1.007 </Version><Mode>both_enabled</Mode></Transaction></EnabledTransactions></ReturnContent></ResponseMessage></TOTVSMessage></RECEIVEMESSAGERESULT> </RECEIVEMESSAGERESPONSE> </soap:Body> </soap:Envelope> |
O objetivo desta seção é demonstrar como cumprir tarefas de diagnóstico do EAI através dos serviços disponibilizados. A tarefa é descrita como tópico principal, e os passos para cumpri-la são descritos como subtópicos.
Os seguintes "placeholders" são utilizados nas URLs abaixo:
<URL_monitor_local_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo interno.
<URL_monitor_externo_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo externo.
<URL_EAI_interno_SOAP>: Refere-se à URL base dos serviços EAI que são consumidos no aplicativo interno.
<URL_EAI_externo_SOAP>: Refere-se à URL base dos serviços EAI que são consumidos no aplicativo externo.
<URL_monitor_externo_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo externo.
GET <URL_monitor_externo_REST>/totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?targetAppID=<App_interno>&version={version}&supportedMode={supportedMode}&enabledMode={enabledMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&availableVersions={availableVersions} , verificando, para cada transação, se a mesma está correta na visão do EAI;
GET <URL_monitor_externo_REST>/totvseai/monitor/v1/admin/healthcheck/checktransactions/business?targetAppID=<app_interno>&version={version}&supportedMode={supportedMode}&enabledMode={enabledMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&availableVersions={availableVersions}, verificando, na camada de negócio, se as transações estão cadastradas de maneira correta.
Âncora | ||||
---|---|---|---|---|
|
Código reservados de Framework | Definição |
FE005 | A transação recebida não está cadastrada neste destino. |
FE006 | A transação recebida não está cadastrada neste destino para recebimento. |
FE007 | A transação recebida não está cadastrada neste destino para envio. |
FE008 | Transações com versões diferentes (incompatíveis) |
FE009 | Empresa/grupo e filial não parametrizados para integração. |
FE010 | Erro no envio da mensagem a outro sistema. |
FW001 | Mensagem cadastrada como assíncrona, mas cadastrada como síncrona no destino. |
FW002 | Mensagem cadastrada como síncrona, mas cadastrada como assíncrona no destino. |
FW003 | Mensagem somente habilitada para eventos de upsert. |
FW004 | Mensagem habilitada somente para eventos de delete. |
FW005 | Mensagem com condição de envio e recebimento habilitada. |
FW006 | Mensagem somente executada em uma filial. |
FW007 | Transações com releases diferentes. |
FI001 | Validado. |
FI002 | Mensagem com validação de XSD. |
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|