Versões comparadas
Chave
- Esta linha foi adicionada.
- Esta linha foi removida.
- A formatação mudou.
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
Observar a Lei nr. 02 de Integrações: A assinatura de uma API/Serviço liberada não pode ser alterada, somente evoluída.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 únicas padronizadas estão preparadas para serem controladas por Versão e por Modificação.
Versão
Sempre começa por 1 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.
Índice | |
---|---|
|