Histórico da Página
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico |
---|
Informações Gerais
Especificação | |||
Produto | Datasul | Módulo | EAI |
Segmento Executor | Tecnologia | ||
Projeto1 | PDR_LD_FRW001 | IRM1 | PCREQ-9836 |
Requisito1 | PCREQ-10304 | 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).
Objetivo
Neste desenvolvimento será possível a execução dos objetos de negócio expostos pelo Datasul, através do recebimento de mensagens baseadas no padrão Mensagem Única TOTVS, preparadas para portar os parâmetros de entrada necessários e os dados de retorno gerados após a execução do referido objeto.
Definição da Regra de Negócio
Os aplicativos que fizerem o consumo de objetos de negócio através da Mensageria TOTVS deverão enviar mensagens com o modelo de dados do aplicativo que, naquela integração, possuir o papel de ERP. A definição dos papeis na integração ficará a cargo do segmento que estiver demandando a mesma.
Considerando um cenário onde o Datasul atue como ERP na integração, teremos todas as mensagens trafegadas com o formato de dados do Datasul. Tomando por exemplo uma integração de cadastro de usuários entre Protheus e Datasul, o fluxo será o seguinte:
- Protheus efetua o cadastro de um usuário;
- O objeto de negócio aciona o adapter de integração;
- O adapter de integração converte o modelo de dados Protheus para o modelo de dados Datasul, baseando-se no XML Schema obtido pelo serviço getSchema;
- O adapter de integração envia a mensagem para o engine de EAI do Protheus;
- O engine de EAI envia a mensagem para o webservice de recebimento do Datasul;
- O webservice de recebimento encaminha a mensagem para o engine de EAI do Datasul;
- O engine de EAI identifica o objeto de negócio solicitado na mensagem;
- O engine extrai os dados de entrada da mensagem e aciona o objeto de negocio, passando os dados extraídos como parâmetro;
- O engine recebe os dados de retorno do objeto de negócio;
- A mensagem de retorno é gerada pelo engine de EAI com os dados de saída do objeto de negócio;
- A mensagem de retorno é enviada ao webservice de recebimento do Protheus;
- O webservice de recebimento encaminha a mensagem de retorno para o engine de EAI Protheus;
- O engine de EAI extrai os dados e encaminha para o objeto de negócio Protheus;
- O objeto de negócio recebe os dados, converte do modelo Datasul para o modelo Protheus e processa o retorno.
Pelo fluxo acima, a responsabilidade de conversão dos dados de um modelo para outro fica sob responsabilidade do papel de Vertical, ou seja, o Protheus.
De acordo com a especificação da Mensageria TOTVS, o conteúdo da tag <BusinessContent> de uma mensagem terá o formato descrito no XML Schema do objeto de negócio presente na tag <Transaction>. Nesta tag, o objeto de negócio sempre será precedido pelo nome do ERP (ex: Datasul/fnbo.bofn017, Protheus/MAT030, etc.).
No exemplo abaixo a mensagem - uma BusinessEvent - refere-se ao objeto de negócio fnbo017, um DBO, associado ao cadastro de usuários no Datasul:
Bloco de código | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8"?> <TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/totvsmsg.xsd"> <MessageInformation version="1.000"> <UUID>Fnbobofn-0170-0001-0000-000000000006</UUID> <Type>BusinessMessage</Type> <Transaction>Datasul/fnbo.bofn017</Transaction> <StandardVersion>1.0</StandardVersion> <SourceApplication>SoapUI</SourceApplication> <Product name="SoapUI" version="5.2.1"/> <GeneratedOn>2016-03-17T18:15:00</GeneratedOn> <DeliveryType>Sync</DeliveryType> </MessageInformation> <BusinessMessage> <BusinessEvent> <Entity>Datasul/fnbo.bofn017</Entity> <Event>upsert</Event> <Identification/> </BusinessEvent> <BusinessContent> <RowObjectbofn017> <RowObjectbofn017Row> <cod_usuario>cod_usuar12</cod_usuario> <nom_usuario>usuario_121</nom_usuario> <cod_senha>cod_senha</cod_senha> <cod_idiom_orig>cod_idiom_orig</cod_idiom_orig> <ind_tip_usuar>ind_tip_usuar</ind_tip_usuar> <num_pessoa>0</num_pessoa> <nom_dir_spool>nom_dir_spool</nom_dir_spool> <nom_subdir_spool>nom_subdir_spool</nom_subdir_spool> <cod_servid_exec>cod_servid_exec</cod_servid_exec> <cod_e_mail_local>cod_e_mail_local</cod_e_mail_local> <dat_ult_erro_tentat_aces>2001-01-01</dat_ult_erro_tentat_aces> <hra_ult_erro_tentat_aces>hra_ult_erro_tentat_aces</hra_ult_erro_tentat_aces> <qtd_erro_tentat_aces>0.0</qtd_erro_tentat_aces> <log_servid_exec_obrig>true</log_servid_exec_obrig> <dat_inic_valid>2001-01-01</dat_inic_valid> <dat_fim_valid>2001-01-01</dat_fim_valid> <dat_valid_senha>2001-01-01</dat_valid_senha> <num_dias_valid_senha>0</num_dias_valid_senha> <log_segur_uhr_atlzdo>true</log_segur_uhr_atlzdo> <cod_livre_1>cod_livre_1</cod_livre_1> <cod_livre_2>cod_livre_2</cod_livre_2> <val_livre_1>0.0</val_livre_1> <val_livre_2>0.0</val_livre_2> <num_livre_1>0</num_livre_1> <num_livre_2>0</num_livre_2> <log_livre_1>true</log_livre_1> <log_livre_2>true</log_livre_2> <dat_livre_1>2001-01-01</dat_livre_1> <dat_livre_2>2001-01-01</dat_livre_2> <des_checksum>des_checksum</des_checksum> <num_perf_usuar>0</num_perf_usuar> <des_cod_perf_usuar>des_cod_perf_usuar</des_cod_perf_usuar> <log_mostra_framework>true</log_mostra_framework> <nom_subdir_spool_rpw>nom_subdir_spool_rpw</nom_subdir_spool_rpw> <cod_dialet>cod_dialet</cod_dialet> <log_usuar_wap>true</log_usuar_wap> <cod_e_mail_celular>cod_e_mail_celular</cod_e_mail_celular> <log_usuar_atlzdo_ged>true</log_usuar_atlzdo_ged> <log_ativ_multi_idiom>true</log_ativ_multi_idiom> <idi_tip_login>0</idi_tip_login> <idi_dtsul>1122</idi_dtsul> <idi_dtsul_instan>0</idi_dtsul_instan> <cod_senha_framework>cod_senha_framework</cod_senha_framework> <log_trace>false</log_trace> <num_dia_cont_modul_dtsul>0</num_dia_cont_modul_dtsul> <ind_tip_aces_usuar>Comum</ind_tip_aces_usuar> <log_full_determ>false</log_full_determ> <log_solic_impres>false</log_solic_impres> <des_login_inform>des_login_inform</des_login_inform> </RowObjectbofn017Row> </RowObjectbofn017> </BusinessContent> </BusinessMessage> </TOTVSMessage> |
O respectivo retorno desta mensagem conterá os dados recebidos na mensagem original, com as devidas atualizações, realizadas pelo objeto de negócio. Estes dados serão enviados na tag <XMLContent>, subordinada à tag <ReturnContent> (vide exemplo a seguir).
Nota |
---|
Apesar de não constar nos exemplos utilizados nesta documentação, as mensagens de retorno sempre conterão o corpo da mensagem original, o qual constará na tag <MessageContent> subordinada à tag <ReceivedMessage>. |
O exemplo abaixo demonstra uma mensagem de retorno gerada após a execução da DBO solicitada.
Bloco de código | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8" ?> <TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/totvsmsg.xsd"> <MessageInformation version="12.1.1"> <UUID>af468991-b5c7-8d82-0d14-1a304c481181</UUID> <Type>Response</Type> <Transaction>datasul/fnbo.bofn017</Transaction> <StandardVersion>1.0</StandardVersion> <SourceApplication>jvd001651</SourceApplication> <CompanyId/> <Product name="Datasul" version="11.5.X"/> <GeneratedOn>2016-04-06T16:36:46.238-03:00</GeneratedOn> </MessageInformation> <ResponseMessage> <ReceivedMessage> <SentBy>Protheus-SoapUI</SentBy> <UUID>Fnbobofn-0170-0001-0000-000000001450</UUID> </ReceivedMessage> <ProcessingInformation> <ProcessedOn>2016-04-06T16:36:46.238-03:00</ProcessedOn> <Status>OK</Status> </ProcessingInformation> <ReturnContent> <XMLContent> <RowObjectbofn017 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <RowObjectbofn017Row> <cod_usuario>test889</cod_usuario> <nom_usuario>Usuário de teste #306</nom_usuario> <cod_senha>cod_senha</cod_senha> <cod_idiom_orig>por</cod_idiom_orig> <ind_tip_usuar>Comum</ind_tip_usuar> <num_pessoa>0</num_pessoa> <nom_dir_spool>nom_dir_spool</nom_dir_spool> <nom_subdir_spool>nom_subdir_spool</nom_subdir_spool> <cod_servid_exec>cod_servid_exec</cod_servid_exec> <cod_e_mail_local>cod_e_mail_local</cod_e_mail_local> <dat_ult_erro_tentat_aces>2001-01-01</dat_ult_erro_tentat_aces> <hra_ult_erro_tentat_aces>000000</hra_ult_erro_tentat_aces> <qtd_erro_tentat_aces>0.0</qtd_erro_tentat_aces> <log_servid_exec_obrig>true</log_servid_exec_obrig> <dat_inic_valid>2001-01-01</dat_inic_valid> <dat_fim_valid>2001-01-01</dat_fim_valid> <dat_valid_senha>2001-01-01</dat_valid_senha> <num_dias_valid_senha>0</num_dias_valid_senha> <log_segur_uhr_atlzdo>true</log_segur_uhr_atlzdo> <cod_livre_1>cod_livre_1</cod_livre_1> <cod_livre_2>cod_livre_2</cod_livre_2> <val_livre_1>0.0</val_livre_1> <val_livre_2>0.0</val_livre_2> <num_livre_1>0</num_livre_1> <num_livre_2>0</num_livre_2> <log_livre_1>true</log_livre_1> <log_livre_2>true</log_livre_2> <dat_livre_1>2001-01-01</dat_livre_1> <dat_livre_2>2001-01-01</dat_livre_2> <des_checksum>des_checksum</des_checksum> <num_perf_usuar>0</num_perf_usuar> <des_cod_perf_usuar>des_cod_perf_usuar</des_cod_perf_usuar> <log_mostra_framework>true</log_mostra_framework> <nom_subdir_spool_rpw>nom_subdir_spool_rpw</nom_subdir_spool_rpw> <cod_dialet>cod_dialet</cod_dialet> <log_usuar_wap>true</log_usuar_wap> <cod_e_mail_celular>cod_e_mail_celular</cod_e_mail_celular> <log_usuar_atlzdo_ged>true</log_usuar_atlzdo_ged> <log_ativ_multi_idiom>true</log_ativ_multi_idiom> <idi_tip_login>0</idi_tip_login> <idi_dtsul>211</idi_dtsul> <idi_dtsul_instan>0</idi_dtsul_instan> <cod_senha_framework>cod_senha_framework</cod_senha_framework> <log_trace>false</log_trace> <num_dia_cont_modul_dtsul>0</num_dia_cont_modul_dtsul> <ind_tip_aces_usuar>Interno</ind_tip_aces_usuar> <log_full_determ>false</log_full_determ> <log_solic_impres>false</log_solic_impres> <des_login_inform>des_login_inform</des_login_inform> <r-Rowid>AAAAAAALlMg=</r-Rowid> </RowObjectbofn017Row> </RowObjectbofn017> </XMLContent> </ReturnContent> </ResponseMessage> </TOTVSMessage> |
Para mensagens enviadas requisitando a execução de serviços (APIs), a estrutura básica se mantém, havendo diferenças no tipo de mensagem, que será uma BusinessRequest, e na tag <BusinessContent>. Veja exemplo:
Bloco de código | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8"?> <TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/totvsmsg.xsd"> <MessageInformation version="1.000"> <UUID>btapi930-za00-0001-0000-000000001357</UUID> <Type>BusinessMessage</Type> <Transaction>Datasul/btb.btapi930za.getProfile</Transaction> <StandardVersion>1.0</StandardVersion> <SourceApplication>Protheus-SoapUI</SourceApplication> <Product name="SoapUI" version="12.1.1"/> <GeneratedOn>2016-04-06T16:36:46</GeneratedOn> <DeliveryType>Sync</DeliveryType> </MessageInformation> <BusinessMessage> <BusinessRequest> <Operation>Datasul/btb.btapi930za.getProfile</Operation> </BusinessRequest> <BusinessContent> <btapi930za_getProfile_in> <QP_userCode>adm</QP_userCode> <QP_pageId>integration</QP_pageId> <QP_dataCode>ecm</QP_dataCode> </btapi930za_getProfile_in> </BusinessContent> </BusinessMessage> </TOTVSMessage> |
A mensagem de retorno (ResponseMessage) conterá, na tag <XMLContent>, os dados gerados pela execução do objeto de negócio.
Bloco de código | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8" ?> <TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/totvsmsg.xsd"> <MessageInformation version="1.000"> <UUID>af468991-b5c7-8d82-0d14-1a30dc76389b</UUID> <Type>Response</Type> <Transaction>datasul/btb.btapi930za.getprofile</Transaction> <StandardVersion>1.0</StandardVersion> <SourceApplication>jvd001651</SourceApplication> <CompanyId/> <Product name="Datasul" version="11.5.X"/> <GeneratedOn>2016-04-06T16:36:48.417-03:00</GeneratedOn> </MessageInformation> <ResponseMessage> <ReceivedMessage> <SentBy>Protheus-SoapUI</SentBy> <UUID>btapi930-za00-0001-0000-000000001357</UUID> </ReceivedMessage> <ProcessingInformation> <ProcessedOn>2016-04-06T16:36:48.417-03:00</ProcessedOn> <Status>OK</Status> </ProcessingInformation> <ReturnContent> <XMLContent> <btapi930za_getProfile_out> <ttProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ttProfileRow> <pageId>integration</pageId> <dataCode>ecm</dataCode> <dataValue>7c93b71451fcdd0515fde8883d856d5b</dataValue> </ttProfileRow> </ttProfile> <RowErrors xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> </btapi930za_getProfile_out> </XMLContent> </ReturnContent> </ResponseMessage> </TOTVSMessage> |
Identificação e tratamento das transações de Mensageria TOTVS
Ao receber uma mensagem, o Engine de EAI do Datasul precisa determinar se a transação é do padrão de Mensagem Única TOTVS, ou de Mensageria TOTVS. Isso é feito verificando a forma de registro da transação, conforme descrito na especificação do serviço getSchema.
As mensagens cujos adapters são prefixados com "MT_" serão direcionadas para um programa processador, que é definido no arquivo de configuração do EAI (eai2-config.properties), através da propriedade eai2.mt.processor. Salvo raras exceções, o valor desta propriedade será sempre com.totvs.datasul.eai.mt.DatasulMTProcessor. Sem esta propriedade, o Datasul não poderá processar as mensagens seguindo o padrão da Mensageria TOTVS.
Este programa processador será responsável por extrair da mensagem os dados de entrada, verificar se há necessidade de transformação do modelo de dados, executar o objeto de negócio requisitado e montar a mensagem de retorno com os dados recebidos do objeto de negócio, efetuando a transformação reversa do modelo de dados quando necessário.
Transformação de modelos de dados
A transformação de modelos de dados de outros produtos para o modelo Datasul é determinada pelo valor informado na tag <Transaction> da mensagem recebida. Se o prefixo for diferente do produto de destino, indica que a transformação é necessária. Por exemplo, se o nome da transação for "Protheus/MATA030", o Datasul deverá transformar a BusinessContent recebida para o modelo Datasul antes de repassar os dados para o objeto de negócio.
Informações |
---|
A transformação de modelos de dados se aplica, atualmente, apenas para objetos de negócio do tipo DBO. Objetos de tipo API não fazem a referida conversão. |
No exemplo acima, o objeto de negócio recebido não No exemplo acima, o objeto de negócio recebido não é um objeto válido para o Datasul, o que implica na necessidade de se relacionar os objetos de negócio dos produtos envolvidos na integração. No caso do Datasul, este relacionamento é feito no momento do registro do objeto de negócio, junto aos arquivos de configuração das transações, conforme descrito na especificação do serviço getSchema.
Complementando o referido documento, para registrar um relacionamento entre objetos de negócio, deve-se seguir o seguinte padrão:
MT_<objeto_negocio_externo>#<versão_externa>|<objeto_negócio_interno>#<versão_interna>
Onde,
- MT_ é o prefixo que identifica o registro como sendo da Mensageria TOTVS;
- <objeto_negócio_externo> é o nome do objeto de negócio do outro produto (Protheus, RM, etc). Ex: mata030 ou FinCFODataBR;
- # como separador;
- <versão_externa> é a versão do modelo de dados do objeto de negócio externo;
- | como separador;
- <objeto_negócio_interno> é o nome do objeto de negócio Datasul;
- # como separador;
- <versão_interna> é a versão do modelo de dados Datasul.
A transformação propriamente dita será realizada no objeto de negócio, através de função específica, de nome EAI_transformBusinessContent. Esta função, quando implementada no objeto de negócio, receberá os seguintes parâmetros:
- Nome do modelo de dados de origem (ex.: Datasul, Protheus, etc.).
- Nome do modelo de dados de destino.
- "Handle" do XML relativo ao BusinessContent da mensagem recebida, o qual está no modelo de dados de origem.
Desta forma, o registro de um objeto de negócio Protheus (por exemplo, MATA030), que deva ser processado pelo objeto BOFN017, será feito desta forma no arquivo correspondente.
Bloco de código | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0"?>
<datasul-adapters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
(...)
<datasul-adaptersRow>
<class>MT_mata030#12.1.1|fnbo.bofn017#12.1.3</class>
</datasul-adaptersRow>
(...)
</datasul-adapters> |
A transformação propriamente dita será realizada no objeto de negócio, através de função específica, de nome EAI_transformBusinessContent. Esta função, quando implementada, receberá os seguintes parâmetros:
- Nome do modelo de dados de origem (ex.: Datasul, Protheus, etc.).
- Nome do modelo de dados de destino.
- "Handle" do XML relativo ao BusinessContent da mensagem recebida, o qual está no modelo de dados de origem.
Como parâmetros de saída tem-se o "handle" do XML correspondente ao BusinessContent convertido para o modelo de dados de destino.
O trecho de código abaixo demonstra a estrutura básica da função:
Bloco de código | ||
---|---|---|
| ||
PROCEDURE EAI_transformBusinessContent :
/*:T------------------------------------------------------------------------------
Purpose: Transforma o BusinessContent recebido em um outro formato
Parameters: recebe o produto original (Datasul, Logix, Protheus, RM, etc.)
recebe o produto de destino
recebe o BusinessContent original (documento XML)
retorna o BusinessContent tranformado no modelo do produto de destino (doc XML)
Notes: Esta função é necessária apenas para o modelo Mensageria TOTVS. O modelo
de Mensagem Única não requer esta função, já que a transformação ocorre
nos adapters.
------------------------------------------------------------------------------*/
DEFINE INPUT PARAMETER pSourceProduct AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER pTargetProduct AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER pSourceContent AS HANDLE NO-UNDO.
DEFINE OUTPUT PARAMETER pTargetContent AS HANDLE NO-UNDO.
/* Conversion ID identifica o sentido da conversão do BusinessContent.
Por exemplo, para converter o modelo de dados Datasul no modelo de dados Protheus,
usar o Conversion ID "Datasul->Protheus".
Transformações no sentido contrário exigem um novo Conversion ID, por exemplo,
"Protheus->Datasul" */
DEFINE VARIABLE cConversionID AS CHARACTER NO-UNDO.
cConversionID = pSourceProduct + "->" + pTargetProduct.
LOG-MANAGER:WRITE-MESSAGE( "Iniciando conversão de BusinessContent - " + cConversionID, "EAI2" ).
CASE cConversionID:
WHEN "Protheus->Datasul" OR
WHEN "RM->Datasul" OR
WHEN "Logix->Datasul" OR
WHEN "Datasul->Protheus" THEN DO:
pTargetContent = pSourceContent.
END.
OTHERWISE DO:
LOG-MANAGER:WRITE-MESSAGE( "Conversão não definida : " + cConversionID, "EAI2" ).
pTargetContent = ?.
RETURN "NOK":U.
END.
END CASE.
RETURN "OK":U.
END PROCEDURE. |
A função EAI_transformBusinessContent será chamada em dois momentos: ao receber a mensagem de negócio, convertendo do modelo recebido para o modelo "local". E ao gerar a mensagem de retorno, convertendo do modelo "local" para o modelo recebido. Logo, a implementação da função no objeto de negócio deve prever este cenário de usoComo parâmetros de saída tem-se o "handle" do XML correspondente ao BusinessContent convertido para o modelo de dados de destino.
Informações |
---|
A implementação da função de transformação , conforme afirmado antes, é de responsabilidade do segmento e deve ser baseada no XML Schema dos objetos de negócio do Vertical e do ERP. |
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico |
---|