Documentação

A documentação da mensagem deve ser definida no bloco <xs:annotation> logo no início do arquivo. 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: Departament

<!-- ------------------------------------ -->

  DOCUMENTAÇÃO DO CAMPO

<!-- ------------------------------------ -->

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 - Nome das pessoas de contato do produto sobre esta mensagem
• Description - Descrição específica para o produto
• Adapter – Caso seja um adapter único para toda a mensagem, informar neste campo.

Send

Identifica quais formas de envio foram implementadas na mensagem. O campo é livre, informe “sim” ou “não”, o nome do adapter caso seja específico para este modo, ou alguma particularidade da implementação.

• Insert - Implementa Insert? qual Adapter? alguma particularidade?
• Update - Implementa Update? qual Adapter? alguma particularidade?
• Delete - Implementa Delete? qual Adapter? alguma particularidade?

Receive

Identifica quais forma de recebimento foram implementadas na mensagem. O campo é livre, informe “sim” ou “não”, o nome do adapter caso seja específico para este modo, ou alguma particularidade da implementação.

• Insert - Implementa Insert? qual Adapter? alguma particularidade?
• Update - Implementa Update? qual Adapter? alguma particularidade?
• Delete - Implementa Delete? qual Adapter? alguma particularidade?

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.xsd tem seis tags e foi criada a versão CostCenter_1_001.xsd incluindo uma nova Tag: 

<xs: element name="Class" minOccurs="1">

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 XSD testados e validados utilizando uma ferramenta de validação de XML Schema (Stylus Studio ou Eclipse). 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 FieldDocumentation em cada mensagem (obrigatório).
• Gerar e entregar o arquivo XML a partir do XSD 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.