Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|
Índice |
---|
Especificação | |||
Produto | TOTVS | Módulo | EAI |
Segmento Executor | Framework | ||
Projeto1 | DEAI1 | IRM/EPIC1 | |
Requisito/Story/Issue1 | DEAI1-1160 | Subtarefa1 | DEAI1-1608 |
Chamado/Ticket2 | |||
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).
Elaborar a especificação que orientará a implementação do Identificador Global de Recursos nas respectivas linhas de produto com EAI.
Informações | ||
---|---|---|
| ||
Este documento leva em consideração que o leitor tenha um conhecimento prévio da mensagem padronizada TOTVS. Caso algum termo não esteja suficientemente descrito aqui, recomenda-se consultar o documento Padrão para criação de mensagem padronizada, disponível no portal de Integrações TOTVS. |
Estamos propondo a criação de um Identificador Global de Recursos para as entidades trafegadas entre os ERP's da TOTVS afim de substituir o uso de "Internal ID" em todas as integrações SOAP e REST.
As marcas deverão atender os seguintes pré-requisitos:
Os termos "DEVE", "NÃO DEVE", "REQUERIDO", "PODE", "NÃO PODE", "DEVERIA", "NÃO DEVERIA", "RECOMENDADO", "NÃO RECOMENDADO" e "OPCIONAL" devem ser interpretados como descritos na BCP-14, RFC-2119 e RFC-8174.
Informações | ||
---|---|---|
| ||
Recursos podem ser compreendidos como as Entidades que são trafegadas através das mensagens padronizadas a partir do EAI dos ERP's da TOTVS. |
Em termos gerais, o ERP de onde se origina a entidade a ser trafegada através do EAI (RM, Datasul, Protheus, Logix) irá realizar a geração do UUID v4, que identificará este recurso através de todas as linhas de produtos que compartilhem esta integração.
Iremos adotar o padrão de compatibilidade total com as mensagens atualmente em uso, sendo assim, mesmo que uma mensagem não utilize a estrutura proposta, os EAIs irão processar estas mensagens através do funcionamento legado utilizando o de-para na entidade "InternalId" para identificar o recurso.
Nossa proposta inicial é de se utilizar UUID's (Universally Unique Identifier), também conhecidos por GUID's (Globally Unique IDentifier), como URN (Uniform Resource Name) de entidades sendo trafegadas entre os ERP's da TOTVS.
Informações | ||
---|---|---|
| ||
Um UUID é composto por 128 bits de informação e não requer um processo de geração centralizado. |
Uma das principais razões pela escolha do UUID é que, além de sua geração poder ser descentralizada e automatizada, o algoritmo de geração do UUID suporta geração concorrente de até 10 milhões de registros por segundo por máquina, permitindo seu uso até como identificador de transações.
Informações | title | Para sua informação
---|
Exemplo de uma representação em texto de um UUID como URN: urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 |
Foi escolhida a versão 4 (UUID v4) por se tratar de um algoritmo que utiliza geração de valores randômicos e que não se baseia no MAC Address da máquina que realiza a geração do identificador (UUID v1).
Elaboramos duas propostas de implementação para o Identificador Global de Recursos
Todas as linhas irão adequar seus adapters para enviar o Identificador Global de Recursos através da entidade "InternalId" no conteúdo de uma mensagem padronizada.
Todas as linhas irão adequar seus adapters para enviar o Identificador Global de Recursos através da entidade "GlobalId" no conteúdo de uma mensagem padronizada.
A especificação atual das mensagens será alterada para discriminar o tipo de identificador de recursos sendo utilizado na mensagem disparada.
Iremos incluir um atributo "GlobalIdType" no elemento "MessageInformation"
Bloco de código | ||
---|---|---|
| ||
<xs:attribute name="GlobalIdType" use="optional"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="UUID"></xs:enumeration> <xs:enumeration value="INTERNALID"></xs:enumeration> <xs:enumeration value="internalid"></xs:enumeration> <xs:enumeration value="uuid"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:attribute> |
Bloco de código | ||
---|---|---|
| ||
<xs:element name="MessageInformation" type="MessageInformationType" /> |
Bloco de código | ||
---|---|---|
| ||
<xs:complexType name="MessageInformationType"> <xs:annotation> <xs:documentation> Bloco com informações sobre a origem da mensagem. </xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="UUID" type="UUIDType" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Define um identificador universal para esta mensagem. Duas mensagens não podem ter o mesmo UUID e este valor permanece sempre o mesmo, seja no aplicativo que gera a mensagem, seja no que recebe. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="Type" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Identifica o tipo de mensagem: a. Business Message: Mensagem “real”, sobre um evento ocorrido (quando for de saída) ou de atualização do produto (quando entrada). Pode ser de dois subtipos (ver atributos da tag BusinessMessage): i. Transaction: Mensagem utilizada para fins de replicação de dados que contém um evento ocorrido no sistema (upsert ou delete). Se recebido, resulta na execução da operação sobre na base de dados. Se Enviado, significa que o sistema de origem está notificando esta operação. Transactions refletem a atividade de uma aplicação (CrUD) tendem a ser utilizadas de forma assíncrona. ii. Request: Mensagem utilizada para solicitar a execução de um procedimento. Este procedimento pode ser uma consulta (getOrders, countCustomers), cálculo (calculateTaxes) ou atualização do banco de dados (updateAverageCost). Requests promovem o compartilhamento de serviços e tendem a ser utilizados de forma síncrona. b. Receipt: Quando a mensagem for recebida de forma assíncrona, o produto devolve um recibo com status de recebimento e com o UUID de rastreabilidade da mensagem dentro do produto que recebeu c. Response: Mensagem retornada pelo processamento da Business Message. Pode trazer apenas o status (OK ou não), a lista de erros (se houver) ou informações relevantes (como número de pedido gerado, por exemplo). Pode ser devolvida na chamada de uma business message (quando síncrono) ou enviada de forma assíncrona. </xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="BusinessMessage"></xs:enumeration> <xs:enumeration value="Response"></xs:enumeration> <xs:enumeration value="Receipt"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Transaction" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Identifica o nome da transação que esta mensagem contém. Exemplo: Branch. </xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:whiteSpace value="collapse"></xs:whiteSpace> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="ContextName" type="xs:string" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation> Campo opcional que identifica o(s) contexto(s) associado(s) a transação. O contexto pode ser o módulo que gerou a mensagem, pode identificar a integração entre aplicativos, enfim, pode ser qualquer informação que permita delimitar a mensagem, de modo a orientar o roteamento da mensagem ou o recebimento. Exemplos: Financeiro, Datasul CRM, Manufatura, APS-Logix, etc. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="StandardVersion" minOccurs="1" maxOccurs="1"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="\d+.\d+"></xs:pattern> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="SourceApplication" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Identifica, dentre os aplicativos integrados, qual instância gerou a mensagem. </xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:whiteSpace value="collapse"></xs:whiteSpace> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="CompanyId" type="xs:string" minOccurs="0"> <xs:annotation> <xs:documentation>Representa o id da empresa do usuário que enviou a mensagem.</xs:documentation> </xs:annotation></xs:element> <xs:element name="BranchId" type="xs:string" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Representa o id do estabelecimento do usuário que enviou a mensagem.</xs:documentation> </xs:annotation></xs:element> <xs:element name="UserId" type="xs:string" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Representa o id do usuário que enviou a mensagem. </xs:documentation> </xs:annotation></xs:element> <xs:element name="Enterprise" type="xs:string" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Representa, para o Protheus, o valor da empresa no sistema </xs:documentation> </xs:annotation></xs:element> <xs:element name="BusinessUnit" type="xs:string" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Representa, para o Protheus, o valor da unidade de negócios </xs:documentation> </xs:annotation></xs:element> <xs:element name="CompanySharingMode" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Indica o modo de compartilhamento no nível da Empresa. C para Compartilhada e E para Exclusiva.</xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="C"></xs:enumeration> <xs:enumeration value="E"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="BusinessUnitySharingMode" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Indica o modo de compartilhamento no nível da Unidade de Negócio. C para Compartilhada e E para Exclusiva.</xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="C"></xs:enumeration> <xs:enumeration value="E"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="BranchSharingMode" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Indica o modo de compartilhamento no nível da Filial. C para Compartilhada e E para Exclusiva.</xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="C"></xs:enumeration> <xs:enumeration value="E"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Product" maxOccurs="1" minOccurs="1"> <xs:annotation> <xs:documentation> Define qual o produto que originou esta mensagem. Não confundir o produto com a instância (atributo de TOTVSMessage). </xs:documentation> </xs:annotation> <xs:complexType> <xs:attribute name="name" type="xs:string" use="required"> <xs:annotation> <xs:documentation> Nome do Produto. </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="version" type="xs:string" use="optional"> <xs:annotation> <xs:documentation> Versão do Produto </xs:documentation> </xs:annotation> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="GeneratedOn" type="xs:dateTime" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Registra a data e hora em que a mensagem foi gerada. Observe que este campo é do tipo datetime e que é sugerido que se acrescente a identificação do fuso horário. Caso a informação de fuso não esteja presente, os sistemas entenderão o horário como GMT-0. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="DeliveryType" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Forma de entrega da mensagem que foi gerada. Será definida por quem entrega a mensagem.</xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="Sync"></xs:enumeration> <xs:enumeration value="Async"></xs:enumeration> <xs:enumeration value="sync"></xs:enumeration> <xs:enumeration value="async"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:element> </xs:sequence> <xs:attribute name="version" use="required"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value="\d+.\d+.\d+"></xs:pattern> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="GlobalIdType" use="optional"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="UUID"></xs:enumeration> <xs:enumeration value="INTERNALID"></xs:enumeration> <xs:enumeration value="internalid"></xs:enumeration> <xs:enumeration value="uuid"></xs:enumeration> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> |
Especificação do tipo 'UUIDType'
Bloco de código | ||
---|---|---|
| ||
<xs:simpleType name="UUIDType"> <xs:restriction base="xs:string"> <xs:pattern value="\w{8}-\w{4}-\w{4}-\w{4}-\w{12}"></xs:pattern> </xs:restriction> </xs:simpleType> |
Bloco de código | ||
---|---|---|
| ||
<xs:element name="InternalId" type="UUIDType" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Define um identificador universal para este recurso. Todas as mensagens que enviem um mesmo recurso terão o mesmo UUID e este valor permanece sempre o mesmo, seja no aplicativo que gera a mensagem, seja no que recebe. </xs:documentation> </xs:annotation> </xs:element> |
Bloco de código | ||
---|---|---|
| ||
<xs:element name="GlobalId" type="UUIDType" minOccurs="1" maxOccurs="1"> <xs:annotation> <xs:documentation> Define um identificador universal para este recurso. Todas as mensagens que enviem um mesmo recurso terão o mesmo UUID e este valor permanece sempre o mesmo, seja no aplicativo que gera a mensagem, seja no que recebe. </xs:documentation> </xs:annotation> </xs:element> |
Iremos incluir um atributo "GlobalIdType" no 'Header' da mensagem
Bloco de código | ||
---|---|---|
| ||
{ "GlobalIdType" : "string" } |
Bloco de código | ||
---|---|---|
| ||
{ "Header" : { "UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b", "Type" : "BusinessMessage", "SubType" : "event", "Transaction" : "CostCenter", "Version" : "2.000", "SourceApplication": "P1299", "ProductName" : "PROTHEUS", "ProductVersion" : "12.1.17", "CompanyId" : "99", "BranchId" : "01", "GeneratedOn" : "2017-11-14T11:47:00-03:00", "DeliveryType" : "async", "GlobalIdType" : "uuid" } } |
Bloco de código | ||
---|---|---|
| ||
{ "InternalId" : "string" } |
Utilização da entidade "InternalId" em mensagens padronizadas
Bloco de código | ||
---|---|---|
| ||
{ "Content" : { "CompanyId" : "99", "BranchId" : "01", "CompanyInternalId" : "99", "Code" : "ABC001", "InternalId" : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "RegisterSituation" : "Active", "Name" : "Centro de Custo ABC001", "ShortCode" : "ABC001", "SPED" : true, "Class" : 2 } } |
Bloco de código | ||
---|---|---|
| ||
{ "GlobalId" : "string" } |
Utilização da entidade "GlobalId" em mensagens padronizadas
Bloco de código | ||
---|---|---|
| ||
{ "Content" : { "GlobalId" : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" "CompanyId" : "99", "BranchId" : "01", "CompanyInternalId" : "99", "Code" : "ABC001", "InternalId" : "99|ABC001", "RegisterSituation" : "Active", "Name" : "Centro de Custo ABC001", "ShortCode" : "ABC001", "SPED" : true, "Class" : 2 } } |
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|