Histórico da Página
| Informações | ||||
|---|---|---|---|---|
| ||||
|
Objetivo
...
Com o objetivo de evitar problemas com padrão de mensagem para trocas entre sistemas, foi definida uma nova diretriz para os projetos de integração: A de que todos os produtos TOTVS devam trabalhar com uma mensagem XML única evitando, desta forma, o processo de transformação de mensagens. Neste cenário, teríamos o seguinte quadro:
...
Além de questões referentes ao formato das mensagens, a mensagem única também torna uniforme o tratamento destas mensagens XML pelos aplicativos, principalmente no que diz respeito à capacidade de rastreamento.
Anatomia da Mensagem TOTVS
...
A Mensagem Única TOTVS estabelece alguns padrões que devem ser seguidos por todos os aplicativos que participem da integração. Estes padrões estabelecem alguns tipos de mensagens suportadas bem como informações obrigatórias que devem fazer parte do seu conteúdo.
A composição do conteúdo de cada uma das mensagens de negócio será definida em conjunto com especialistas de negócio e não faz parte do escopo deste documento.
Tipos de Mensagens
...
O padrão de mensagem TOTVS estabelece quatro tipos de mensagens: BusinessMessage, ResponseMessage, ReceiptMessage e MalformedMessage.
BusinessMessage
...
Uma mensagem do tipo BusinessMessage são aquelas que iniciam qualquer processo de troca de mensagens entre os aplicativos. Sempre que um aplicativo A quiser enviar ou solicitar informações do aplicativo B, ele enviará uma BusinessMessage que será processada pelo aplicativo destinatário.
...
A tabela abaixo apresenta um comparativo entre mensagens de evento e de solicitação:
| Event | Request | |
|---|---|---|
| Objetivo | Replicação de dados | Compartilhar lógicas |
| Quem gera | Um (cadastro master) | Vários (clientes que precisam da lógica) |
| Quem responde | Vários (cadastros replicados) | Um (detentor da lógica) |
| Uso comum | Assíncrono (envia e esquece) | Síncrono (envia e aguarda) |
| Exemplo | Upsert UnitOfMeasure | getCashAvailableOnDate |
ResponseMessage
...
Uma ResponseMessage representa o resultado do processamento de uma BusinessMessage pelo aplicativo que a recebeu e o seu conteúdo pode variar de acordo com o tipo de mensagem e com o resultado do processamento.
Todas as respostas geradas por uma BusinessMessage devem ser associadas à mensagem original e mantidas pelo aplicativo-origem, como forma de rastrear quem processou aquela mensagem e qual o resultado do processamento.
Atributos da classe:
| Atributo | Tipo | Descrição |
|---|---|---|
| CustomInformation | CustomInformation | Retorna ou atribui informações customizadas |
| NUM-MESSAGES | INTEGER | Retorna número de mensagens de erro ou não na mensagem |
| ProcessedOn | DATETIME-TZ | Retorna ou atribui data de processamento |
| ReceivedMessageInfo | ReceivedMessageInfo | Retorna ou atribui informações da mensagem original (BusinessMessage) |
| ReturnContent | LONGCHAR | Retorna ou atribui mensagem original (BusinessMessage) |
| STATUS | CHARACTER | Retorna se a resposta contém erros ou não: “OK” ou “ERROR”. |
| TYPE | CHARACTER | Retorna o tipo do objeto: “Response” |
...
Métodos da classe:
| Método | Retorno | Descrição |
|---|---|---|
| addMessage | void | Adiciona mensagem na mensagem. Caso uma mensagem do tipo ERROR, o atributo STATUS é alterado para OK. |
| createResponse | ResponseMessage | Cria uma mensagem de resposta a partir de uma BusinessMessage. |
| GET-MESSAGE-CODE | CHARACTER | Retorna o código de uma determinada mensagem. Usada em conjunto com o atributo NUM-MESSAGES. |
| GET-MESSAGE-DESC | CHARACTER | Retorna a descrição de uma determinada mensagem. Usada em conjunto com o atributo NUM-MESSAGES. |
| GET-MESSAGE-TYPE | CHARACTER | Retorna o tipo de uma determinada mensagem. Usada em conjunto com o atributo NUM-MESSAGES. |
| prepare-message | void | Altera o horário de processamento da mensagem com o horário corrente, antes de devolver ao sistema externo. |
ReceiptMessage
...
Uma ReceiptMessage representa a confirmação de recebimento de uma BusinessMessage pelo aplicativo destino.
...
Quando a mensagem for processada pelo aplicativo-destino, uma mensagem de resposta (ResponseMessage) será gerada e encaminhada ao aplicativo que originou a BusinessMessage.
MalformedMessage
...
A MalformedMessage não é propriamente uma mensagem de integração mas um registro de uma mensagem desconhecida, ou seja, que não esteja no padrão TOTVSMessage.
Composição das Mensagens
...
As mensagens TOTVS compartilham um conjunto de informações básicas que são utilizadas para identificar o seu tipo, versão e origem.
Informações comuns
...
As mensagens TOTVS possuem um segmento chamado MessageInformation que possui as principais informações utilizadas para identificação e roteamento da mensagem. O quadro abaixo apresenta um exemplo deste segmento:
| Informações | ||||
|---|---|---|---|---|
| ||||
|
Onde:
- MessageInformation - version: Identifica qual a versão daquela mensagem de negócio. Uma mensagem de Item, por exemplo, pode sofrer alterações no decorrer do tempo, sendo que cada uma destas alterações irá afetar esta informação;
- UUID: Identificador único desta mensagem e que não pode ser igual ao UUID de qualquer outra mensagem em qualquer um dos aplicativos participantes da integração;
- Type: Identifica o tipo da mensagem (BusinessMessage, ReceiptMessage ou ResponseMessage);
- Transaction: Identificador do tipo de transação da mensagem. Esta informação será utilizada pelos aplicativos para definir como os dados serão processados no recebimento;
- StandardVersion: Identifica a versão do padrão TOTVS, ou seja, do formato utilizado nas áreas genéricas da mensagem TOTVS. Caso o padrão TOTVS seja alterado, este valor será alterado;
- SourceApplication: Identifica a instancia dos aplicativos TOTVS que gerou a mensagem. Uma instância representa uma instalação/configuração daquele aplicativo/produto. Caso duas instancia do mesmo aplicativo participem da mesma integração, cada um deverá ser identificado de forma única;
- CompanyId: Identificador da empresa que gerou a mensagem. Esta informação é apenas documentacional e não deve ser utilizada para o processamento da mensagem já que não existe garantia da sua existência na mensagem. Quando a informação da empresa for relevante para o negócio, é preciso buscar esta informação do conteúdo da mensagem de negócio;
- Product: Identifica o produto e versão que originou a mensagem. Neste caso, o valor pode ser o igual, mesmo em instâncias diferentes do mesmo aplicativo;
- GeneratedOn: Identifica o timestamp de geração desta mensagem.
BusinessMessage – Event
...
As mensagens de eventos de negócio basicamente descrevem o evento ocorrido, como no exemplo abaixo:
| Informações | ||||
|---|---|---|---|---|
| ||||
|
Onde:
- Entity: Identifica qual foi a entidade de negócio que sofreu o evento;
- Event: Qual foi o evento associado à mensagem (pode ser upsert – inclusão/alteração – ou delete – eliminação);
- Identification/Keys: campos-chave para identificação do registro impactado pela alteração;
- BusinessContent: XML com informações sobre o evento, normalmente contendo todas as informações pertinentes àquela entidade.
BusinessMessage – Request
...
As mensagens de request descrevem qual função se deseja executar e os parâmetros necessários, como no exemplo abaixo:
| Informações | ||||
|---|---|---|---|---|
| ||||
|
Onde:
- Operation: Identifica qual a operação que se deseja executar;
- BusinessContent: XML com informações necessárias para o processamentos, normalmente parâmetros de entrada.
ResponseMessage
...
As mensagens de resposta contém informações sobre o resultado do processamento de uma BusinessMessage, como no exemplo abaixo:
| Informações | ||||
|---|---|---|---|---|
| ||||
|
Onde:
- ReceivedMessage: Segmento com informações sobre a mensagem original (BusinessMessage) que deu origem à esta resposta
- SentBy: Indica qual foi a instancia que gerou a mensagem original;
- UUID: Identificador universal da mensagem de origem;
- MessageContent: XML da mensagem original (opcional).
- ProcessingInformation: Segmento com informações sobre o resultado do processamento
- ProcessedOn: Timestamp de quando a mensagem foi processada pelo destino
- Status: Situação final do processamento (OK ou ERROR)
- ListOfMessages: Lista de mensagens (erro ou aviso) retornadas no processamento.
- ReturnContent: XML com as informações de negócio retornadas no processamento.
ReceiptMessage
...
As informações contidas nas mensagens de recibo são genéricas e focam especificamente nos dados de recebimento da mensagem.
| Informações | ||||
|---|---|---|---|---|
| ||||
|
Onde:
- ReceivedMessage: Segmento com informações sobre a mensagem original (BusinessMessage) que deu origem à esta resposta.
- SentBy: Indica qual foi a instancia que gerou a mensagem original;
- UUID: Identificador universal da mensagem de origem;
- MessageContent: XML da mensagem original (opcional).
- ReceiptData: Segmento com informações sobre o recebimento da mensagem
- ReceivedOn: Timestamp do recebimento da mensagem;
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas