...

1. O que é TOTVS Connector
   
   1. TOTVS Connector Client
      1. Requisitos Mínimos de Instalação
      2. Requisitos de Ambiente / Infraestrutura 
   2. TOTVS Connector Server
   3. Diagrama da arquitetura do TOTVS Connector
2. Integração com aplicações TOTVS e de terceiros
   
   1. Entidades 
      1. TOTVS Connector Server
         1. Client Environment 
         2. SchemaDefinition
      2. TOTVS Connector Client
         1. Product Connection (citar que o usuário do banco cadastrado no product connection, precisa de permissão para inserir, alterar e deletar, criar e alterar triggers e tabelas)
         2. Product Connection Schema (citar que irá criar triggers no momento desse cadastro) 
         3. Modo Standalone
         4. External Event
   2. Mensagens
      1. Fluxo
      2. Estrutura
      3. Como enviar? (rabbit + api do External Event)
3. Integração com TOTVS Carol
   1. Introdução 
   2. Entidades (explicar um pouco mais sobre a integração com a Carol e pensar em um diagrama para ilustrar)
   3. Autenticação
   4. Entidades
      1. Client Environment
      2. CarolUser
      3. CarolConnector
      4. CarolStagingTable
      5. EventDataCarol
   5. Mensagens
      1. Fluxo
      2. Entidade EventDataCarolRequest
      3. Como enviar?
4. Observações
   1. Tempo de envio de dados

...

O TOTVS Connector Server é responsável por receber todos os dados que serão integrados, seja dados de aplicações On Premise / Nuvem Privada (Private Cloud), aplicações SaaS e até aplicações de terceiros. Ele fica em um ambiente exposto na nuvem, já que todos os TOTVS Connector Client devem ser capazes de acessá-lo via requisição HTTP. 

...

A imagem a seguir representa a arquitetura do TOTVS Connector:

02. Integração com aplicações TOTVS e de terceiros

...

Modo Standalone

O Modo Standalone é uma forma de trabalhar apenas no ambiente On Premise. Por exemplo, um cenário onde é necessário integrar dois ou mais produtos que estão em ambientes On Premise / Nuvem Privada (Private Cloud). Para habilitar o modo standalone Modo Standalone é preciso iniciar o TOTVS Connector Client com o standalone ligado. Ao ligar o standalone, o TOTVS Connector Client exigirá uma conexão com uma instância do RabbitMQ, geralmente instalada no mesmo ambiente. Uma vez definido o TOTVS Connector Client como standalone, precisamos habilitar o ProductConnectionSchema como standalone. Depois de tudo configurado, teremos o seguinte comportamento após alguma das seguintes ações:

Um registro é modificado no banco de dados do produto On Premise

Um novo dado é recebido do TOTVS Connector Server

O TOTVS Connector Client irá enviar esse dado para o RabbitMQ, tornando possível qualquer aplicação que estiver conectada a uma fila receber o dado e integrar.

No modo standalone também é possível realizar o caminho inverso, uma aplicação pode enviar um dado para o RabbitMQ, seguindo a estrutura do Schema Definition, dessa forma o TOTVS Connector Client irá receber este dado e enviar para o TOTVS Connector Server (permitindo algum produto Cloud receber o dado) e inserir no banco de dados do produto On Premise.

External Event

Mensagens

Fluxo de Mensagens

Estrutura

Como enviar?

Para fins explicativos, suponha que existe um produto A, com um ambiente On Premise com banco de dados, TOTVS Connector Client e RabbitMQ instalados.

No modo standalone desabilitado, qualquer alteração de registros no banco de dados do produto A, o TOTVS Connector Client será notificado e enviará esses registros para o TOTVS Connector Server, que está no Cloud.

Com o standalone habilitado, o TOTVS Connector Client também enviará os registros do produto A para a instância do RabbitMQ, que também está no On Premise. Com isso, outros produtos que estão no On Premise, por exemplo os produtos B e C, poderão escutar uma fila na instância do RabbitMQ para receber esses mesmos registros. Além disso, é possível os produtos B e C, publicarem os registros no RabbitMQ. Assim, o TOTVS Connector Client irá ser notificado e processar os registros no banco de dados do produto A.

External Event

Um ExternalEvent (ou Evento Externo, em Português), é um endpoint no TOTVS Connector Client que aceita mensagens via requisição HTTP POST, sendo possível enviar dados por aplicações que não possuem integração com o RabbitMQ.
Este endpoint aceita apenas o envio de mensagens. Não há um endpoint que seja possível recuperar mensagens. As mensagens só são disponibilizadas no RabbitMQ via modo standalone.

Database Structure

Por causa dos vários objetos de banco de dados necessários para o funcionamento do TOTVS Connector Client, existe uma funcionalidade que checa de tempos em tempos a consistência desses objetos.

Cada tabela do SchemaDefinition criará uma trigger e duas colunas no banco de dados do produto On Premise. Caso algum desses objetos sofrer alterações indevidas, o TOTVS Connector Client demonstrará essa falta de conformidade, facilitando verificações de problemas no funcionamento desejado.

Mensagens

Fluxo

A seguir é apresentado o fluxo de mensagens das aplicações OnPremise / Nuvem Privada e Cloud, através do TOTVS Connector Server e Totvs Connector Client:

Image Added

Entidade EventData

A entidade EventData é utilizada para encapsular os dados para enviar ao TOTVS Connector Server, destinada às aplicações On Premise e Cloud.

Atributos

• O atributo originApp é o nome da origem do registro, ou seja, o nome do produto;
• O atributo appVersion é a versão do produto;
• O atributo schemaName é o nome da entidade do SchemaDefinition;
• O atributo schemaVersion é a versão da entidade do SchemaDefinition;
• O atributo action é a ação que será executada no banco de dados, podendo ser INSERT, UPDATE ou DELETE.
• O atributo data é o registro no formato JSON, definido pelo SchemaDefinition.
• O atributo createdAt é a data de criação da entidade EventData.
• O atributo token é o atributo gerado pela entidade ClientEnvironment;

{
    "originApp": "nome_do_produto",
    "appVersion": "1",
    "schemaName": "PESSOA",
    "schemaVersion": "1",
    "action": "INSERT",
    "data": { },
    "createdAt": "2000-01-01T00:00:00.335846Z",
    "token": "TOKEN_DO_CLIENTE_QUE_GEROU_O_DADO"
}

Como enviar?

Para enviar os dados via mensageria para o TOTVS Connector Server, deve-se enviar a entidade TOTVSMessage<T>. A entidade TOTVSMessage é uma classe da biblioteca TJF, que encapsula a mensagem a ser enviada por mensageria.

O tipo genérico T é a entidade a ser encapsulada que, no nosso caso, será a EventData. Portanto, para enviar uma mensagem para o TOTVS Connector Server, deverá mandar um objeto TOTVSMessage<EventData>.

Atributos

• O atributo header é a classe TOTVSHeader, também da biblioteca TJF, que será enviada no header da mensagem. 
  • O atributo type é o nome da StagingTable a ser enviada.
  • O atributo generatedOn é a data que está enviado os dados
  • O atributo locale é a localização utilizada no cliente.
• O Atributo content é o tipo genérico T. No nosso caso, será a entidade EventData.

Estrutura Final TOTVSMessage<EventData>

Segue abaixo um exemplo de uma mensagem com um schema fictício chamado PESSOA:

{
   "header": {
      "type": "atributo_name_do_schemaDefinition",
      "generatedOn": "2000-01-01T00:00:00.000000Z",
      "locale": "pt_BR" 
   },
   "content": {

      "originApp": "PESSOAS",
      "appVersion": "1",
      "schemaName": "PESSOA",
      "schemaVersion": "1",
      "action": "INSERT",
      "data": {
          "id": {
              "id": 1
          },
          "rg": "10.10.10.10",
          "cpf": "100.100.100/10",
          "nome": "FULANO",
          "originId": "HASH_GERADO_PELO_APP_DE_ORIGEM",
          "tipoSangue": "O-",
          "dataNascimento": "1950-01-01T00:00:00+00:00"
      },
      "createdAt": "2000-01-01T00:00:00.335846Z",
      "token": "TOKEN_DO_CLIENTE_QUE_GEROU_O_DADO"
 }
}

03. Integração com TOTVS Carol

...

A entidade CarolUser são informações de login da plataforma Carol que deve ser cadastrada no TOTVS Connector Server. 

Atributos

• O atributo "organizationSubdomain" corresponde ao atributo "orgDomain" da TOTVS Carol;

• O atributo "subdomain" corresponde ao atributo "subdomain" da TOTVS Carol, que se refere ao ambiente (tenant) que está se autenticando;

• Os atributos "username" e "password" são informações do seu login na TOTVS Carol;

...

Portanto, CarolConnector é a relação do connector (connectorId) com o connector token gerado para esse mesmo connector na TOTVS Carol.

Atributos

• O atributo connectorId é o id do connector na TOTVS Carol;

• O atributo connectorToken é o identificador gerado para o connectorId na TOTVS Carol;

...

A entidade CarolStagingTable possui dois atributos similares, que representam abstrações diferentes: name e stagingTableName. A diferenciação de cada atributo será explicado a seguir.

Atributos

• O atributo stagingTableName representa exatamente o nome da StagingTable na TOTVS Carol. Por exemplo, se na TOTVS Carol contém uma StagingTable com o nome "fazenda", o atributo stagingTableName deverá ser, exatamente, "fazenda";

• O atributo name representa um "apelido" para o TOTVS Connector Server diferenciar dos nomes das StagingTable. Por exemplo, na TOTVS Carol contém uma StagingTable chamada "inspecao" e no TOTVS Connector Server, contém duas CarolStagingTable que apontam para a StagingTable "inspecao" na TOTVS Carol. Para diferenciar as duas CarolStagingTable, utiliza-se o atributo name.

• O atributo description representa uma descrição sobre a CarolStagingTable;

...

A entidade EventDataCarolRequest será explicada no tópico a seguir.

Envio de dados

Fluxo

O diagrama a seguir apresenta o fluxo de dados para enviar à TOTVS Carol:

...

Entidade EventDataCarolRequest

A entidade EventDataCarolRequest é utilizada para encapsular os dados para enviar ao TOTVS Connector Server, destinada à TOTVS Carol.

Atributos

• O atributo environmentToken é o token gerado na entidade Client Environment;

• O atributo stagingTableName é exatamente o apelido (atributo name) cadastrada na entidade CarolStagingTable;

• O atributo originApp é o nome do produto que está enviando os dados (produto de origem);

• O atributo dataList é uma lista de objetos que será enviada para a StagingTable na TOTVS Carol, ou seja, os objetos são as próprias representações da StagingTable;

...

O tipo genérico T é a entidade a ser encapsulada que, no nosso caso, será a EventDataCarolRequest. Portanto, para enviar uma mensagem para o TOTVS Connector Server, destinada à Carol, deverá mandar um objeto TOTVSMessage<EventDataCarolRequest>.

Atributos

• O atributo header é a classe TOTVSHeader, também da biblioteca TJF, que será enviada no header da mensagem. 
  • O atributo type é o nome da StagingTable a ser enviada.
  • O atributo generatedOn é a data que está enviado os dados
  • O atributo locale é a localização utilizada no cliente.
• O Atributo content é o tipo genérico T. No nosso caso, será a entidade EventDataCarolRequest.

...