Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

Elaborar a especificação que orientará a implementação do Identificador Global de Recursos nas respectivas linhas de produto com EAI.

Definições Gerais

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.

Pré-requisitos

As marcas deverão atender os seguintes pré-requisitos:

• Devem respeitar a sintaxe de URI descrita na RFC-3986;
• Devem respeitar a sintaxe de URN descrita na RFC-8141;
• Devem respeitar a definição de UUID descrita na RFC-4122;
• Devem respeitar a definição de JSON descrita na RFC-8259;

Termos e Nomenclaturas

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.

Definições da Regra de Negócio

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.

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.

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

Funcionamento

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.

Estrutura

A especificação atual das mensagens será alterada para discriminar o tipo de identificador de recursos sendo utilizado na mensagem disparada.

SOAP/XML

Iremos incluir um atributo "globalType" no elemento "InternalId" do conteúdo da mensagem padronizada

<xs:attribute name="globalType" type="xs:string" use="optional">
    <xs:restriction base="xs:string">
        <xs:enumeration value="UUID"></xs:enumeration>
        <xs:enumeration value="INTERNALID"></xs:enumeration>
        <xs:enumeration value="uuid"></xs:enumeration>
        <xs:enumeration value="internalid"></xs:enumeration>                        
    </xs:restriction>
</xs:attribute>

Especificação do elemento InternalId

<xs:element name="InternalId" type="xs:string" 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:complexType>
        <xs:attribute name="globalType" type="xs:string" use="optional">
            <xs:restriction base="xs:string">
                <xs:enumeration value="UUID"></xs:enumeration>
                <xs:enumeration value="INTERNALID"></xs:enumeration>
                <xs:enumeration value="uuid"></xs:enumeration>
                <xs:enumeration value="internalid"></xs:enumeration>                        
            </xs:restriction>
        </xs:attribute>
    </xs:complexType>
</xs:element>

Exemplo de utilização da estrutura proposta para representar um identificador global de recursos

<InternalId globalType="uuid">f81d4fae-7dec-11d0-a765-00a0c91e6bf6</InternalId>

REST/JSON

Iremos incluir um atributo "GlobalType" duas propriedades no elemento "ContentInternalId" da mensagem padronizada

{
    "title"uuid": {
        "type": "Content",
string"
    },
    "internalid": {
        "type": "string"
    }
}

Especificação do elemento "InternalId"

{
    "InternalId": {
        "type": "object",
        "properties": {
         "GlobalType   "uuid": {
                "type": "string"
            },
            "internalid": {
                "type": "string"
            }
        }
    }
}

Utilização da entidade "InternalId" em mensagens padronizadas

{
    "Content" : {
        "CompanyId" : "99",
        "BranchId" : "01",
        "CompanyInternalId" : "99",
        "Code" : "ABC001",
        "GlobalTypeInternalId" : {"uuid"
        "InternalId" : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"},
        "RegisterSituation" : "Active",
        "Name" : "Centro de Custo ABC001",
        "ShortCode" : "ABC001",
        "SPED" : true,
        "Class" : 2
    }
}