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?appID={appID}&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 | appId - 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 appID 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": [ { "appID": "PRODUCAO18", "product": "PROTHEUS", "companies": [ { "company": "18", "branch": "D MG 01", "integratedProducts": [ { "appId": "AMBIENTE", "product": "RM", "company": "01", "branch": "01" }, { "appId": "AMBX", "product": "DATASUL", "company": "1", "branch": "10" } ] }, { "company": "18", "branch": "D RJ 01", "integratedProducts": [ { "appId": "AMBIENTE", "product": "RM", "company": "01", "branch": "02" }, { "appId": "AMBX", "product": "DATASUL", "company": "1", "branch": "11" } ] } ] }, { "appID": "PRODUCAO19", "product": "PROTHEUS", "companies": [ { "company": "19", "branch": "D MG 01", "integratedProducts": [ { "appId": "AMBIENTE", "product": "RM", "company": "02", "branch": "02" } ] } ] } ] } |
Exemplo de retorno
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : { "appID" : "PRODUCAO19", "product" : "PROTHEUS", "companies" : [{ "company" : "19", "branch" : "D MG 01", "integratedProducts" : [{ "appId" : "AMBIENTE", "product" : "RM", "company" : "02", "branch" : "02" } ] } ] } } |
Âncora | ||||
---|---|---|---|---|
|
O método GET /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage} já criado para o monitor EAI será alterado, e um novo atributo será incluído no JSON:
avaiableVersions - 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 "avaiableVersions" : "1.000;1.001" } ] } |
Âncora | ||||
---|---|---|---|---|
|
GET /totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?appID={appid}&version={version}&suportedMode={suportedMode}&enableMode={enableMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&avaiableVersions={avaiableVersions}
Recebe | appID - string - Query param |
version - string - query param | |
suportedMode - string - query param | |
enableMode - string - query param | |
allowAnonymous - boolean - query param | |
includeOriginalMsg - boolean - query param | |
avaiableVersions - 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 appID 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 appID 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, suportedMode, enableMode, allowAnonymous, includeOriginalMsg e avaiableVersions, 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 dasdos seguem os valores do retorno do método GET /totvseai/monitor/v1/apps/{appID}/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" : { "transactioID" "transactioID: "order", "messages" : "order", [{ "code" : "FW006" "text" : "Filial de execução - 001" } ] } } |
Âncora | ||||
---|---|---|---|---|
|
GET GET /totvseai/monitor/v1/admin/healthcheck/checktransactions/business?appID={appid}&version={version}&suportedMode={suportedMode}&transactionsenableMode={jSON}enableMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&avaiableVersions={avaiableVersions}
Recebe | appID - string - Query param |
version - string - query param | |
suportedMode - string - query param | |
enableMode - string - query param | |
allowAnonymous - boolean - query param | |
includeOriginalMsg - boolean - query param | |
avaiableVersions - string - query param | |
Recebe | appID - string - Query param |
transactions - jSON - 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 appID 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 appID 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.
o parâmetro transactions, opcional, quando enviado fará Os parâmetros version, suportedMode, enableMode, allowAnonymous, includeOriginalMsg e avaiableVersions, opcionais, quando enviados farão a consistência de uma transação (adapter) cadastrado em um aplicativo A contra um aplicativo B. A estrutura deste jSON é o mesmo Os valores permitidos para estes dasdos seguem os valores do retorno do método GET /totvseai/monitor/v1/apps/{appID}/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 de jSON destes parâmetros é opcional pois existem validações internas que independem do cadastro de outro sistema. Desta forma, se o JSON não for recebido pelo serviço, somente estas validações deverão ser verificadas.
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?appID={appid}&transactions={jSONversion={version}&suportedMode={suportedMode}&enableMode={enableMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&avaiableVersions={avaiableVersions}
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : [{ "transactioID" : "financing", "messages" : [{ "code" : "" "text" : "É necessário configurar o parâmetro MV_MULNATP e MV_MULNATR na integração com o TOTVS Incorporações." } } |
]
}
]
}
|
Âncora |
---|
Check_empresas |
|
|
GET /totvseai/monitor/v1/admin/healthcheck/getcompanies/{appID}/{companyID}/{branchID}
Recebe | appID - |
Recebe | appID - string - path param |
companyID - 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" "messages" : [{ "code" : "FI001" "text" : "" } ] } } |
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "messages" : [], "length" : 1, "data" : { "originCompany" : "01", "originBranch" : "01" "destinationCompany" : "" "destinationBranch" : "" "codemessages" :"FE009" [{ "code" : "FE009" "text" : "" } ] } } |
Âncora | ||||
---|---|---|---|---|
|
GET /totvseai/monitor/v1/admin/healthcheck/wsintegration/{appID}/{companyIdcompanyID}/{branchID}
Recebe | appID - 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 appID é 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 appID 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" : { "originAppID" : "PRODUCAO18@PROTHEUS", "destinationAppID" : "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.
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.
POST WhoIS
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.
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.
Os valores de companyID e branchID são recuperados pelo método GET /totvseai/monitor/v1/admin/companies/{appID}/{companyID}/{branchID}?page={page}&perPage={perPage}
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
<soapenv:Envelope xmlns:soapenv="http://schemas. | ||||||
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_>: Refere-se à URL base dos serviços EAI que são consumidos.
<URL_monitor_externo_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo externo.
Â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. |
---|