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 / Framework | ||
Projeto1 | PDR_LD_FRW001 | IRM1 | PCREQ-9836 |
Requisito1 | PCREQ-9845 | Subtarefa1 | |
País | ( ) Brasil ( ) Argentina ( ) Mexico ( ) Chile ( ) Paraguai ( ) Equador ( ) USA ( ) Colombia ( X ) TODOS. | ||
Outros | <Caso necessário informe outras referências que sejam pertinentes a esta especificação. Exemplo: links de outros documentos ou subtarefas relacionadas>. |
Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos).
Objetivo
O serviço getSchema deverá prover a recuperação das estruturas de dados usadas como parâmetros de entrada e saída para os cadastros (DBOs) e serviços (APIs) do Datasul que forem expostos como Web Services.
Este serviço é parte da nova arquitetura de integração EAI, a qual está sendo denominada Mensageria TOTVS, e que visa, entre outras coisas, definir os "donos" de uma integração e reduzir o custo total de suporte em situações de inconsistência.
Definição da Regra de Negócio
Em resumo, o serviço de recuperação de estrutura de dados será implementado utilizando uma transação do tipo Mensagem Única TOTVS, com nome getSchema. Para mais detalhes, consultar este link. Nele é possível verificar o XML Schema (XSD) da transação, entre outras informações.
O fluxo a seguir demonstra como o serviço getSchema será utilizado no contexto das integrações:
No lado do Datasul (que no desenho acima é representado pelo ERP), será implementado um adapter seguindo os padrões de Mensagem Única TOTVS, o qual utilizará a classe helper gerada a partir do XSD da transação GetSchema 1.000.
Classes helper são geradas por um processo automático, que interpreta os XSDs de Mensagem Única e os converte em classes Java ou Progress. Estas classes são compiladas e disponibilizadas em um repositório comum, e são utilizadas por todos que desejam utilizar o padrão de mensagem única para integração via EAI.
O adapter, de nome GetSchemaAdapter_1_000, receberá o XML com o nome do objeto de negócio e a resposta será um XML com o XSD que define os parâmetros de entrada e saída para o objeto de negócio solicitado.
A geração do XSD se dará a partir da infra-estrutura definida pelo serviço Datasul REST. Será reaproveitada a definição dos objetos de negócio, registrada em arquivos no formato JSON. Estes arquivos serão carregados pelo adapter e interpretados para obter as informações necessárias para a geração do XSD, cujo conteúdo será incorporado na mensagem de resposta gerada.
O fluxo a seguir descreve em detalhes os elementos necessários para que a geração do XSD ocorra:
Modelo de mensagem de envio e de retorno
Abaixo está um exemplo do XML que deve ser enviado pelo aplicativo que deseja obter o XML Schema de determinado objeto de negócio. Neste exemplo, o objeto de negócio é uma API (serviço):
<?xml version="1.0" encoding="UTF-8"?> <TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/requests/getSchema_1_000.xsd"> <MessageInformation version="1.000"> <UUID>getSchem-aReq-uest-2000-000000000001</UUID> <Type>BusinessMessage</Type> <Transaction>GetSchema</Transaction> <StandardVersion>1.0</StandardVersion> <SourceApplication>SoapUI</SourceApplication> <Product name="SoapUI" version="5.2.1"/> <GeneratedOn>2016-03-17T13:40:00</GeneratedOn> <DeliveryType>Sync</DeliveryType> </MessageInformation> <BusinessMessage> <BusinessRequest> <Operation>GetSchema</Operation> </BusinessRequest> <BusinessContent> <Adapter>Datasul/btb.btapi930za.getProfile</Adapter> </BusinessContent> </BusinessMessage> </TOTVSMessage>
Observe que na tag <Adapter> o nome do objeto de negócio deve vir precedido do nome do produto (Datasul) sempre que for feita a requisição do schema.
O retorno será semelhante ao XML abaixo, o qual segue o padrão definido para uma mensagem do tipo ResponseMessage.
<?xml version="1.0" encoding="UTF-8" ?> <TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/requests/getSchema_1_000.xsd"> <MessageInformation version="1.000"> <UUID>931a3df6-f194-b0aa-0d14-5e1e64a54078</UUID> <Type>Response</Type> <Transaction>getschema</Transaction> <StandardVersion>1.0</StandardVersion> <SourceApplication>jvd001651</SourceApplication> <CompanyId/> <Product name="Datasul" version="11.5.X"/> <GeneratedOn>2016-04-05T13:31:49.743-03:00</GeneratedOn> </MessageInformation> <ResponseMessage> <ReceivedMessage> <SentBy>SoapUI</SentBy> <UUID>getSchem-aReq-uest-2000-000000000002</UUID> </ReceivedMessage> <ProcessingInformation> <ProcessedOn>2016-04-05T13:31:49.743-03:00</ProcessedOn> <Status>OK</Status> </ProcessingInformation> <ReturnContent> <XSD> <Adapter>Datasul/btb.btapi930za.getProfile</Adapter> <Schema><![CDATA[ <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="btapi930za_getProfile_in"> <xs:complexType> <xs:sequence> <xs:element name="QP_userCode" type="xs:string"/> <xs:element name="QP_pageId" type="xs:string"/> <xs:element name="QP_dataCode" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="btapi930za_getProfile_out"> <xs:complexType> <xs:sequence> <xs:element name="ttProfile" type="ttProfile"/> <xs:element name="RowErrors" type="RowErrors"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="ttProfile"> <xs:sequence> <xs:element name="ttProfileRow" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="pageId" type="xs:string" minOccurs="0"/> <xs:element name="dataCode" type="xs:string" minOccurs="0"/> <xs:element name="dataValue" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> <xs:complexType name="RowErrors"> <xs:sequence> <xs:element name="RowErrorsRow" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="ErrorSequence" type="xs:int" minOccurs="0"/> <xs:element name="ErrorNumber" type="xs:int" minOccurs="0"/> <xs:element name="ErrorDescription" type="xs:string" minOccurs="0"/> <xs:element name="ErrorParameters" type="xs:string" minOccurs="0"/> <xs:element name="ErrorType" type="xs:string" minOccurs="0"/> <xs:element name="ErrorHelp" type="xs:string" minOccurs="0"/> <xs:element name="ErrorSubType" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:schema>]]> </Schema> </XSD> </ReturnContent> </ResponseMessage> </TOTVSMessage>
Dentro da tag <ReturnContent> encontramos a tag <XSD>, e logo abaixo, após a tag <Adapter>, temos a tag <Schema>, na qual se encontra o conteúdo do XSD correspondente aos parâmetros de entrada e saída do objeto de negócio.
O XSD gerado terá dois grupos de parâmetros, sendo um para os de entrada (com sufixo "_in") e outro para os de saída (com sufixo "_out"). No exemplo acima, estes grupos são representados pelos elementos de nome "btapi930za_getProfile_in" e "btapi930_getProfile_out", respectivamente.
Quando se requisita o modelo de dados de um objeto de negócio do tipo DBO, o retorno é um pouco diferente, conforme exemplo abaixo. Por simplificação, aqui é mostrado apenas o conteúdo que seria retornado na tag <Schema>.
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="RowObjectbofn017" > <xs:complexType> <xs:sequence> <xs:element name="RowObjectbofn017Row" minOccurs="1" maxOccurs="unbounded" > <xs:complexType> <xs:sequence> <xs:element name="cod_usuario" type="xs:string" minOccurs="0"/> <xs:element name="nom_usuario" type="xs:string" minOccurs="0"/> <xs:element name="cod_senha" type="xs:string" minOccurs="0"/> <xs:element name="cod_idiom_orig" type="xs:string" minOccurs="0"/> <xs:element name="ind_tip_usuar" type="xs:string" minOccurs="0"/> <xs:element name="num_pessoa" type="xs:int" minOccurs="0"/> <xs:element name="nom_dir_spool" type="xs:string" minOccurs="0"/> <xs:element name="nom_subdir_spool" type="xs:string" minOccurs="0"/> <xs:element name="cod_servid_exec" type="xs:string" minOccurs="0"/> <xs:element name="cod_e_mail_local" type="xs:string" minOccurs="0"/> <xs:element name="dat_ult_erro_tentat_aces" type="xs:date" minOccurs="0"/> <xs:element name="hra_ult_erro_tentat_aces" type="xs:string" minOccurs="0"/> <xs:element name="qtd_erro_tentat_aces" type="xs:decimal" minOccurs="0"/> <xs:element name="log_servid_exec_obrig" type="xs:boolean" minOccurs="0"/> <xs:element name="dat_inic_valid" type="xs:date" minOccurs="0"/> <xs:element name="dat_fim_valid" type="xs:date" minOccurs="0"/> <xs:element name="dat_valid_senha" type="xs:date" minOccurs="0"/> <xs:element name="num_dias_valid_senha" type="xs:int" minOccurs="0"/> <xs:element name="log_segur_uhr_atlzdo" type="xs:boolean" minOccurs="0"/> <xs:element name="cod_livre_1" type="xs:string" minOccurs="0"/> <xs:element name="cod_livre_2" type="xs:string" minOccurs="0"/> <xs:element name="val_livre_1" type="xs:decimal" minOccurs="0"/> <xs:element name="val_livre_2" type="xs:decimal" minOccurs="0"/> <xs:element name="num_livre_1" type="xs:int" minOccurs="0"/> <xs:element name="num_livre_2" type="xs:int" minOccurs="0"/> <xs:element name="log_livre_1" type="xs:boolean" minOccurs="0"/> <xs:element name="log_livre_2" type="xs:boolean" minOccurs="0"/> <xs:element name="dat_livre_1" type="xs:date" minOccurs="0"/> <xs:element name="dat_livre_2" type="xs:date" minOccurs="0"/> <xs:element name="des_checksum" type="xs:string" minOccurs="0"/> <xs:element name="num_perf_usuar" type="xs:int" minOccurs="0"/> <xs:element name="des_cod_perf_usuar" type="xs:string" minOccurs="0"/> <xs:element name="log_mostra_framework" type="xs:boolean" minOccurs="0"/> <xs:element name="nom_subdir_spool_rpw" type="xs:string" minOccurs="0"/> <xs:element name="cod_dialet" type="xs:string" minOccurs="0"/> <xs:element name="log_usuar_wap" type="xs:boolean" minOccurs="0"/> <xs:element name="cod_e_mail_celular" type="xs:string" minOccurs="0"/> <xs:element name="log_usuar_atlzdo_ged" type="xs:boolean" minOccurs="0"/> <xs:element name="log_ativ_multi_idiom" type="xs:boolean" minOccurs="0"/> <xs:element name="idi_tip_login" type="xs:int" minOccurs="0"/> <xs:element name="idi_dtsul" type="xs:int" minOccurs="0"/> <xs:element name="idi_dtsul_instan" type="xs:int" minOccurs="0"/> <xs:element name="cod_senha_framework" type="xs:string" minOccurs="0"/> <xs:element name="log_trace" type="xs:boolean" minOccurs="0"/> <xs:element name="num_dia_cont_modul_dtsul" type="xs:int" minOccurs="0"/> <xs:element name="ind_tip_aces_usuar" type="xs:string" minOccurs="0"/> <xs:element name="log_full_determ" type="xs:boolean" minOccurs="0"/> <xs:element name="log_solic_impres" type="xs:boolean" minOccurs="0"/> <xs:element name="des_login_inform" type="xs:string" minOccurs="0"/> <xs:element name="r-Rowid" type="xs:base64Binary" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Os parâmetros são mantidos em um agrupador único (elemento "RowObjectbofn017", no exemplo acima) que é usado tanto para entrada quanto para saída. O modelo acima se aproxima da estrutura de dados correspondente a uma tabela.
Definição dos objetos de negócio
Para a geração do XSD, é necessário indicar no arquivo de configuração do EAI (eai2-config.properties) o local dos arquivos de definição dos objetos de negócio. Isso é feito através da propriedade eai2.mt.adapter.definition.dir.
eai2.config.provider=com.totvs.datasul.eai.db.DBConfigurationProvider eai2.app.name=jvd001651-dts12.1.11 eai2.mt.processor=com.totvs.datasul.eai.mt.DatasulMTProcessor eai2.mt.adapter.definition.dir=C:/TOTVS/Datasul11/11.5.X/jboss-4.2.3.GA/server/progress-8280/datasul-rest # define o diretório dos arquivos JSON
No arquivo de definição de uma API, será considerada, dentro da propriedade "methods", a propriedade correspondente ao método referenciado na tag <Adapter> da mensagem recebida. Encontrada a definição do método, será utilizada a propriedade "parameters" para gerar o XSD com os parâmetros de entrada (indicados pela propriedade "type" = 1) e de saída ("type" = 2). Podem existir parâmetros com propriedade "type" = 3, significando que é tanto de entrada como de saída.
{ "programName" : "btb/btapi930za.r", "serviceName" : "btb/btapi930za", "type" : "api", "methods" : { "getProfileGET" : { "procedureName" : "REST_GET_getProfile", "httpMethod" : "GET", "path" : "getProfile", "parameters" : [{ "name" : "QP_userCode", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "QP_pageId", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "QP_dataCode", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "ttProfile", "type" : 2, "datatype" : 15, "origin" : "representation", "extent" : -1 }, { "name" : "RowErrors", "type" : 2, "datatype" : 15, "origin" : "representation", "extent" : -1 } ] }, "removeProfilePOST" : { "procedureName" : "REST_POST_removeProfile", "httpMethod" : "POST", "path" : "removeProfile", "parameters" : [{ "name" : "QP_userCode", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "QP_pageId", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "QP_dataCode", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "RowErrors", "type" : 2, "datatype" : 15, "origin" : "representation", "extent" : -1 } ] }, "setProfilePOST" : { "procedureName" : "REST_POST_setProfile", "httpMethod" : "POST", "path" : "setProfile", "parameters" : [{ "name" : "QP_userCode", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "QP_pageId", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 }, { "name" : "ttProfile", "type" : 1, "datatype" : 15, "origin" : "representation", "extent" : -1 }, { "name" : "RowErrors", "type" : 2, "datatype" : 15, "origin" : "representation", "extent" : -1 } ] } }, "datasets" : {}, "tables" : { "RowErrors" : [{ "name" : "ErrorSequence", "datatype" : 4, "extent" : -1 }, { "name" : "ErrorNumber", "datatype" : 4, "extent" : -1 }, { "name" : "ErrorDescription", "datatype" : 1, "extent" : -1 }, { "name" : "ErrorParameters", "datatype" : 1, "extent" : -1 }, { "name" : "ErrorType", "datatype" : 1, "extent" : -1 }, { "name" : "ErrorHelp", "datatype" : 1, "extent" : -1 }, { "name" : "ErrorSubType", "datatype" : 1, "extent" : -1 } ], "ttProfile" : [{ "name" : "pageId", "datatype" : 1, "extent" : -1 }, { "name" : "dataCode", "datatype" : 1, "extent" : -1 }, { "name" : "dataValue", "datatype" : 1, "extent" : -1 } ] } }
Para um objeto de negócio do tipo DBO (cadastro), será utilizada a propriedade "fieldsarray" para determinar os campos do modelo de dados.
{ "programName" : "fnbo/bofn017.r", "dboName" : "fnbo/bofn017", "type" : "dbo", "tableName" : "RowObject", "getRowObjectExtraMethod" : false, "keyparameters" : [{ "name" : "pcod_usuario", "type" : 1, "datatype" : 1, "origin" : "query", "extent" : -1 } ], "fieldsarray" : [{ "name" : "cod_usuario", "datatype" : 1, "extent" : -1 }, { "name" : "nom_usuario", "datatype" : 1, "extent" : -1 }, { "name" : "cod_senha", "datatype" : 1, "extent" : -1 }, { "name" : "cod_idiom_orig", "datatype" : 1, "extent" : -1 }, { "name" : "ind_tip_usuar", "datatype" : 1, "extent" : -1 }, { "name" : "num_pessoa", "datatype" : 4, "extent" : -1 }, { "name" : "nom_dir_spool", "datatype" : 1, "extent" : -1 }, { "name" : "nom_subdir_spool", "datatype" : 1, "extent" : -1 }, { "name" : "cod_servid_exec", "datatype" : 1, "extent" : -1 }, { "name" : "cod_e_mail_local", "datatype" : 1, "extent" : -1 }, { "name" : "dat_ult_erro_tentat_aces", "datatype" : 2, "extent" : -1 }, { "name" : "hra_ult_erro_tentat_aces", "datatype" : 1, "extent" : -1 }, { "name" : "qtd_erro_tentat_aces", "datatype" : 5, "extent" : -1 }, { "name" : "log_servid_exec_obrig", "datatype" : 3, "extent" : -1 }, { "name" : "dat_inic_valid", "datatype" : 2, "extent" : -1 }, { "name" : "dat_fim_valid", "datatype" : 2, "extent" : -1 }, { "name" : "dat_valid_senha", "datatype" : 2, "extent" : -1 }, { "name" : "num_dias_valid_senha", "datatype" : 4, "extent" : -1 }, { "name" : "log_segur_uhr_atlzdo", "datatype" : 3, "extent" : -1 }, { "name" : "cod_livre_1", "datatype" : 1, "extent" : -1 }, { "name" : "cod_livre_2", "datatype" : 1, "extent" : -1 }, { "name" : "val_livre_1", "datatype" : 5, "extent" : -1 }, { "name" : "val_livre_2", "datatype" : 5, "extent" : -1 }, { "name" : "num_livre_1", "datatype" : 4, "extent" : -1 }, { "name" : "num_livre_2", "datatype" : 4, "extent" : -1 }, { "name" : "log_livre_1", "datatype" : 3, "extent" : -1 }, { "name" : "log_livre_2", "datatype" : 3, "extent" : -1 }, { "name" : "dat_livre_1", "datatype" : 2, "extent" : -1 }, { "name" : "dat_livre_2", "datatype" : 2, "extent" : -1 }, { "name" : "des_checksum", "datatype" : 1, "extent" : -1 }, { "name" : "num_perf_usuar", "datatype" : 4, "extent" : -1 }, { "name" : "des_cod_perf_usuar", "datatype" : 1, "extent" : -1 }, { "name" : "log_mostra_framework", "datatype" : 3, "extent" : -1 }, { "name" : "nom_subdir_spool_rpw", "datatype" : 1, "extent" : -1 }, { "name" : "cod_dialet", "datatype" : 1, "extent" : -1 }, { "name" : "log_usuar_wap", "datatype" : 3, "extent" : -1 }, { "name" : "cod_e_mail_celular", "datatype" : 1, "extent" : -1 }, { "name" : "log_usuar_atlzdo_ged", "datatype" : 3, "extent" : -1 }, { "name" : "log_ativ_multi_idiom", "datatype" : 3, "extent" : -1 }, { "name" : "idi_tip_login", "datatype" : 4, "extent" : -1 }, { "name" : "idi_dtsul", "datatype" : 4, "extent" : -1 }, { "name" : "idi_dtsul_instan", "datatype" : 4, "extent" : -1 }, { "name" : "cod_senha_framework", "datatype" : 1, "extent" : -1 }, { "name" : "log_trace", "datatype" : 3, "extent" : -1 }, { "name" : "num_dia_cont_modul_dtsul", "datatype" : 4, "extent" : -1 }, { "name" : "ind_tip_aces_usuar", "datatype" : 1, "extent" : -1 }, { "name" : "log_full_determ", "datatype" : 3, "extent" : -1 }, { "name" : "log_solic_impres", "datatype" : 3, "extent" : -1 }, { "name" : "des_login_inform", "datatype" : 1, "extent" : -1 }, { "name" : "r-Rowid", "datatype" : 13, "extent" : -1 } ], "gotomethods" : { "gotokeyid" : [{ "name" : "pidi_dtsul", "type" : 1, "datatype" : 4, "origin" : "query", "extent" : -1 } ] }, "extraFieldsarray" : [] }
Registro dos objetos de negócio
O objeto de negócio também deve estar registrado no EAI para que seja possível obter seu schema. O registro é feito nos mesmos arquivos de configuração utilizados para adapters de mensagem única, com mudança apenas no nome da classe que implementa o adapter (tag <class>). Para saber como se faz o registro de adapters no Datasul, acesse este documento.
O registro deve obedecer os seguintes padrões, para que o Engine do EAI consiga diferenciar um objeto de negócio de um adapter de mensagem única:
- Formato geral: "MT_<objeto_negocio>#<versão_produto>"
Onde,
- O prefixo "MT_" identifica que é um objeto de negócio sendo usado pela Mensageria TOTVS;
- O nome do objeto de negócio deve incluir a pasta onde o mesmo reside, usando "." como separador;
- Se o objeto for uma API, deve constar também o nome do método que se deseja publicar, não apenas o nome do objeto, usando o separador ".";
- Deve-se informar, junto ao objeto de negócio, a versão do modelo de dados, que corresponde à versão do produto. Usar separador "#".
Exemplificando as regras acima consideremos o registro de dois objetos de negócio: BOFN017 (cadastro de usuários) e BTAPI930ZA, método getProfile (API para obter propriedades associadas a um usuário).
- Registro do BOFN017, do tipo DBO (cadastro), considerando que esteja na pasta "fnbo", no Datasul versão 12.1.3: MT_fnbo.bofn017#12.1.3.
- Registro do BTAPI930ZA, método getProfile, de tipo API (serviço), considerando que esteja na pasta "btb", no Datasul versão 12.1.9: MT_btb.btbapi930za.getProfile#12.1.9.
O exemplo abaixo mostra como seria o registro destes no arquivo adapters/tec-adapters.xml.
<?xml version="1.0"?> <datasul-adapters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <datasul-adaptersRow> <class>MT_fnbo.bofn017#12.1.3</class> </datasul-adaptersRow> <datasul-adaptersRow> <class>MT_btb.btapi930za.getProfile#12.1.9</class> </datasul-adaptersRow> </datasul-adapters>
Considerações finais
A transação getSchema, assim como a transação Whois, deve ser considerada padrão do EAI e, por isso, não necessita ser habilitada e deve ser aceita por outros EAI de forma anônima, ou seja, sem que o aplicativo de origem esteja cadastrado no destino.
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|