Documentação

A documentação da mensagem deve ser definida na propriedade customizada x-totvs que deve ficar dentro da propriedade info. O objetivo desta documentação é definir para cada mensagem o seu nome em português, uma descrição e descrever características de como ela está sendo implementada em cada produto.

O preenchimento desta documentação é obrigatório caso o produto implemente a mensagem, e de responsabilidade da equipe de negócio que definiu o seu conteúdo.

Mensagem: Branch

messageDocumentation

Informações gerais da mensagem representa o resultado do consenso. Ou seja, neste espaço deve ser informado o nome, descrição e conceito que estão em acordo com todos os outros produtos do grupo.

• name - Nome em português da mensagem
• description - Objetivo e funcionamento da mensagem
• segment - Nome do segmento a qual a mensagem pertence. Exemplo: controladoria, manufatura, finanças, recursos humanos. Neste caso sempre procure outras mensagens do mesmo segmento para saber qual nome exatamente está sendo usado, para utilizar o mesmo. Assim evita-se de uma mensagem usar “rh”, outra “Recursos Humanos” e outra “recursoshumanos”

productInformation

Informações específicas do produto para a mensagem. Aqui podem entrar informações para entender o que a mensagem representa dentro de determinado produto.

• contact - Email do grupo/equipe responsável pelo processo na linha
• description - Descrição específica para o produto
• adapter – Caso seja um adapter único para toda a mensagem, informar neste campo.
• helpUrls - Link com a documentação on-line do processo na linha

Documentação nos Verbos da API

Ao declarar uma API é obrigatório a documentação interna e esta deve conter as seguintes informações:

A propriedade x-totvs para identificar a documentação interna, contendo uma array de propriedades que o nome é o produto que será descrito, no exemplo protheus.

Cada verbo deve conter as seguintes informações:

• avaliable: campo booleano que indicia de o verbo esta implementado no produto.
• note: observações sobre o verbo referente ao produto, como regras especificas.
• minimalVersion: a versão minima na qual o verbo foi implementado no produto.

Direção

Sempre construir o Adapter (mensagem), pensando que ela deverá ser enviada e recebida, mesmo que o seu projeto não contemple as duas opções.

Codificação

A codificação utilizada nas mensagens do TOTVSMessage é o UTF-8

Versionamento

A assinatura ou contrato que representa a estrutura de dados e métodos recebidos ou retornados numa API/Serviço não pode ser alterada. Uma vez liberada ou publicado o serviço, a sua assinatura deve ser imutável.

As mensagens padronizadas estão preparadas para serem controladas por Versão e por Modificação.

Versão

Se a mensagem utilizar o "internalID" sugerimos que inicie pelo número "2" e somente irá mudar quando a alteração na mensagem torna esta incompatível com o layout anterior a alteração. A decisão de mudar a versão nunca deve ser tomada somente pelo analista, o comitê deverá ser envolvido desde o princípio quando uma possibilidade desta for identificada.

Exemplo:

• Exclusão de algum campo
• Alteração de tipo ou nome de campo
• Inclusão de chave estrangeira
• Inclusão de campo que pode alterar o comportamento da mensagem. Exemplos: campos de tipo, situação ou qualquer outro campo ou indicador que faça com que a informação possa ser entendida de uma forma diferente daquela da versão anterior.

Exemplo de alteração de versão:

• A mensagem Company_1_000.xsd não tratava a nova estrutura de mensagem com ReturnContentType e ListOfInternalId. Para tratar a nova estrutura de mensagem e os novos conceitos de InternalId foi criada a versão Company_2_000.xsd.

Quando uma mensagem mudar a versão, os sistemas precisam ser capazes de processar as versões anteriores.

Versão de mensagem x versão de produto:

Manter a compatibilidade entre as versões de mensagens, tratando campos atuais das versões do produto.

Exemplos:

• Incluído um campo na versão 12 do Produto e consequentemente evoluído a mensagem de 3.000 para 3.001.  A versão 12 do produto deverá ser capaz de processar a mensagem 3.000 (sem o campo novo) atribuindo um valor default para o campo evitando erros de CRUD. O mesmo se aplica para casos de alterações da estrutura da mensagem (de 3.000 para 4.000).

Modificação

Sempre começa por 000 e somente irá mudar quando algum campo puramente informativo for incluído na mensagem. Caso a versão/modificação da mensagem ainda estão com seus adapters sendo desenvolvidos pelos produtos e a mensagem em si nesta versão/modificação ainda não foi para cliente, é possível alinhar entre os produtos para que novos campos sejam incluídos na modificação atual.

Exemplo de modificação:

• A mensagem CostCenter_1_000.yaml tem seis tags e foi criada a versão CostCenter_1_001.yaml incluindo uma nova propriedade

Entregáveis

Ao elaborar uma nova mensagem ou a nova versão de uma mensagem existente a equipe de negócio deve:

• Entregar os arquivos YAML testados e validados utilizando uma ferramenta de validação de Swagger. No momento que o representante do Comitê receber as mensagens para avaliação, se houverem erros de sintaxe, estas serão recusadas.
• Preencher as documentações MessageDocumentation e documentações de campos em cada mensagem (obrigatório).
• Gerar e entregar o arquivo JSON a partir do Swagger para testar o preenchimento do arquivo e testar a ausência dos campos não obrigatórios conforme demanda da integração. Armazenar este no diretório TFS: TOTVSMSGXML: DEV\samples.

Exemplo de documentação:

branch_2_001.json