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	Logix	Módulo	Foundation
Segmento Executor	Tecnologia
Projeto	LD_FRW_FRW002	IRM	PCREQ-9903
Requisito		Subtarefa	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 permitindo a execução das mesmas a partir de Web Services. A publicação deverá possibilitar que ferramentas como EAI e o TOTVS HTML Framework possam executar as APIs através de serviços SOAP ou REST, desenvolvidos nos padrões determinados em Desenvolvimento de API - LGX 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

Índice

minLevel	3

1. Introdução

Recentemente foram definidos novos padrões para o desenvolvimento de APIs API na tecnologia 4GL que permitam sua publicação para utilização Logix 4GL, disponível em Desenvolvimento de API - LGX, permitindo sua execução através de Web Services, porém . Porém, para permitir a execução desta API é necessária a uma ferramenta que permita a exportação destas.

Tal ferramenta será responsável por efetuar a leitura do código fonte que possui as funções que serão publicadas e gerar suas estruturas em JSON e XML. Com estas estruturas geradas, a ferramenta deverá criar também duas novas funções ao final do código fonte para retorná-las no formato texto, possibilitando rápida recuperação destas no produto Logix.

2. Nomenclatura das Funções

Para gerar a estrutura e pontos de entrada das APIs, a ferramenta deverá verificar os padrões de nomenclatura de funções - conforme descritos no documento TODO. O nome da função indicará como ficará o nome e o método de chamada através do WebService.

Exemplo:

Bloco de código

title	Fonte logr4.4gl
linenumbers	true

#------------------------------------------------------------------------------#
FUNCTION logr4_pub_create_companies()
#------------------------------------------------------------------------------#
END FUNCTION

Image Removed

Sempre delimitada pelo caractere underscore, o nome da função indica como será a estrutura da função a partir de cada delimitador:

Código da API (logr4)
Identificador de publicação da função (sem o identificador pub, ela não será publicada)
Método de execução da função (create - verificar o item Métodos de Execução)
Nome da função (companies)

2.1. Métodos de Execução

Os métodos de execução definem qual método de requisição HTTP será utilizado para executar a função. Para aproximar o desenvolvimento das APIs ao desenvolvimento do produto Logix, será possível definir um apelido para os métodos de execução, como create, process e update - uma função definida com o nome logr4_pub_create_companies seria igual a uma função com o nome logr4_pub_post_companies por exemplo.

Os métodos de execução disponíveis atualmente são:

POST, CREATE ou PROCESS: para inclusão ou processamento
PUT ou UPDATE: para modificação
DELETE: para exclusão
GET ou QUERY: para recuperar uma ou mais informações

A execução REST da função da imagem acima, após sua publicação, teria uma requisição semelhante a abaixo:

Bloco de código

linenumbers	true

POST /logix-rest/logr4/companies HTTP/1.1
Host: localhost:808

3. Nomenclatura dos Parâmetros

Para gerar os parâmetros de

TODO: documentar nomenclatura dos parametros

TODO: documentar estrutura JSON

TODO: documentar estrutura XML

TODO: documentar funções de retorno da estrutura

TODO: gerar WADL

TODO: gerar WSDL

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 esta estrutura em um arquivo, a API ficará disponível publicamente para execução apenas após a compilação deste arquivo no RPO.

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:

Image Added

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.

Informações

title	Helpers e Adapters

Ambas as funções de Adapters ou Helpers podem ser geradas pelo processo EAI0032 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.

Bloco de código

language	xml
title	GetSchemaIn
linenumbers	true

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

Bloco de código

language	xml
title	GetSchemaOut
linenumbers	true

<?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="cod_empresa" type="xs:string"/>
                                <xs:element name="den_empresa" type="xs:string"/>
                                <xs:element name="den_reduz" type="xs:string"/>
                                <xs:element name="end_empresa" type="xs:string"/>
                                <xs:element name="den_bairro" type="xs:string"/>
                                <xs:element name="den_munic" type="xs:string"/>
                                <xs:element name="uni_feder" type="xs:string"/>
                                <xs:element name="ins_estadual" type="xs:string"/>
                                <xs:element name="num_cgc" type="xs:string"/>
                                <xs:element name="num_caixa_postal" type="xs:string"/>
                                <xs:element name="cod_cep" type="xs:string"/>
                                <xs:element name="num_telefone" type="xs:string"/>
                                <xs:element name="num_telex" type="xs:string"/>
                                <xs:element name="num_fax" type="xs:string"/>
                                <xs:element name="end_telegraf" type="xs:string"/>
                                <xs:element name="num_reg_junta" type="xs:string"/>
                                <xs:element name="dat_inclu_junta" type="xs:date"/>
                                <xs:element name="ies_filial" type="xs:string"/>
                                <xs:element name="dat_fundacao" type="xs:date"/>
                                <xs:element name="cod_cliente" type="xs:string"/>
                            </xs:sequence>
                        </xs:complexType>
                        <xs:complexType name="lr_return">
                            <xs:sequence>
                                <xs:element name="status" type="xs:integer"/>
                                <xs:element name="retmsg" type="xs:string"/>
                            </xs:sequence>
                        </xs:complexType>
                    </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 e exibindo as APIs já publicadas.

Image Added

Veja Também

Protótipo de Tela

Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico.

Páginas filhas

Versões comparadas

Versão antiga 27

Nova versão Atual

Chave

Informações Gerais

Objetivo

Definição da Regra de Negócio

1. Introdução

2. Nomenclatura das Funções

2.1. Métodos de Execução

3. Nomenclatura dos Parâmetros

2. Funcionamento

3. Serviço GetSchema

3.1 Mensagem de Envio

3.2 Mensagem de Reposta

4. Considerações Finais

Protótipo de Tela

Veja Também