CONTENT

O que é TOTVS Connector
1. TOTVS Connector Server
2. TOTVS Connector Client
  1. Requisitos Mínimos de Instalação
  2. Requisitos de Ambiente / Infraestrutura
3. Diagrama da arquitetura do TOTVS Connector (Tentar generalizar para atender o da Carol, se não, criar 2 diagramas e colocar nos respectivos tópicos abaixo)
Integração com aplicações TOTVS e de terceiros
1. Introdução (explicar um pouco mais sobre as integrações de produtos internos e externos, pensar em um diagrama para ilustrar)
2. Entidades (Cadastros ?)
  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
3. Mensagens
  1. Fluxo das mensagens
  2. Estrutura
  3. Como enviar? (rabbit + api do External Event)
Integração com TOTVS Carol (Cadastros ?)
1. Entidades (explicar um pouco mais sobre a integração com a Carol e pensar em um diagrama para ilustrar)
2. Autenticação
3. Entidades
  1. Client Environment
  2. CarolUser
  3. CarolConnector
  4. CarolStagingTable
  5. EventDataCarol
4. Mensagens
  1. Fluxo
  2. Estrutura das mensagens (EventDataCarolRequest)
  3. Como enviar? (rabbit + endpoint)
Observações importantes
1. Tempo de envio das mensagens (explciar que pode demorar por conta da conexão / processamento)

01. O que é TOTVS Connector?

O TOTVS Connector é uma ferramenta que permite a integração entre softwares, não importando a forma de distribuição do software, ou seja, integra dados entre aplicações Cloud e aplicações On Premise e vice-versa.

Como assim?

Por meio de dois componentes dispostos em ambientes diferentes, é possível uma aplicação On Premise ficar sincronizada com um aplicação em Cloud. Um desses componentes é o TOTVS Connector Client, que é instalado no ambiente On Premise / Private Cloud. O outro componente é o TOTVS Connector Server, gerenciado pela TOTVS, é responsável de receber todo fluxo de dados. Portanto, o cliente deverá instalar e configurar apenas o TOTVS Connector Client.

TOTVS Connector Client

É a parte responsável por ler os dados das aplicações On Premises, seja aplicações TOTVS ou de terceiros. Ele é instalado em uma máquina que possa se conectar com o banco de dados do produto On Premise / Private Cloud. O TOTVS Connector Client precisa de uma instância do PostgreSQL e, dependendo da configuração standalone (explicação no tópico 2. Integração com produtos TOTVS e externos), uma instância do RabbitMQ.

Requisitos Mínimos de Instalação

Caso a sua máquina não atinja os requisitos mínimos abaixo, entre em contato conosco para avaliar outras possibilidades:

Sugestão do sistema operacional: Debian ou CentOS GNU/Linux 10 (buster) ou distribuição Linux 64 bits.
Memória RAM: 4GB.
Processador: Quad Core 1.8 GHZ ou superior.
Espaço em Disco: Espaço em disco de 40GB.
Ferramentas/Recursos principais: Docker (containers Linux) e Portainer (opcional, para monitoramento/gestão de ambientes baseados em Docker/containers).

Requisitos de Ambiente / Infraestrutura

Comunicação entre os ambientes do TOTVS Connector Client e bases de dados de outros produtos (por exemplo, TOTVS Agro Bioenergia ou TOTVS Agro Multicultivo, com compatibilidade com Oracle ou SQL Server, e PostgreSQL).
Caso exista bloqueio/restrição na rede, baseado em whitelist, adicionar os hosts na máquina em que o TOTVS Connector Client será instalado:

TOTVS Connector Server

O TOTVS Connector Server é responsável por receber todos os dados que serão integrados, seja dados de aplicações On Premise / 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

Introdução

Entidades

Este tópico irá apresentar as entidades de cadastros utilizados no TOTVS Connector Server e TOTVS Connector Client.

TOTVS Connector Server

Client Environment

A entidade Client Environment representa o ambiente no cliente e é necessário realizar seu cadastro para o funcionamento do TOTVS Connector Client e para a integração da TOTVS Carol. Ao cadastrar um ambiente (Client Environment), a entidade irá gerar um token para o ambiente. Esse token é a identificação do cliente, ou seja, todo dado trafegado deve possuir um token do cliente. Além disso, o token deve ser informado na instalação do TOTVS Connector Client, pois ele verifica se o token é válido ou não. As aplicações SaaS (Cloud) também deve enviar esse token nas mensagens para o TOTVS Connector Server.

SchemaDefitinion

TOTVS Connector Client

Product Connection

Product Connection Schema

Modo Standalone

External Event

Mensagens

Fluxo de Mensagens

Estrutura

Como enviar?

03. Integração com TOTVS Carol

Introdução

A TOTVS Carol é uma plataforma de dados com inteligência artificial, podendo aplicar todas as funcionalidades do MDM (Master Data Management, ou Gestão de Dados Mestre, em Português), como por exemplo: capacidade de receber dados de qualquer fonte, garantir a qualidade dos dados e centralizar os dados de sua aplicação. Além disso, também possui a capacidade de desenvolver aplicativos e implantá-los na plataforma e utilizar a Assistente Carol. Para saber mais sobre a plataforma, você pode acessar a sua documentação.

O TOTVS Connector possui integração com a TOTVS Carol, podendo levar seus dados de aplicações On Premise ou SaaS para dentro da plataforma, podendo aumentar a qualidade de seus dados e gerar gráficos a partir deles. Nesse tópico, será explicado como configurar o TOTVS Connector Server para enviar dados à TOTVS Carol.

Autenticação

Para enviar dados à TOTVS Carol é preciso realizar a autenticação do usuário, que pode ser feita de duas formas: pelo accessToken ou pelo connectorToken. Para o TOTVS Connector Server, a autenticação será feita pelo connectorToken. Portanto, é preciso gerar o connectorToken na plataforma. Após gerado o connectorToken, será utilizado no cadastro da entidade CarolConnector, explicado nos tópicos a seguir.

Entidades

Client Envrionment

Como já explicado no tópico 2. Integrações com aplicações TOTVS e terceiros, a entidade Client Environment representa o ambiente, e o token gerado por ele, representa a identificação do cliente. Assim, o token é utilizado para identificar as mensagens do cliente e direcionar para a TOTVS Carol.

Carol User

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;

Informações

title	Estrutura de exemplo da entidade CarolUser

{
"organizationSubdomain": "ambienteteste",
"password": "senha_carol",
"subdomain": "clienteteste",
"username": "usuario_carol"
}

Carol Connector

A entidade CarolConnector representa quais connectors (da TOTVS Carol), que o usuário possui no ambiente, e os seus connector tokens. Na TOTVS Carol é possível gerar um connector token para cada connector, e são utilizados para enviar como identificação do usuário para autorização nas requisições das APIs.

ATENÇÃO!

O connector token é diferente do token gerado na entidade Client Environment. O connector token é gerado na TOTVS Carol para um connector e é utilizado na identificação do usuário na TOTVS Carol para o mesmo connector. Diferentes connectors possuem diferentes connectorToken para o mesmo usuário. E o token da entidade Client Environment é utilizado para identificação no TOTVS Connector.

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;

Informações

title	Estrutura de exmeplo da entidade CarolConnector

{
  "connectorId": "1257404c3f7c7a1547c00f0c833e357b",
  "connectorToken": "aa3ee9f21fc09602580e0357125e0d02"
}

Carol Staging Table

A entidade CarolStagingTable representa uma StagingTable na TOTVS Carol.

ATENÇÃO!

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;

Mas por que pode conter duas CarolStagingTable no TOTVS Connector Server apontando para a mesma StagingTable na TOTVS Carol?

Pois podem conter duas ou mais formas de enviar dados para o TOTVS Connector Server. Por exemplo, dois produtos diferentes de um mesmo cliente enviando para a mesma StagingTable na TOTVS Carol.

Informações

title	Estrutura de exemplo da entidade CarolStagingTable

{
  "carolConnectorId": "b26a732f-d2fc-47c8-9e0d-545d6e3ef674",
  "stagingTableName": "fazenda",
  "description": "Exemplo de CarolStagingTable, que representa uma StagingTable na TOTVS Carol",
  "name": "apelido_para_fazenda"
}

IMPORTANTE!

Quando enviar uma mensagem para o TOTVS Connector Server, destinada à TOTVS Carol, a entidade EventDataCarolRequest deverá conter, exatamente, o valor do atributo name. Portanto, não deverá mandar o atributo stagingTableName na mensagem.

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

Envio de dados

Fluxo

Diagrama mostrando a mensagem saindo do produto e chegando na totvs carol: produto (interno e externo) → tc-server → totvs carol

Entidade EventDataCarolRequest

A entidade EventDataCarolRequest é utilizada para encapsular os dados para enviar ao TOTVS Connector Server.

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;

Informações

title	Estrutura de exemplo da entidade EventDataCarolRequest

{
  "environmentToken": "dac9b5163b31479bd9a2151b6f2fe2bbb3d48cf110911d36c062995994598c6e",
  "stagingTableName": "atributo_name_da_entidade_CarolStagingTable",
  "originApp": "app_de_origem",
  "dataList": [
    {}
  ]
}

Como enviar?

A seguir, são explicados os métodos de envio de dados para o TOTVS Connector Server, direcionados à TOTVS Carol.

IMPORTANTE!

Como os envios de dados são feitos de forma assíncrona, pode-se levar algum tempo até os dados serem processados e enviados.

Via Requisição HTTP

Para enviar os dados via requisição HTTP, utiliza-se o endpoint do TOTVS Connector Server: /v1/environment/carol/eventsDataCarol

No corpo da requisição, passa-se uma lista de EventDataCarolRequest. Após o envio de dados via HTTP, o TOTVS Connector Server irá validar as informações e direcionar para TOTVS Carol.

Via Mensageria

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

Informações

title	Estrutua de exemplo da entidade TOTVSMessage

{

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

"content": { }

}

Estrutura Final TOTVSMessage<EventDataCarolRequest>

Informações

title	Exemplo da estrutura final de envio via mensageria

{
   "header": {
      "type": "atributo_name_da_entidade_CarolStagingTable",
      "generatedOn": "2000-01-01T00:00:00.000000Z",
      "locale": "pt_BR" 
   },
   "content": {
      "environmentToken": "dac9b5163b31479bd9a2151b6f2fe2bbb3d48cf110911d36c062995994598c6e",
      "stagingTableName": "atributo_name_da_entidade_CarolStagingTable",
      "originApp": "app_de_origem",
      "dataList": [
         {}
      ]
   }
}

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 25

Nova versão 26

Chave

CONTENT

01. O que é TOTVS Connector?

Como assim?

TOTVS Connector Client

Requisitos Mínimos de Instalação

Requisitos de Ambiente / Infraestrutura

TOTVS Connector Server

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

Introdução

Entidades

TOTVS Connector Server

Client Environment

SchemaDefitinion

TOTVS Connector Client

Product Connection

Product Connection Schema

Modo Standalone

External Event

Mensagens

Fluxo de Mensagens

Estrutura

Como enviar?

03. Integração com TOTVS Carol

Introdução

Autenticação

Entidades

Client Envrionment

Carol User

Atributos

Carol Connector

ATENÇÃO!

Atributos

Carol Staging Table

ATENÇÃO!

Atributos

Mas por que pode conter duas CarolStagingTable no TOTVS Connector Server apontando para a mesma StagingTable na TOTVS Carol?

IMPORTANTE!

Envio de dados

Fluxo

Entidade EventDataCarolRequest

Atributos

Como enviar?

IMPORTANTE!

Via Requisição HTTP

Atributos

Estrutura Final TOTVSMessage<EventDataCarolRequest>

04. Observações

Tempo de processamento das mensagens