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

PDR_LD_FRW001-218

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 e 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, que visa, entre outras coisas, definir os "donos" de uma integração e reduzir o tempo de suporte em situações de inconsistência. Para mais informações sobre a Mensageria TOTVS, acessar este documento.


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 documento de especificação. 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. Para mais informações, acesse este documento.

O adapter, de nome GetSchemaAdapter_1_000, receberá o XML com o nome do objeto de negócio para o qual deve retornar o XSD correspondente aos parâmetros de entrada e saída. A resposta será 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 (veja mais detalhes aqui). Será reaproveitada a definição dos objetos de negócio, os quais estão registrados em arquivos no formato JSON. Estes arquivos serão carregados pelo adapter e interpretados para obter as definiçõ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:

Abaixo está um exemplo do XML que deve ser enviado pelo aplicativo que deseja obter o schema para um determinado objeto de negócio:

 

 

<?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 que estará exercendo o papel de ERP na integração. O formato utilizado aqui se aplica a uma API.

O retorno do serviço será algo como o XML abaixo:

 

 

<?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>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot; ?&gt;&lt;xs:schema xmlns:xs=&quot;http://www.w3.org/2001/XMLSchema&quot; elementFormDefault=&quot;qualified&quot;&gt;&lt;xs:element name=&quot;btapi930za_getProfile_in&quot;&gt;&lt;xs:complexType&gt;&lt;xs:sequence&gt;&lt;xs:element name=&quot;QP_userCode&quot; type=&quot;xs:string&quot;/&gt;&lt;xs:element name=&quot;QP_pageId&quot; type=&quot;xs:string&quot;/&gt;&lt;xs:element name=&quot;QP_dataCode&quot; type=&quot;xs:string&quot;/&gt;&lt;/xs:sequence&gt;&lt;/xs:complexType&gt;&lt;/xs:element&gt;&lt;xs:element name=&quot;btapi930za_getProfile_out&quot;&gt;&lt;xs:complexType&gt;&lt;xs:sequence&gt;&lt;xs:element name=&quot;ttProfile&quot; type=&quot;ttProfile&quot;/&gt;&lt;xs:element name=&quot;RowErrors&quot; type=&quot;RowErrors&quot;/&gt;&lt;/xs:sequence&gt;&lt;/xs:complexType&gt;&lt;/xs:element&gt;&lt;xs:complexType name=&quot;ttProfile&quot;&gt;&lt;xs:sequence&gt;&lt;xs:element name=&quot;ttProfileRow&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;&lt;xs:complexType&gt;&lt;xs:sequence&gt;&lt;xs:element name=&quot;pageId&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;dataCode&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;dataValue&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;/xs:sequence&gt;&lt;/xs:complexType&gt;&lt;/xs:element&gt;&lt;/xs:sequence&gt;&lt;/xs:complexType&gt;&lt;xs:complexType name=&quot;RowErrors&quot;&gt;&lt;xs:sequence&gt;&lt;xs:element name=&quot;RowErrorsRow&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;&lt;xs:complexType&gt;&lt;xs:sequence&gt;&lt;xs:element name=&quot;ErrorSequence&quot; type=&quot;xs:int&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;ErrorNumber&quot; type=&quot;xs:int&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;ErrorDescription&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;ErrorParameters&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;ErrorType&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;ErrorHelp&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;xs:element name=&quot;ErrorSubType&quot; type=&quot;xs:string&quot; minOccurs=&quot;0&quot;/&gt;&lt;/xs:sequence&gt;&lt;/xs:complexType&gt;&lt;/xs:element&gt;&lt;/xs:sequence&gt;&lt;/xs:complexType&gt;&lt;/xs:schema&gt;</Schema>
            </XSD>
        </ReturnContent>
    </ResponseMessage>
</TOTVSMessage>

Conforme mostrado acima, na tag Schema encontra-se o conteúdo do XSD correspondente aos parâmetros de entrada e saída do objeto de negócio.

 

 

Para a geração do XSD, é necessário informar o diretório com os arquivos de definição dos objetos de negócio no arquivo de configuração do EAI (eai2-config.properties), através da propriedade eai2.mt.adapter.definition.dir.

Para efeitos de comparação, segue abaixo o arquivo JSON usado para gerar o XSD do exemplo acima:

 

 

{
    "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
            }
        ]
    }
}

O objeto de negócio também deve estar registrado no EAI para que seja possível obter seu schema. O registro é feito seguindo o mesmo padrão para adapters de mensagem única, com mudança apenas no nome da classe que implementa o adapter. Para saber como se faz o registro de adapters no Datasul, acesse este documento.

Como o objeto de negócio é uma rotina Progress diferente da utilizada para envio e recebimento de transações da mensagem única, o modo de registro deve obedecer os seguintes padrões, para que o Engine do EAI saiba diferenciar um tipo de adapter do outro:

 

  • Nome da classe deve ser precedido do prefixo "MT_" (Mensageria TOTVS);
  • Nome do objeto de negócio deve incluir a pasta onde o mesmo reside;
  • 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;
  • Deve-se informar, junto ao objeto de negócio, a versão do modelo de dados, que corresponde à versão do produto.

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.



Opcional

Protótipo de Tela

 

<Caso necessário inclua protótipos de telas com o objetivo de facilitar o entendimento do requisito, apresentar conceitos e funcionalidades do software>.

 

Protótipo 01

 

 

 

 

 

 

 

 

 

Opcional

Fluxo do Processo

 

<Nesta etapa incluir representações gráficas que descrevam o problema a ser resolvido e o sistema a ser desenvolvido. Exemplo: Diagrama - Caso de Uso, Diagrama de Atividades, Diagrama de Classes, Diagrama de Entidade e Relacionamento e Diagrama de Sequência>. 

Opcional

Dicionário de Dados

 

Arquivo ou Código do Script: AAA – Negociação Financeira / *Versao=CP.2014.12_03*/

  

Índice

Chave

01

<FI9_FILIAL+FI9_IDDARF+FI9_STATUS>

02

<FI9_FILIAL+FI9_FORNEC+ FI9_LOJA+FI9_EMISS+FI9_IDDARF>

03

<FI9_FILIAL+FI9_FORNEC+ FI9_LOJA+FI9_PREFIX+FI9_NUM+FI9_PARCEL+FI9_TIPO>

Campo

<AAA_PERESP>

Tipo

<N>

Tamanho

<6>

Valor Inicial

<Varia de acordo com o tipo informado. Por exemplo, quando o campo “tipo” for date, neste campo pode ser informado uma data>. 

Mandatório

Sim (  ) Não (  )

Descrição

<Referência Mínima para Cálculo>

Título

<Ref.Calc.>

Picture

<@E999.99>

Help de Campo

<Informar o % que o aluno pagará em dinheiro. Esse % poderá ser alterado durante a negociação>

 

(Opcional)

Grupo de Perguntas

 

<Informações utilizadas na linha Protheus>.

 

Nome: FINSRF2

X1_ORDEM

01

X1_PERGUNT

Emissão De

X1_TIPO

D

X1_TAMANHO

8

X1_GSC

G

X1_VAR01

MV_PAR01

X1_DEF01

Comum

X1_CNT01

'01/01/08'

X1_HELP

Data inicial do intervalo de emissões das guias de DARF a serem consideradas na seleção dos dados para o relatório 

 

(Opcional)

Consulta Padrão

<Informações utilizadas na linha Protheus>

 

Consulta: AMB

Descrição

Configurações de Planejamento

Tipo

Consulta Padrão

Tabela

“AMB”

Índice

“Código”

Campo

“Código”; ”Descrição”

Retorno

AMB->AMB_CODIGO

 

(Opcional)

Estrutura de Menu

 

<Informações utilizadas na linha Datasul>.

 

Procedimentos

 

Procedimento

 

 

 

Descrição

(Max 40 posições)

(Max 40 posições)

(Max 40 posições)

Módulo

 

 

 

Programa base

 

 

 

Nome Menu

(Max 32 posições)

(Max 32 posições)

(Max 32 posições)

Interface

GUI/WEB/ChUI/Flex

GUI/WEB/ChUI/Flex

GUI/WEB/ChUI/Flex

Registro padrão

Sim

Sim

Sim

Visualiza Menu

Sim/Não

Sim/Não

Sim/Não

Release de Liberação

 

 

 

 

 

 

Programas

 

Programa

 

 

 

Descrição

(Max 40 posições)

(Max 40 posições)

(Max 40 posições)

Nome Externo

 

 

 

Nome Menu/Programa

(Max 32 posições)

(Max 32 posições)

(Max 32 posições)

Nome Verbalizado[1]

(Max 254 posições)

(Max 254 posições)

(Max 254 posições)

Procedimento

 

 

 

Template

(Verificar lista de opções no man01211)

(Verificar lista de opções no man01211)

(Verificar lista de opções no man01211)

Tipo[2]

Consulta/Manutenção/ Relatório/Tarefas

Consulta/Manutenção/ Relatório/Tarefas

Consulta/Manutenção/ Relatório/Tarefas

Interface

GUI/WEB/ChUI/Flex

GUI/WEB/ChUI/Flex

GUI/WEB/ChUI/Flex

Categoria[3]

 

 

 

Executa via RPC

Sim/Não

Sim/Não

Sim/Não

Registro padrão

Sim

Sim

Sim

Outro Produto

Não

Não

Não

Visualiza Menu

Sim/Não

Sim/Não

Sim/Não

Query on-line

Sim/Não

Sim/Não

Sim/Não

Log Exec.

Sim/Não

Sim/Não

Sim/Não

Rotina (EMS)

 

 

 

Sub-Rotina (EMS)

 

 

 

Localização dentro da Sub Rotina (EMS)

 

 

 

Compact[4]

Sim/Não

Sim/Não

Sim/Não

Home[5]

Sim/Não

Sim/Não

Sim/Não

Posição do Portlet[6]

0 – Top Left

1 – Top Right

2 – Bottom Left

3 – Bottom Right

0 – Top Left

1 – Top Right

2 – Bottom Left

3 – Bottom Right

0 – Top Left

1 – Top Right

2 – Bottom Left

3 – Bottom Right

Informar os papeis com os quais o programa deve ser vinculado

 

 

 

 

Cadastro de Papéis

<O cadastro de papéis é obrigatório para os projetos de desenvolvimento FLEX a partir do Datasul 10>.

<Lembrete: o nome dos papeis em inglês descrito neste ponto do documento, devem ser homologados pela equipe de tradução>.

 

Código Papel

(máx 3 posições)

Descrição em Português*

 

Descrição em Inglês*

 

[1] Nome Verbalizado é obrigatório para desenvolvimentos no Datasul 10 em diante.

[2] Tipo é obrigatório para desenvolvimento no Datasul 10 em diante

[3] Categorias são obrigatórias para os programas FLEX.

[4] Obrigatório quando o projeto for FLEX

[5] Obrigatório quando o projeto for FLEX

[6] Obrigatório quando o projeto for FLEX

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