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": {
"transactionDefinition":{
"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.
Ao declarar uma API é obrigatório a documentação interna e esta deve conter as seguintes informações:
paths:
/Branch:
get:
tags:
- Branch
summary: "Retorna todas as Filiais da base"
x-totvs:
productInformation:
-protheus:
available: true
note: 'Este verbo esta disponivel com todos os parametros'
minimalVersion: '12..1.21'
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.
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:
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/Branchbranch_2_001.json
Índice |
---|