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
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
"info": { "description": "Contrato de Mensagem Padronizada para a entidade filial (Branch) para produtos TOTVS", "version": "2.001", "title": "Branch", "contact": { "name": "T-Talk", "url": "API.Totvs.com.br", "email": "[email protected]" }, "x-totvs": { "transactionMessageDocumentation":{ "subType":"event", "businessContentType":{ "type":"object", "$ref":"#/definitions/BranchType" }, "returnContentType":{ "type":"object", "$ref":"https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/ListOfInternalId_1_000.json#/definitions/ReturnContentWithModelType" } }, "messageDocumentation": { "name": "Branch", "description": "Filial", "segment": "FrameWork" }, "productInformation": [ { "product": "protheus", "contact": "[email protected]", "description": "Cadastro de Filial", "adapter": "apcfg230i.prw", "helpUrl": "link aqui" } ] } } |
Informações da estruturação da Mensagem Padronizada no protocolo Transactions, descrevendo o tipo da mensagem, o contrato das tags BusinessContent e ReturnContent, dentre outras informações .
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.
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.
Mensagem: Branch
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
(...),
"definitions": {
(...),
"BranchType": {
"type": "object",
"properties": {
"CompanyCode": {
"type": "string",
"example": "D",
"description": "Código da Empresa",
"x-totvs": [
{
"product": "protheus",
"Field": "XX8.XX8_CODIGO",
"Required": false,
"Type": "Char",
"length": "12",
"avialable": true,
"canUpdate": false
{
]
},
(...)
}
}
},
(...) |
Informações do campo da Mensagem Padronizada para cada linha de produto que o implementa, que contém as propriedades descritas abaixo.
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.
A codificação utilizada nas mensagens do TOTVSMessage é o UTF-8
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.
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:
Exemplo de alteração de versão:
Quando uma mensagem mudar a versão, os sistemas precisam ser capazes de processar as versões anteriores.
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).
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:
Ao elaborar uma nova mensagem ou a nova versão de uma mensagem existente a equipe de negócio deve:
Índice |
---|