Frameworksp

Atalhos

Páginas filhas
  • ER_DEAI1_Identificador_Global_de_Recursos

Versões comparadas

Versão antiga 39

changes.mady.by.user Rafael Tudela C Lacerda Caldas

Gravado em

comparado com

Nova versão 40

changes.mady.by.user Rafael Tudela C Lacerda Caldas

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

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


Índice


Informações Gerais

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

Objetivo

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


Informações
titlePara sua informação

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.


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.


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.

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.


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

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

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.

Todos os adapters deverão estar preparados para receber o Identificador Global de Recursos e retornar este mesmo identificador na tag "Destination" do elemento "InternalId" de forma que a migração possa ocorrer de forma gradativa.


Image Added

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 nos elementos "InternalId" do conteúdo da mensagem padronizada

Bloco de código
languagexml
<xs:attribute name="globalType" type="xs:string" use="optional">
    <xs:restriction base="xs:string">
        <xs:enumeration value="UUID"></xs:enumeration>
        <xs:enumeration value="uuid"></xs:enumeration>
    </xs:restriction>
</xs:attribute>

Especificação do elemento "InternalId"

Bloco de código
languagexml
<xs:element name="InternalId" type="xs:string" minOccurs="0" maxOccurs="1">
    <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="uuid"></xs:enumeration>
            </xs:restriction>
        </xs:attribute>
    </xs:complexType>
</xs:element>

Exemplos

Utilização da entidade "InternalId" em mensagens padronizadas para identificar recursos globais

Especificação do elemento "ListOfInternalId"

Bloco de código
languagexml
        <BusinessContent><xs:complexType name="ListOfInternalIdType">
        <xs:sequence>
    <InternalId globalType="uuid">f81d4fae-7dec-11d0-a765-00a0c91e6bf6</InternalId>
       <xs:element name="InternalId" type="InternalIdType" minOccurs="1" maxOccurs="unbounded" <OrderPurpose>1</OrderPurpose>>
        </xs:sequence>
    <CompanyId>4</CompanyId></xs:complexType>

    <xs:complexType name="InternalIdType">
       <CompanyInternalId>4|1</CompanyInternalId>
 <xs:attribute name="globalType" type="xs:string" use="optional">
             <BranchId>1</BranchId>
<xs:restriction base="xs:string">
              <CustomerOrderId>4|</CustomerOrderId>
  <xs:enumeration value="UUID"></xs:enumeration>
                 <RegisterDate></RegisterDate><xs:enumeration value="uuid"></xs:enumeration>
            <PaymentTermCode>4|001</PaymentTermCode></xs:restriction>
            <OrderId>5652</OrderId></xs:attribute>

         <xs:sequence>
   <UserInternalId>mestre</UserInternalId>
         <xs:element name="Name"  <PaymenTermCode></PaymenTermCode>type="xs:string" minOccurs="0" maxOccurs="1">
            <CurrencyCode></CurrencyCode>
    <xs:annotation>
        <CurrencyId></CurrencyId>
            <Observation></Observation><xs:documentation>
            <ListOfCreditDocument></ListOfCreditDocument>
            <DeliveryAddress>
Nome da InternalId, este nome será padronizado como o nome 
      <City></City>
                <State>
  que esta internalId teria como chave extrangeira de uma mensagem.
            <StateCode></StateCode>
            
        <StateInternalId></StateInternalId>
                </State>
Exemplo:
               </DeliveryAddress>
         Para entidade Item: <Discounts>ItemInternalId
                <Discount>0</Discount>
            </Discounts>
           City: <SalesOrderItens>CityInternalId
                 <Item>
                    <OrderItem>1</OrderItem> CustomerVendor: CustomerVendorInternalId
                    <CompanyId>4</CompanyId>
    </xs:documentation>
                <BranchId><</BranchId>xs:annotation>
            </xs:element>

          <OrderId>5652</OrderId>
  <xs:element name="Origin" type="xs:string" minOccurs="0" maxOccurs="1">
              <itemunitofmeasure></itemunitofmeasure>
  <xs:annotation>
                  <InternalId>4|5652|1</InternalId>
  <xs:documentation>InternalId da origem</xs:documentation>
                <ItemCode><</ItemCode>xs:annotation>
                    <ItemInternalId>4|</ItemInternalId>xs:element>

            <xs:element name="Destination"       <CostCenter>4|</CostCenter>type="xs:string" minOccurs="0" maxOccurs="1">
                <xs:annotation>
    <UnityPrice></UnityPrice>
                <xs:documentation>InternalId do   <TotalPrice></TotalPrice>destino</xs:documentation>
                    <Quantity></Quantity></xs:annotation>
            </xs:element>

        <Observation><</Observation>xs:sequence>
    </xs:complexType>


Exemplos

Utilização da entidade "InternalId" em mensagens padronizadas para identificar recursos globais

Bloco de código
languagexml
           <BusinessContent>
     <UnitOfMeasureInternalId></UnitOfMeasureInternalId>
       <InternalId globalType="uuid">f81d4fae-7dec-11d0-a765-00a0c91e6bf6</InternalId>
            <WarehouseInternalId>4||</WarehouseInternalId><OrderPurpose>1</OrderPurpose>
            <CompanyId>4</CompanyId>
        <FreightValue></FreightValue>
    <CompanyInternalId globalType="uuid">19dfb9b3-901c-48ce-9954-2cb147ec4fe8</CompanyInternalId>
            <BranchId>1</BranchId>
    <ListOfApportionOrderItem></ListOfApportionOrderItem>
        <CustomerOrderId>4|</CustomerOrderId>
            <ItemDiscounts><RegisterDate></RegisterDate>
            <PaymentTermCode>4|001</PaymentTermCode>
            <ItemDiscount><<OrderId>5652</ItemDiscount>OrderId>
            <UserInternalId>mestre</UserInternalId>
        </ItemDiscounts>
    <PaymenTermCode></PaymenTermCode>
            <<CurrencyCode></Item>CurrencyCode>
            <<CurrencyId></SalesOrderItens>CurrencyId>
        </BusinessContent>

Utilização da entidade "InternalId" em mensagens padronizadas para identificar recursos através de de-para

Bloco de código
languagexml
    <Observation></Observation>
    <BusinessContent>
        <ListOfCreditDocument></ListOfCreditDocument>
    <InternalId>4|5652</InternalId>
        <DeliveryAddress>
    <OrderPurpose>1</OrderPurpose>
            <CompanyId>4<<City></CompanyId>City>
                <CompanyInternalId>4|1</CompanyInternalId><State>
            <BranchId>1</BranchId>
            <CustomerOrderId>4|</CustomerOrderId><StateCode></StateCode>
            <RegisterDate></RegisterDate>
        <StateInternalId></StateInternalId>
    <PaymentTermCode>4|001</PaymentTermCode>
            <OrderId>5652<</OrderId>State>
            <UserInternalId>mestre<</UserInternalId>DeliveryAddress>
            <PaymenTermCode></PaymenTermCode>
<Discounts>
                <CurrencyCode><<Discount>0</CurrencyCode>Discount>
            <CurrencyId><</CurrencyId>Discounts>
            <Observation></Observation><SalesOrderItens>
            <ListOfCreditDocument></ListOfCreditDocument>
    <Item>
        <DeliveryAddress>
            <OrderItem>1</OrderItem>
    <City></City>
                <State><CompanyId>4</CompanyId>
                    <StateCode><<BranchId></StateCode>BranchId>
                    <StateInternalId><<OrderId>5652</StateInternalId>OrderId>
                 </State>
   <itemunitofmeasure></itemunitofmeasure>
         </DeliveryAddress>
            <Discounts><InternalId globalType="uuid">95a81989-e487-4012-b8e2-b5ae97d3e078</InternalId>
                <Discount>0</Discount>
    <ItemCode></ItemCode>
        </Discounts>
            <SalesOrderItens>
 <ItemInternalId globalType="uuid">7371ec73-3062-476d-93cf-251560d130da</ItemInternalId>
               <Item>     <CostCenter>4|</CostCenter>
                    <OrderItem>1<<UnityPrice></OrderItem>UnityPrice>
                    <CompanyId>4<<TotalPrice></CompanyId>TotalPrice>
                    <BranchId><<Quantity></BranchId>Quantity>
                    <OrderId>5652<<Observation></OrderId>Observation>
                     <itemunitofmeasure></itemunitofmeasure><UnitOfMeasureInternalId globalType="uuid">5eeba464-3748-41a6-a5f7-1cff2ca69aeb</UnitOfMeasureInternalId>
                    <InternalId>4|5652|1</InternalId><WarehouseInternalId globalType="uuid">c3507b85-a799-42b0-8e71-07cf886ec781</WarehouseInternalId>
                    <ItemCode><<FreightValue></ItemCode>FreightValue>
                    <ItemInternalId>4|<<ListOfApportionOrderItem></ItemInternalId>ListOfApportionOrderItem>
                    <CostCenter>4|</CostCenter>
<ItemDiscounts>
                        <UnityPrice><<ItemDiscount></UnityPrice>ItemDiscount>
                    <TotalPrice><</TotalPrice>ItemDiscounts>
                    <Quantity></Quantity></Item>
            </SalesOrderItens>
        <Observation></Observation></BusinessContent>

Utilização da entidade "ListOfInternalId" em mensagens padronizadas para identificar recursos globais

Bloco de código
languagexml
<TOTVSMessage>
  <MessageInformation version="1.000">
    <UUID>6403aa6a-700d-a535-c567-8ea0be5c9142</UUID>
    <Type>Response</Type>
    <Transaction>CONTRACT</Transaction>
     <UnitOfMeasureInternalId></UnitOfMeasureInternalId><StandardVersion>1.000</StandardVersion>
    <SourceApplication>PADRAO_EAI2</SourceApplication>
    <CompanyId>01</CompanyId>
    <BranchId>1U</BranchId>
    <Product    <WarehouseInternalId>4||</WarehouseInternalId>name="PROTHEUS" version="12"></Product>
    <GeneratedOn>2018-01-08T16:53:45</GeneratedOn>
    <DeliveryType>Sync</DeliveryType>
  </MessageInformation>
  <ResponseMessage>
        <FreightValue></FreightValue><ReceivedMessage>
      <SentBy>RM</SentBy>
       <UUID>bf920a68-8263-4e1a-8076-2084a55e69d2</UUID>
       <ListOfApportionOrderItem><<Event>Upsert</ListOfApportionOrderItem>Event>
      <MessageContent><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<TOTVSMessage>
            <ItemDiscounts><MessageInformation version="1.000">
          <UUID>bf920a68-8263-4e1a-8076-2084a55e69d2</UUID>
        <Type>BusinessMessage</Type>
        <ItemDiscount><<Transaction>CONTRACT</ItemDiscount>Transaction>
        <StandardVersion>1.000</StandardVersion>
            </ItemDiscounts><SourceApplication>RM</SourceApplication>
        <CompanyId>1</CompanyId>
        <<BranchId>1</Item>BranchId>
        <Product    </SalesOrderItens>name="RM" version="12.1.17.0" />
        </BusinessContent>

REST/JSON

Iremos incluir a propriedade "uuid" no elemento "InternalId" da mensagem padronizada para representar uma mensagem trafegando um identificador global

Bloco de código
languagejs
{
<GeneratedOn>2018-01-08T18:53:40</GeneratedOn>
       "uuid": { <DeliveryType>Sync</DeliveryType>
    </MessageInformation>
    "type": "string"
    }
}

Especificação do elemento "InternalId"

Bloco de código
languagejs
{
    "InternalId": {
        "type": ["object", "string"]<BusinessMessage>
        <BusinessEvent>
            <Entity>CONTRACT</Entity>
            <Event>Upsert</Event>
        </BusinessEvent>
        <BusinessContent>
            <RMENTITYNAME>MCNT</RMENTITYNAME>
            <InternalId globalType="uuid">f555297a-951f-415d-8672-4a08f2251d40</InternalId>
            <CompanyId>1</CompanyId>
            <ProjectInternalId globalType="uuid">a82462a7-481b-4839-b525-272184f86cb6</ProjectInternalId>
            <ContractNumber>333333</ContractNumber>
        </BusinessContent>
    </BusinessMessage>
</TOTVSMessage>
]]></MessageContent>
    </ReceivedMessage>
    <ProcessingInformation>
      <ProcessedOn>2018-01-08T16:53:45</ProcessedOn>
      <Status>ok</Status>
    </ProcessingInformation>
    <ReturnContent>
      <ListOfInternalId>
  "properties": {
     <InternalId>
       "uuid": {   <Name>Contract</Name>
          <Origin>f555297a-951f-415d-8672-4a08f2251d40</Origin>
      "type": "string"
   <Destination>f555297a-951f-415d-8672-4a08f2251d40</Destination>
         }</InternalId>
      </ListOfInternalId>
  }
  </ReturnContent>
  }
}

Exemplos

Utilização da entidade "InternalId" em mensagens padronizadas para identificar recursos globais
</ResponseMessage>
</TOTVSMessage>

REST/JSON

Iremos incluir a propriedade "uuid" no elemento "InternalId" da mensagem padronizada para representar uma mensagem trafegando um identificador global

Bloco de código
languagejs
{
    "Contentuuid" : {
        "CompanyIdtype" : "99string",
    }
}

Especificação do elemento "InternalId"

Bloco de código
languagejs
{
    "BranchIdInternalId" : "01",{
        "CompanyInternalIdtype" : ["99object",
        "Code" : "ABC001","string"]
        "InternalIdproperties" : {"uuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"},

          "RegisterSituation" : "Active",
   uuid": {
     "Name" : "Centro de Custo ABC001",
        "ShortCodetype" : "ABC001string",
        "SPED" : true,
  }
      "Class" : 2}
    }
}

Exemplos

Utilização da entidade "InternalId" em mensagens padronizadas para identificar recursos

através de de-para

globais

Bloco de código
languagejs
{
    "Content" : {
        "CompanyId" : "99",
        "BranchId" : "01",
        "CompanyInternalId" : "99",
        "Code" : "ABC001",
        "InternalId" : {"uuid": "99|ABC001"f81d4fae-7dec-11d0-a765-00a0c91e6bf6"},
        "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.