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
Projeto¹	PDR_LD_FRW001	IRM¹	PCREQ-9836
Requisito¹	PCREQ-10304	Subtarefa¹	PDR_LD_FRW001-229
País	( ) Brasil ( ) Argentina ( ) Mexico ( ) Chile ( ) Paraguai ( ) Equador ( ) USA ( ) Colombia ( x ) TODOS.
Outros	Especificação - PCREQ-9845 - getSchema Especificação - PCREQ-10303 - Whois

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

language	xml
theme	Confluence

<?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

language	xml
theme	Confluence

<?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

language	xml
theme	Confluence

<?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

language	xml
theme	Confluence

<?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 Desta forma, o registro de um 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.

Protheus (por exemplo, MATA030), que deva ser processado pelo objeto BOFN017, será feito desta forma no arquivo correspondente.

Bloco de código

language	xml
theme	Confluence

<?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

language	text

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 é 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

Árvore de páginas

Versões comparadas

Versão antiga 6

Nova versão Atual

Chave

Informações Gerais

Objetivo

Definição da Regra de Negócio

Identificação e tratamento das transações de Mensageria TOTVS

Transformação de modelos de dados