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.

Documentação da Mensagem Padronizada (MessageDocumentation)

Mensagem: Branch

"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"
             	}
            ]
        }
    }

transactionDefinition

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 .

• subType  - Tipo da Mensagem Padronizada, definido entre "event" e "request"
• businessContentType - Tipo definido no schema para o Content da BusinessMesage. 
• returnContentType - Tipo definido no schema para o campo ReturnContent da ResponseMesage.

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 de campos da Mensagem Padronizada (annotation)

Mensagem: Branch

(...),
"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
						{
					]
				},
			(...)
			}
		}
	},
(...)

x-totvs

Informações do campo da Mensagem Padronizada para cada linha de produto que o implementa, que contém as propriedades descritas abaixo.

• product - Linha de produto da respectiva documentação.
• Description - Descrição do campo para a linha de produto.
• Field - Campo equivalente para a linha especificada. 
• Required - Informa se o campo é obrigatório.
• Type - Tipo do campo equivalente.
• lenght - Tamanho do campo.
• available - Informa se o campo é utilizado por esta linha de produto.
• canUpdate - Informa se este campo pode ser alterado.

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 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.

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.json tem seis tags e foi criada a versão CostCenter_1_001.json 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 Json Schema testados e validados utilizando uma ferramenta de validação. 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 seguindo o Json Schema para testar o preenchimento do arquivo e testar a ausência dos campos não obrigatórios conforme demanda da integração. 

Exemplo de documentação

https://github.com/totvs/ttalk-standard-message/blob/master/jsonschema/schemas/Branch_2_001.json