Documentação

Um campo declarado dentro da mensagem permite dois modos diferentes e obrigatórios de documentação. O conteúdo de <xs:documentation> e o conteúdo de <xs:annotation> <FieldDocumentation>

Na documentação em <xs:documentation> é importante que a descrição esteja bem detalhada, lembre-se que para o analista que está propondo um campo, o objetivo deste campo é sempre muito óbvio, porém próximos analistas do mesmo produto ou até analistas de outros produtos sempre terão dificuldade caso o campo não esteja bem documentado.

Consulte o tópico Padrão de nomenclatura para mais detalhes sobre a correta redação da documentação dos campos e elaboração de seus nomes.

ATENÇÃO! Campos de InternalId só precisam de <FieldDocumentation> se representarem a PK da mensagem. Se estes estiverem representando a FK de uma entidade pode-se entender que na declaração da PK já existe a documentação. Isto é interessante para evitar a replicação da definição da composição das chaves da InternalId na documentação.

Field

A qual tabela.campo o campo da mensagem se refere.

Caso no produto este campo possa estar em mais tabela, explicar o funcionamento.

Exemplo:

<Field>clientes.cod_cliente</Field>

ou

<Field>cliente.cod_cliente para Type=Customer ou fornecedor.cod_fornecedor para Type=Vendor</Field>

Required

Obrigatoriedade do campo, ou condições em que ele será obrigatório ou não.

Exemplo:

<Required>sim</Required>

<Required>não</Required>

<Required>sim, caso o centro de custo do departamento estiver preenchido</Required>

Type

Tipo do campo no produto. Importante declarar aqui o tipo do campo como é conhecido no produto.

Exemplo:

 <Type>char</Type>

<Type>varchar</Type>

<Type>number</Type>

<Type>decimal</Type>

<Type>integer</Type>

<Type>boolean</Type>

Length

Tamanho do campo no produto, pode ser informado apenas o tamanho ou outro texto que descreva como este tamanho funciona.

Exemplo:

<Length>20</Length>

<Length>8,2</Length>

<Length>sempre implantado como 20, mas o cliente pode usar até 50</Length>

Description

Complemento de informações sobre o campo se for o caso.

Exemplo:

• Formato da informação
• Vínculo entre mensagens
• Escopo de dados - Deve ser informado para campos que precisam respeitar uma relação específica de valores no produto, podendo ser informado aqui:
  • 'lista fixa'   ou

• • 'valores da tabela [tabela.campo]'. 
  
  Caso na mensagem tenha sido definida lista fixa, informar aqui a relação dos valores da mensagem com os valores do produto.

...ou qualquer outra informação importante para descrever a representação desta tag no produto em questão.

Padrão de nomenclatura

Os nomes dos campos na mensagem única devem respeitar as regras a seguir:

• Devem ser sempre escritos em inglês.

Procure discutir com outras pessoas ou pesquisar no Google Translator a tradução correta dos termos. Deve-se prestar muita atenção na possibilidade de ocorrerem os falsos cognatos.

Exemplo: Código do Turno é ShiftCode e não TurnCode e nem CodeOfTurn. Turn em inglês significa: transformar, voltar, vez e não “turno”, é um caso de falso cognato.

• Formatação em camel case

Devem respeitar a formatação em camelCase com a primeira letra em maiúsculo.
Exemplo: CustomerCode, RegisterDate, ListOfItem, TypeOfDay

• Padrão para chaves primárias e estrangeiras simples

Ao criar o elemento que representa a chave primária da mensagem utilize apenas a palavra Code, quando for chave simples. Exemplo: na mensagem Seller, use Code e Description/Name.

Exemplo:

Mensagem  Item

   Code

   Description

   Status

   RegisterDate

Ao utilizar esta chave primária como chave estrangeira em outra mensagem, utilize o padrão “Mensagem” + “Code”, ou seja ItemCode, CustomerCode, BankCode. Exemplo: Na mensagem SalesOrder use SellerCode.

Exemplo:

Mensagem Warehouse

   Code

   Description

Mensagem Item

   Code
   Description

   Status

   RegisterDate
   WarehouseCode

• Reaproveitamento de nomes

Deve-se evitar a utilização de nomes diferentes para campos com o mesmo objetivo, por isso ao criar os nomes de campos para uma mensagem é importante verificar em outras mensagens qual termo está sendo utilizado para o mesmo objetivo.

Exemplos:

• • Utilizar sempre CompanyId e BranchId para empresa e filial
  • Utilizar sempre ItemCode pois este já é utilizado em todas as mensagens que usam a chave primária da mensagem Item. Não utilizar ProductCode, a mensagem para produto é a Item.
  • Utilizar VendorCode para código do representante e não Suplier e nem Provider, pois a mensagem já existente é CustomerVendor.
  • Hoje já existe a mensagem Role, que representa Cargo no Logix. O Cargo do Logix corresponde a Função no Protheus. Então novas mensagens propostas pelo Protheus têm que usar o termo Role para Função e não Function.

• Utilize nomes que reflitam a descrição e vice-versa

Exemplos reais e proposta de correção:

TableCodeItem - Código da Tabela de Preços (Deveria ser PriceListCode ou PriceTableCode)

SalesPrice - Preço de mínimo de venda do produto (Deveria ser MinimumSalesPrice)

Tipos dados padrões

Os tipos padrões para os elementos dentro da mensagem única são os seguintes:

Texto

Decimal

Inteiro

Boleano

Data

Hora

Data & Hora

Obrigatoriedade

No XSD as TAGs devem ser definidas como não obrigatórias, pois as mensagens únicas são utilizadas tanto para inclusão quando para exclusão. Ou seja, uma exclusão não precisa enviar tantas informações quanto a inclusão. Se a mensagem única tivesse os seus campos obrigatórios geraria a necessidade de se enviar o registro completo para exclusão e não apenas a sua chave.

Além disso, a obrigatoriedade de um campo depende de cada produto, o que torna muito mais difícil chegar a um consenso se for necessário considerar esta característica na mensagem.

Por isso, todo campo na mensagem será declarado com os atributos:

minOccurs=”0” maxOccurs=”1”

Campos que se repetem poderão apresentar um padrão diferente, consulte o tópico Criando listas de valores e elementos para mais informações.

Havendo a necessidade de validação da presença ou não de informação na mensagem, este controle deve ser feito no próprio adapter. 

Exclusão parcial de informações

As mensagens de integração possuem em seu cabeçalho <BusinessEvent> a informação <Event>, que pode ter os valores upsert ou delete e vale para toda a mensagem.

Quando existir a necessidade de anotar apenas alguns itens da mensagem para serem excluídos, pode-se incluir uma tag <Event> dentro da estrutura de filhos para conter esta informação.

ATENÇÃO! Este recurso somente será válido se a mensagem estiver anotada como upsert e opcionalmente seus itens anotados como delete.

Esta tag <Event> deverá existir fisicamente no XSD, como se fosse outro campo qualquer.

A inclusão destas tags deve gerar nova versão de mensagem, mas não exige consenso. A nova versão é necessária pois ela muda drasticamente a forma de tratamento das informações, ou seja, se um adapter de uma versão anterior receber a mensagem com uma anotação de delete exclusivo de item, o item não será deletado, pois o adapter irá ignorar a informação.

Se a mensagem inteira for enviada como Event delete, ela será excluída por inteiro.

A única opção de uso deste recurso é para mensagem upsert e item delete.

Campos de código + descrição

Não é necessário montar mensagens específicas para tabelas que só precisarão trafegar código + descrição. Estas informações poderão trafegar como chave estrangeira na mensagem que as utilizar. Também não é necessário criar agrupadores específicos para estes campos, podem ser colocados na raiz das mensagens.

Exemplo:

Hipoteticamente, a mensagem Item deverá levar a informação do fabricante.

Mensagem Item
   Code
   Description
   ManufacturerCode
   ManufacturerDescription

Por exemplo: Não existe a necessidade de criar a mensagem Manufacturer (supondo que contém apenas Código + Descrição). Estes dados deverão ser enviados na mensagem de Item 

Campos com valores fixos

Campos com valores fixos devem ser definidos como xs:string e seus valores respeitar a sequencia 1,2,3,4 etc... O objetivo desta definição é evitar confusões pelo uso de letras iguais para objetivos diferentes entre os produtos TOTVS. Exemplo: RM Pedido Cancelado = “C”, Datasul Pedido Concluído = “C”. Utilizando sempre a seqüência numérica o desenvolvedor se vê obrigado a observar a lista de valores presentes na mensagem, observando inclusive se o tipo que queira utilizar já está listado no schema XML.

Porém, muitas vezes quando um campo em um produto é composto por uma lista fixa de valores, em outro produto esses valores podem ser cadastrados dinamicamente. Exemplo: Tipo do documento no Logix é fixo, no Protheus é pre-cadastrado e permite alterar, na Datasul é fixo e na RM é totalmente cadastrável. Para estes casos leia o tópico Conflito entre valores fixos e valores cadastráveis.

Exemplo: