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": { "transactionMessageDocumentationtransactionDefinition":{ "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:
https://github.com/totvs/ttalk-standard-message/blob/master/jsonschema/schemas/Branch_2_001.json
Índice |
---|