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 | Logix | Módulo | Foundation |
Segmento Executor | Tecnologia | ||
Projeto | LD_FRW_FRW002 | IRM | PCREQ-9903 |
Requisito | PCREQ-9904 | Sub tarefa | PDR_LD_FRW001-241 |
País | (X) Brasil ( ) Argentina ( ) Mexico ( ) Chile ( ) Paraguai ( ) Equador ( ) USA ( ) Colombia ( ) Outro ______________. | ||
Objetivo
Desenvolver uma ferramenta que efetue a exportação e publicação das estruturas das APIs Logix, desenvolvidos nos padrões determinados em LGX - Desenvolvimento de APIs e o novo serviço, denominado GetSchema, que provê a consulta às estruturas publicadas retornando-as no formato de XML Schema (XSD).
Definição da Regra de Negócio
| Rotina | Tipo de Operação | Opção de Menu |
|---|---|---|
LOG00070 - Publicação de APIs | Criação | Administração Logix > Controle Geral > Desenvolvimento |
1. Introdução
Recentemente foram definidos novos padrões para o desenvolvimento de API na tecnologia Logix 4GL, disponível em LGX - Desenvolvimento de APIs, permitindo sua execução através de Web Services. Porém, para permitir a execução desta API é necessária uma ferramenta que efetue a exportação e publicação de sua estrutura de dados para que os serviços externos (como o TOTVS HTML Framework e EAI) saibam quais parâmetros de entrada e de saída deverão ser informados para a execução da mesma.
2. Funcionamento
A ferramenta de publicação será responsável por ler o conteúdo do código fonte da API e gerar a estrutura de todos os métodos públicos encontrados e seus respectivos parâmetros de entrada e saída. Após gerada a estrutura no formato JSON, a ferramenta deve disponibilizar um meio do desenvolvedor copiá-la para o código fonte informado, a API ficará disponível publicamente para execução apenas após a compilação do código fonte no RPO com a estrutura copiada.
3. Serviço GetSchema
O serviço GetSchema será responsável por retornar a estrutura das APIs públicas, este fará parte da nova arquitetura de integração EAI, a qual está sendo denominada Mensageria TOTVS e que visa, entre outras coisas, definir os responsáveis de uma integração e reduzir o custo total de suporte em situações de inconsistências. O GetSchema será desenvolvido utilizando uma transação do tipo Mensagem Única TOTVS utilizando o a estrutura do XSD disponível neste link.
O fluxo abaixo demonstra como o serviço GetSchema será utilizado no contexto das integrações:
No lado Logix, que no fluxo acima é representado como ERP, será desenvolvido 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 versão 1.000. O adapter, de nome EAIAdapterGetSchema, receberá o XML com o nome do objeto de negócio e a resposta será um XML com o XSD da estrutura contendo os parâmetros de entrada e saída do objeto solicitado.
As funções Helpers são geradas por um processo automático que interpreta o XSD de uma determinada mensagem e os converte em funções 4GL. Estas funções 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. |
A geração do XSD se dará a partir da conversão da execução da função responsável por retornar a estrutura em JSON gerada através da ferramenta de publicação de API (item 2.Funcionamento deste documento).
3.1 Mensagem de Envio
Segue abaixo um exemplo do XML que deverá ser enviado pelo aplicativo que deseja obter o XSD de determinado objeto de negócio, seguindo o padrão definido para uma mensagem do tipo BusinessMessage.
<?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>a8eef627-a4f7-47ad-97dc-706ab15b995d</UUID>
<Type>BusinessMessage</Type>
<Transaction>GetSchema</Transaction>
<StandardVersion>1.000</StandardVersion>
<SourceApplication>SoapUI</SourceApplication>
<Product name="SoapUI" version="5.2.1"/>
<GeneratedOn>2016-01-01T00:00:00.000-00:00</GeneratedOn>
<DeliveryType>sync</DeliveryType>
</MessageInformation>
<BusinessMessage>
<BusinessRequest>
<Operation>GetSchema</Operation>
</BusinessRequest>
<BusinessContent>
<Adapter>Logix/logr2.logr2_pub_create_companies</Adapter>
</BusinessContent>
</BusinessMessage>
</TOTVSMessage> |
Observe na mensagem acima que no elemento <Adapter> o nome do objeto de negócio deve vir precedido do nome do produto (Logix) e do nome da API (logr2) sempre que for realizada a requisição do XSD.
3.2 Mensagem de Reposta
Segue abaixo um exemplo do XML de retorno, o qual segue o padrão definido para uma mensagem do tipo ResponseMessage.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TOTVSMessage>
<MessageInformation version="1.000">
<UUID>66567771-f4b2-77f7-94f6-9dd1c22c3dbf</UUID>
<Type>Response</Type>
<Transaction>GetSchema</Transaction>
<StandardVersion>1.000</StandardVersion>
<SourceApplication>SoapUI</SourceApplication>
<BranchId/>
<Product name="SoapUI" version="5.1.2"/>
<GeneratedOn>2016-00-00T00:00:00</GeneratedOn>
<DeliveryType>sync</DeliveryType>
</MessageInformation>
<ResponseMessage>
<ReceivedMessage>
<SentBy>SoapUI</SentBy>
<UUID>a8eef627-a4f7-47ad-97dc-706ab15b995d</UUID>
<MessageContent>
<![CDATA[<?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>a8eef627-a4f7-47ad-97dc-706ab15b995d</UUID>
<Type>BusinessMessage</Type>
<Transaction>GetSchema</Transaction>
<StandardVersion>1.000</StandardVersion>
<SourceApplication>SoapUI</SourceApplication>
<Product name="SoapUI" version="5.1.2"/>
<GeneratedOn>2016-00-00T00:00:00</GeneratedOn>
<DeliveryType>sync</DeliveryType>
</MessageInformation>
<BusinessMessage>
<BusinessRequest>
<Operation>GetSchema</Operation>
</BusinessRequest>
<BusinessContent>
<Adapter>Logix/logr2.logr2_pub_create_companies</Adapter>
</BusinessContent>
</BusinessMessage>
</TOTVSMessage>]]>
</MessageContent>
</ReceivedMessage>
<ProcessingInformation>
<ProcessedOn>2016-00-00T00:00:00</ProcessedOn>
<Status>ok</Status>
</ProcessingInformation>
<ReturnContent>
<XSD>
<Adapter>logr2_pub_create_companies</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="logr2_pub_create_companies">
<xs:complexType>
<xs:choice>
<xs:element name="input" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="lr_empresa" type="lr_empresa" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="output" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="lr_return" type="lr_return"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
<xs:attribute name="api" type="xs:string" fixed="logr2"/>
</xs:complexType>
</xs:element>
<xs:complexType name="lr_empresa">
<xs:sequence>
<xs:element name="lr_empresa.cod_empresa" type="xs:string"/>
<xs:element name="lr_empresa.den_empresa" type="xs:string"/>
<xs:element name="lr_empresa.den_reduz" type="xs:string"/>
<xs:element name="lr_empresa.end_empresa" type="xs:string"/>
<xs:element name="lr_empresa.den_bairro" type="xs:string"/>
<xs:element name="lr_empresa.den_munic" type="xs:string"/>
<xs:element name="lr_empresa.uni_feder" type="xs:string"/>
<xs:element name="lr_empresa.ins_estadual" type="xs:string"/>
<xs:element name="lr_empresa.num_cgc" type="xs:string"/>
<xs:element name="lr_empresa.num_caixa_postal" type="xs:string"/>
<xs:element name="lr_empresa.cod_cep" type="xs:string"/>
<xs:element name="lr_empresa.num_telefone" type="xs:string"/>
<xs:element name="lr_empresa.num_telex" type="xs:string"/>
<xs:element name="lr_empresa.num_fax" type="xs:string"/>
<xs:element name="lr_empresa.end_telegraf" type="xs:string"/>
<xs:element name="lr_empresa.num_reg_junta" type="xs:string"/>
<xs:element name="lr_empresa.dat_inclu_junta" type="xs:date"/>
<xs:element name="lr_empresa.ies_filial" type="xs:string"/>
<xs:element name="lr_empresa.dat_fundacao" type="xs:date"/>
<xs:element name="lr_empresa.cod_cliente" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="lr_return">
<xs:sequence>
<xs:element name="lr_return.status" type="xs:integer"/>
<xs:element name="lr_return.retmsm" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="lr_empresa.cod_empresa">
<xs:restriction base="xs:string">
<xs:maxLength value="2"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.den_empresa">
<xs:restriction base="xs:string">
<xs:maxLength value="36"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.den_reduz">
<xs:restriction base="xs:string">
<xs:maxLength value="10"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.end_empresa">
<xs:restriction base="xs:string">
<xs:maxLength value="36"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.den_bairro">
<xs:restriction base="xs:string">
<xs:maxLength value="19"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.den_munic">
<xs:restriction base="xs:string">
<xs:maxLength value="30"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.uni_feder">
<xs:restriction base="xs:string">
<xs:maxLength value="2"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.ins_estadual">
<xs:restriction base="xs:string">
<xs:maxLength value="16"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.num_cgc">
<xs:restriction base="xs:string">
<xs:maxLength value="19"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.num_caixa_postal">
<xs:restriction base="xs:string">
<xs:maxLength value="5"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.cod_cep">
<xs:restriction base="xs:string">
<xs:maxLength value="9"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.num_telefone">
<xs:restriction base="xs:string">
<xs:maxLength value="15"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.num_telex">
<xs:restriction base="xs:string">
<xs:maxLength value="15"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.num_fax">
<xs:restriction base="xs:string">
<xs:maxLength value="15"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.end_telegraf">
<xs:restriction base="xs:string">
<xs:maxLength value="36"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.num_reg_junta">
<xs:restriction base="xs:string">
<xs:maxLength value="15"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.ies_filial">
<xs:restriction base="xs:string">
<xs:maxLength value="1"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_empresa.cod_cliente">
<xs:restriction base="xs:string">
<xs:maxLength value="15"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_return.status">
<xs:restriction base="xs:integer">
<xs:maxInclusive value="2147483647"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="lr_return.retmsm">
<xs:restriction base="xs:string">
<xs:maxLength value="100"/>
</xs:restriction>
</xs:simpleType>]]>
</xs:schema>
</Schema>
</XSD>
</ReturnContent>
</ResponseMessage>
</TOTVSMessage> |
No elemento <ReturnContent> encontra-se o elemento <XSD> e logo abaixo encontram-se os elementos <Adapter> e <Schema>, no qual se encontra o conteúdo do XSD correspondente com a estrutura do objeto de negócio e seus respectivos parâmetros de entrada e saída. O XSD gerado terá dois grupos de parâmetros, sendo um para os de entrada (representado pelo elemento <input>) e outro para os de saída (representado pelo elemento <output>).
4. Considerações Finais
A transação GetSchema, assim como a transação WhoIs, deve ser considerada padrão do EAI e, portanto, 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.
Protótipo de Tela
Imagem 1: tela para informação do código fonte da API.
Imagem 2: estrutura gerada e exibida em tela para cópia.
Imagem 3: lista das APIs já publicadas anteriormente pela ferramenta.
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
|---|