http://tdn.totvs.com/pages/viewpage.action?pageId=181142263

Objetivo

O objetivo da InternalId é permitir trafegar em um só campo a composição da chave das entidades de cada produto. Isto foi necessário, pois várias entidades dos produtos possuem composições de chaves diferentes e não pode ser responsabilidade dos produtos entender a complexidade da composição destas chaves uns dos outros.

...

Por mais que sempre existirão juntas as tags próprias (exemplo: CompanyId e BranchId) e as tags de InternalId (CompanyInternalId) o ideal é que os adapters passem a priorizar o reconhecimento das informações recebidas via InternalId. Ou seja, se a CustomerInternalId recebida em uma mensagem já existe nos valores de de/para do produto, quer dizer que já existe um registro local associado. Sendo assim, é mais fácil extrair da informação “50|123456” o código da empresa e cliente do Logix, do que resolver separadamente os de/para de empresa e de cliente, caso fosse esta a estratégia.

Identificação única de De/Para de InternalId

Atualmente cada produto (ex.: Logix, Datasul, Protheus e RM) tem seu próprio ferramental de de/para, ou seja, conjunto de tabelas e funções que permitem gravar valores de de/para referente a um determinado produto.

Tabela VDP_DPARA_GERAL


   TABELA_DPARA    CHAR(18)


   CAMPO_DPARA     CHAR(150)


   CARACTER_LOGIX  CHAR(150)


   SISTEMA_INTEGR  CHAR(20)


   CARACTER_INTEGR CHAR(150)

...

Assim, tendo os ferramentais de de/para de cada produto uma referência a este nome, será possível no futuro fazer uma rotina de conferência de integridade de de/para entre os produtos.

Múltiplas referências a uma InternalId na mesma mensagem

Vamos supor que a mensagem DeliverySchedule tenha os campos OriginCityCode e DestinationCityCode, consequentemente existirão os campos OriginCityInternalId e DestinationCityInternalId. A existência destes dois campos não significa que haverá dois de/para diferentes, um para Origin e outro para Destination, o de/para deverá ser o mesmo, ou seja, CityInternalId, pois a origem da informação é a mesma.

Esta mesma regra vale para quando o campo da chave estrangeira, por qualquer motivo, não tem um nome idêntico ao padrão “Mensagem”+InternalId, não necessariamente precisa existir dois campos com a mesma fonte de informação na mesma mensagem.

...

• Mensagem

...

• Order

...

• • Campos

...

• • VendorCode

...

• • e

...

• • VendorInternalId

Utilização na mensagem

A chave interna (InternalId) é utilizada em dois contextos, como chave primária e como chave estrangeira.

Regra para chave primária

Toda mensagem que seja de evento, deverá ter uma tag InternalId dentro de seu "BusinessContent" que irá trafegar a composição de chave da sua entidade. Deve-se ressaltar que mesmo que em um produto a chave de uma entidade não for composta deve-se utilizar a InternalId, pois se está é simples em um produto, mesmo assim poderá ser composta em outro.

Esta tag deverá estar localizada logo abaixo dos campos da mensagem, que fazem parte da sua composição. O exemplo a seguir é um trecho do schema RefundReason_1_000.json.

(...)


				"Code": {

					"description": "Código do Motivo",

					"type": "string",

					"x-totvs": [

						{

							"product": "PROTHEUS",

							"field": "G8P.G8P_CODIGO",

							"required": true,

							"type": "Char",

							"length": "4",

							"note": "",

							"available": true,

							"canUpdate": false

						}

					]

				},

				"InternalId": {

					"description": "InternalId do Motivo",

					"type": "string",

					"x-totvs": [

						{

							"product": "PROTHEUS",

							"field": "cEmpAnt+G8P.G8P_FILIAL+G8P.G8P_CODIGO",

							"required": true,

							"type": "Char",

							"length": "136",

							"note": "",

							"available": true,

							"canUpdate": false

						}

					]

				},

(...)

Suponhamos que em um cenário tenhamos CompanyId com valor 23 e Code com valor 50. O internalId trafegado seguiria então a seguinte lógica:

...

Toda mensagem de evento (quando for UpSertUpsert) deverá conter em seu conteúdo de retorno "ReturnContent" campos de InternalId para armazenar a chave interna do gerador do evento e a chave interna gerada no recebedor do evento. A necessidade disso é para que o recebedor da mensagem de evento e o gerador da mensagem de evento tenham conhecimento da chave interna gerada em cada produto. O fluxo abaixo exemplifica este funcionamento, para o cenário de inclusão de um novo Cliente.

...

(...)

		"ReturnContentType": {

			"type": "object",

			"properties": {

				"ListOfInternalId": {

					"type": "array",

					"items": {

						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/types/ListOfInternalId_1_000.json#/definitions/ListOfInternalIdType",

						"type": "object"

					}

				}

			}

		}

O ListOfInternalIdType está definido em um arquivo a parte e está estruturado conforme o exemplo abaixo:

(...)


"definitions": {

		"ReturnContentWithModelType": {

			"type": "object",

			"properties": {

				"ListOfInternalId": {

					"type": "object",

					"$ref": "#/definitions/ListOfInternalIdType"

				}

			}

		},

		"ListOfInternalIdType": {

			"type": "array",

			"items": {

				"$ref": "#/definitions/InternalIdType",

				"type": "object"

			}

		},

		"InternalIdType": {

			"type": "object",

			"properties": {

				"name": {

					"description": "Nome da InternalId, este nome será padronizado entre todas as linhas e  corresponderá ao nome da própria transação. Exemplo: City, Item, CustomerVendor. Observação: em outras partes da mensagem, que não sejam a tag ListOfInternalId, a regra pode ser diferente. Para mais informações, consulte  http://tdn.totvs.com/pages/viewpage.action?pageId=181142263",

					"type": "string"

				},

				"origin": {

					"description": "InternalId da origem",

					"type": "string"

				},

				"destination": {

					"description": "InternalId do destino",

					"type": "string"

				}

			}

		}

	}


(...)

Como este retorno representa a resposta de uma mensagem enviada, deve-se entender a tag "origin" como a InternalId do produto que enviou a mensagem (a origem), e "destination" como a InternalId do produto que foi o destino da mensagem.

Regra para chave estrangeira

A utilização da InternalId se aplica também para chaves estrangeiras. Porém, neste caso a regra é que para cada tag que representar uma chave estrangeira também exista uma tag InternalId correspondente. 

...

(...) 


				"InternalId": {					
					"description": "InternalId de Integração para o Grupo de Produto",
					"type": "string",
					"x-totvs": [
						{
							"product": "PROTHEUS",
							"available": true,
							"note": "O InternalID do Codigo do Armazém é formado por EMPRESA|NNR_FILIAL|NNR_CODIGO",
							"field": "EMPRESA|NNR_FILIAL|NNR_CODIGO",
							"length": "50",
							"type": "string"
						}
					]
				},
				"Code": {
					"description": "Código do Local de Estoque (armazém/almoxarifado/depósito)",
					"type": "string",
					"x-totvs": [
						{
							"product": "PROTHEUS",
							"available": true,
							"note": "Pode ter tamanho entre 02 e 06 dependendo da configuração do Protheus",
							"field": "NNRXX0.NNR_CODIGO",
							"length": "2",
							"type": "string",
							"required": true
						}
					]
				},
				"Description": {
					"description": "Descrição do Local de Estoque",
					"type": "string",
					"x-totvs": [
						{
							"product": "PROTHEUS",
							"available": true,
							"note": "Descrição do Local de Estoque(armazém/almoxarifado/depósito)",
							"field": "NNRXX0.NNR_DESCRI",
							"length": "20",
							"type": "string"
						}
					]
				}
(...)

...

Recomenda-se que a InternalId de chave estrangeira tenha o mesmo nome da tag normal – referenciando o InternalId de Warehouse, seria então WarehouseInternalId. No caso do exemplo acima, o analista optou por chamar de StandardWarehouseInternalId. Não há problema, porém é necessário que as outras definições que fazem referência a Warehouse sigam o mesmo padrão (StandardWarehouseCode e StandardWarehouseDescription).

...

Para a chave estrangeira o adapter também deverá dar prioridade em resolver o relacionamento pela InternalId. Ou seja, ao receber uma mensagem de Item (seguindo o exemplo), este deve primeiro consultar no seu ferramental de de/para se existe registro correspondente para o WarehouseInternaId recebido, pois este valor já irá fornecer a chave completa correspondente no produto.

Utilização no Adapter

É sabido que cada mensagem única terá um único adapter/versão nos produtos. Com o objetivo de centralizar a regra para composição da chave da InternalId é interessante que cada adapter seja responsável por receber os valores das chaves e concatena-los para a composição da InternalId. Se isto ficar a cargo de cada programa ou adapter que for utilizar o valor, este poderá correr o risco de ser concatenado de formas diferentes em cada ponto em que seja necessário, o que irá prejudicar completamente o funcionamento do recurso.

...

Adapter da mensagem Item



	AdapterItem.Get_InternalId(cod_empresa, cod_filial, item)


	Retorna Empresa + “|” + Filial + “|” + Código


	Uso: AdapterItem.Get_InternalId(50,10,123456) =  “50|10|123456”




	AdapterItem.Get_InternalId_Value(InternalId, Campo)


	Retorna <retorna o valor correspondente a posição de “Campo”>


	Uso: AdapterItem.Get_InternalId_Value(“50|10|123456”,”cod_empresa”) == “123456”

...