...

1. O que é TOTVS Connector?
   
   1. TOTVS Connector Client
      1. Requisitos Mínimos mínimos de InstalaçãoiInstalação
      2. Requisitos de Ambiente / Infraestrutura infraestrutura e ambiente 
   2. TOTVS Connector Server
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
         2. Product Connection Schema
         3. Modo Standalone
         4. External Event
   2. Mensagens
      1. Fluxo
      2. Entidade EventData
      3. Como enviar?
3. Integração com TOTVS Carol
   1. Introdução Contextualização
   2. Entidades
   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 é uma ferramenta/plataforma que permite possibilita 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.

...

e plataformas (TOTVS e não-TOTVS), independente da forma de distribuição de tal solução. Desta forma, utiliza-se o TOTVS Connector para integrar dados, por exemplo, entre aplicações OnPremise, Cloud Privada/Pública e plataforma SaaS (TOTVS Apps).

Funcionamento geral

Por meio de dois componentes dispostos em contextos/ambientes diferentesdistintos, é possível garantir que uma aplicação On Premise ficar OnPremise fique sincronizada com um uma aplicação em Cloud. Um desses /SaaS. Para viabilizar este cenário, um dos componentes é o TOTVS Connector Client, ferramenta que é instalado no ambiente On Premise instalada em ambiente OnPremise/Nuvem Privada (Private Cloud). O outro Outro componente é , o TOTVS Connector Server, gerenciado pela TOTVS, é responsável de receber todo o fluxo de dados. Portanto, o cliente deverá instalar e configurar , assim como expor APIs e se comunicar com as demais soluções em Cloud/SaaS. Em ambiente do cliente (OnPremise/Cloud), deve ser instalado e configurado apenas o TOTVS Connector Client.

TOTVS Connector Client

É a parte o componente responsável por ler os dados das aplicações On PremisesOnPremise, seja sejam aplicações TOTVS ou de terceiros. Ele  A instalação é instalado realizada em uma máquina que possa de forma a conecta-se conectar com o banco de dados do produto On Premise OnPremise/Nuvem Privada (Private Cloud), podendo este ser Oracle, Microsoft SQL Server e PostgreSQL. O TOTVS Connector Client precisa de uma instância do PostgreSQL e, dependendo da configuração standalone (explicação , mencionado no tópico 2 . (Integração com produtos TOTVS e externos), uma instância do RabbitMQ (para comunicação via mensageria AMQP).

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. 4 GB RAM;

• Processador: Quad Core 1.8 GHZ ou superior.;

• Espaço em Disco: Espaço em disco de 40GB.40 GB RAM;

• Ferramentas/Recursos principais: Docker (containers Linux) e Portainer (opcional, para monitoramento/gestão de ambientes baseados em Docker/containers).;

Requisitos de

...

infraestrutura e ambiente

• 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:
• https://tcserver-supplyagro.totvs.app/
• https://docker.totvs.io/
• https://totvstfs.visualstudio.com/
• http://agrodata-gateway.agro.totvs.io:8092 
• http://mdm.agro.totvs.io:8090 
• https://discordapp.comcom

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 originados em aplicações OnPremise/Nuvem Privada (Private Cloud), aplicações SaaS e até não-TOTVS, por meio de aplicações de terceiros. Ele Este componente fica em um ambiente exposto na nuvem, já uma vez que todos os demais TOTVS Connector Client devem ser capazes de acessá-lo via requisição Internet/HTTP. 

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

Entidades

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

...

A entidade Client Environment representa o ambiente do cliente e é necessário realizar seu cadastro para o correto funcionamento do TOTVS Connector Client e , assim como para a integração da TOTVS Carol. Ao cadastrar um novo ambiente (Client Environment), a entidade irá gerar gerará um token para o este ambiente. Esse O token é  gerado representa a identificação do cliente cliente/ambiente que será utilizado para enviar os dados. Além disso, o token deve ser informado na instalação do TOTVS Connector Client, pois ele a plataforma TOTVS Connector verifica se o token é válido ou não. As aplicações Cloud/SaaS (Cloud) também deve enviar esse token nas mensagens para o TOTVS Connector Server.

...

SchemaDefitinion

O SchemaDefinition é uma a estrutura de dados que o mapeamento estrutural e de metadados de persistência (por exemplo, nomes de Tabela e Coluna). Para isto, a entidade SchemaDefinition possui as informações da tabela de origem do dado e como ele deve ser convertido se dá a conversão para ser enviado ao TOTVS Connector Server. A gestão do SchemaDefinition é realizada apenas no TOTVS Connector Server. Uma vez publicado o SchemaDefinition, gerará será gerada uma nova versão do SchemaDefinition. Assim, todos os TOTVS Connector Client irão sincronizar os  também são responsáveis pelo processo de sincronismo de novos SchemaDefinition.

A estrutura do SchemaDefinition é representada pelo JSON abaixo:

{
    "id": "Identificador: UUID",
    "version": "Versão",
    "name": "Nome",
    "description": "Descrição",
    "status": "Status: PRODUCTION ou DEVELOPMENT",
    "createdAt": "Data de criação",
    "updatedAt": "Data da última atualização",
    "attributes": [ -- Array que contém objetos Schema Attributes
        {
            "name": "Nome do atributo",
            "required": true -- se o atributo é obrigatório,
            "type": "Tipo: ELEMENT ou ARRAY",
            "entityPrimaryKey": false -- se o atributo é a primary key da entidade,
            "foreignKeyType": "Tipo de chave estrangeira: NONE, PARENT_SCHEMA ou OTHER_SCHEMA",
            "attributeProducts": -- Array de objetos Schema Attribute Product [
                {
                    "productName": "Nome do produto",
                    "tableName": "Nome da tabela",
                    "foreignTableName": "Nome da tabela de referência a chave estrangeira",
                    "columns": -- Array de objetos Schema Attribute Columns [
                        {
                            "columnName": "Nome da coluna",
                            "parentColumnName": "Nome da coluna na tabela da chave estrangeira",
                            "type": "Tipo da coluna: STRING, NUMBER, DATE e CLOB",
                            "label": "Label da coluna quando o atributo for Primary Key, Parent Schema ou Other Schema"
                        }
                    ]
                }
            ],
            "children": -- Array de objetos Schema Attributes quando o type for ARRAY []
        }
    ]
}

Segue abaixo um novo exemplo de SchemaDefinition:

...

A entidade ProductConnection representa as informações da conexão do banco de dados do produto , que será integrado. O TOTVS Connector Client suporta conexão conexões com vários bancos de dados ao mesmo tempo, trabalhando com múltiplos ProductConnectionpossibilitando que uma mesma instalação de TOTVS Connector Client monitore e integre dados a partir de múltiplos ProductConnection (por exemplo, Oracle, Microsoft SQL Server e PostgreSQL). Cada banco de dados deve possuir uma tabela chamada TCC_PRODUCT_METADATA, onde deve existir um registro com o  responsável pelo controle de nome do produto (NAME) e a versão do produto que está sendo monitorado/integrado (VERSION). Essas Estas informações serão são necessárias para relacionar o as entidades ProductConnection com o e SchemaDefinition.

A estrutura da tabela TCC_PRODUCT_METADATA deve possuir duas colunas de texto: NAME e VERSION.

Os bancos de dados suportados são Oracle (11G 11g e 12C12c), PostgreSQL e Microsoft SQL Server e PostgreSQL.

Atributos

• O atributo id é o identificador único do produto;
• O atributo productName é o nome do produto;
• O atributo productVersion é a versão atual do produto;
• O atributo url é o endereço de conexão com o banco de dados. Para cada baco banco de dados é , utiliza-se um endereço diferente. AbaixoNesta documentação, também são apresentados os diferentes endereção endereços para cada banco de dados;
• O atributo username é o usuário do banco de dados;
• O atributo password é a senha do usuário do banco de dados;
• O atributo dataBaseType é o tipo do banco de dados. Abaixo, são apresentados os tipos de cada banco de dados;
• O atributo enabled representa se a conexão está habilitada ou desabilitada;

...

O usuário do banco de dados deve ter permissão de criar, alterar remover registros, colunas e triggers nas tabelas.

ProductConnection para conexões com o banco de dados SQL dados Microsoft SQL Server:

{
    "id": "68eaa1a2-aedb-4ba9-9015-a01a31bead89",
    "productName": "PIMS",
    "productVersion": "12.1.27",
    "url": "jdbc:jtds:sqlserver://localhost:1433/PIMS",
    "username": "PIMS",
    "password": "PIMS",
    "dataBaseType": "MSSQLSERVER",
    "enabled": true
}

ProductConnection com o  para conexões com banco de dados Oracle 11G11g:

{
    "id": "68eaa1a2-aedb-4ba9-9015-a01a31bead89",
    "productName": "PIMS",
    "productVersion": "12.1.27",
    "url": "jdbc:oracle:thin:@localhost:1521:PIMS",
    "username": "PIMS",
    "password": "PIMS",
    "dataBaseType": "ORACLE11G",
    "enabled": true
}

ProductConnection para conexões com o banco de dados PostgreSQL:

...

A entidade ProducConnectionSchema representa a relação entre as entidades ProductConnection e SchemaDefinition.  Essa Esta relação significa que uma determinada conexão integrará determinados SchemaDefinition. Por exemplo: a conexão A conexão A possui integração com os schemas Schema_A e Schema_B, e a conexão B, com os schemas Schema_B e Schema_C. Portanto, é possível possuir configurar duas conexões com diferentes SchemaDefinition. A entidade SchemaDefinition é cadastrada no TOTVS Connector Server e a própria aplicação TOTVS Connector Client encarrega-se encarrega de sincronizar, automaticamente, essa esta entidade. 

Após realizar o relacionamento, o TOTVS Connector Client iniciará o monitoramento das tabelas definidas no SchemaDefinition. Assim que houver qualquer alteração em qualquer registro das tabela integradasem um ou mais registros das tabelas monitoradas, o TOTVS Connector Client será notificado e processará esse registro e enviarã para o este registro, enviando-o à plataforma TOTVS Connector Server.

Atributos

• O atributo id é o identificador do registro;
• O atributo idProductConnection é o id do registro da entidade ProducConnection;
• O atributo idSchemaDefinition é o id do registro da entidade SchemaDefinition;
• O atributo versionSchemaDefinition é a versão do SchemaDefinition relacionado. Esse Este atributo não precisa ser passado para criar o relacionamento. Ele é preenchido Preenchido automaticamente;
• O atributo nameSchemaDefinition é o nome do SchemaDefinition relacionado. Esse Este atributo não precisa ser passado para criar o relacionamento. Ele é preenchido Preenchido automaticamente;
• O atributo enableStandalone será explicado no tópico Modo Standalone, apresentado a seguir;

...

O Modo Standalone é uma forma de trabalhar apenas no ambiente On PremiseOnPremise. Por exemplo, integrar dois ou mais produtos que estão em ambientes On Premise OnPremise/Nuvem Privada (Private Cloud). Para habilitar o Modo Standalone é preciso iniciar inicializar o TOTVS Connector Client com o standalone ligado. Ao ligar habilitar o standalone, o TOTVS Connector Client exigirá uma conexão com uma instância do RabbitMQ, geralmente instalada, por padrão, no mesmo ambiente. Uma vez definido o TOTVS Connector Client como standalone, precisamos deve-se habilitar o ProductConnectionSchema como standalone. 

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

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

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

A seguirNa representação seguinte, é apresentado o diagrama do Modo Standalone:

...

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 Importante mencionar que não há um endpoint que seja possível recuperar mensagens. As mensagens só somente são disponibilizadas no RabbitMQ (local) via modo standalone.

Database Structure

Por causa dos vários Devido à necessidade de existência de objetos de banco de dados necessários para o correto funcionamento do TOTVS Connector Client, existe uma funcionalidade que checa/verifica, de tempos em tempos, a consistência ou integridade desses objetos.

Cada tabela do SchemaDefinition criará  origina a criação de uma trigger e de duas colunas (gerenciais) no banco de dados do produto On PremiseOnPremise. Caso algum desses objetos sofrer sofra alterações indevidas, o TOTVS Connector Client demonstrará essa  validará e exibirá esta falta de conformidade/integridade, facilitando verificações de problemas no funcionamento desejado.

Mensagens

Fluxo

A seguir é apresentado o fluxo Fluxo de mensagens das aplicações On Premise OnPremise/Nuvem Privada (Private Cloud) e Cloud, através por meio do TOTVS Connector Server e Totvs Connector Client:

...

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

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;

...

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á acontexto atual, representa o EventData. Portanto, para enviar uma mensagem para o TOTVS Connector Server, deverá mandar ser enviado um objeto com tipagem 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 atributo content é o tipo genérico T. No nosso caso, será a entidade EventData.;

Estrutura

...

final TOTVSMessage<EventData>

Segue abaixo um exemplo Exemplo de uma mensagem com um schema fictício chamado que define 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

...

Contextualização

A TOTVS Carol é uma plataforma de dados com e inteligência artificial da TOTVS, podendo-se aplicar todas as funcionalidades do de um 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 integridade dos dados e centralizar os dados de sua aplicação. Além disso, também possui a capacidade de desenvolver aplicativos e implantá-los os implantar na plataforma e utilizar a Assistente Carol, por meio de Carol Apps e Carol Assistant. Para saber mais sobre a plataforma Carol, você pode-se acessar a sua documentação.

O TOTVS Connector possui integração com a TOTVS Carol, podendo levar seus possibilitando a disponibilização de dados de aplicações On Premise OnPremise 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 à a plataforma Carol. Neste tópico, são explicados os processo de configuração e uso do TOTVS Connector Server junto à plataforma TOTVS Carol.

Autenticação

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

Entidades

Client Envrionment

Como já explicado no mencionado anteriormente (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  contempla as informações de autenticação/login da plataforma Carol que e deve ser cadastrada no TOTVS Connector Server. 

...

A entidade CarolConnector representa quais connectorsConnectors (da TOTVS Carol) , que o usuário possui no ambiente, e os assim como seus connector tokensConnector Tokens. Na TOTVS Carol é possível gerar um connector tokenCarol, pode-se gerar um Connector Token para cada connector, Connector e são utilizados para enviar como identificação do para o processo de autenticação/identificação de usuário para autorização nas requisições das APIs.

ATENÇÃO!

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

Portanto, CarolConnector é a relação do connectorConnector (connectorId) com o connector token Connector Token gerado para esse mesmo connector 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 exatamente o nome da StagingTable na TOTVS Carol. Por exemplo, se na TOTVS Carol contém existe 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

...

podem existir duas CarolStagingTable no TOTVS Connector Server apontando para a mesma StagingTable na TOTVS Carol?

Pois podem Isto pode ser configurado de forma a conter duas ou mais formas de enviar responsáveis pelo envio dados para o TOTVS Connector Server. Por exemplo, dois produtos diferentes de um mesmo cliente enviando para a mesma StagingTable na TOTVS Carol.

...

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 enviar o atributo stagingTableName na mensagem.

...

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 validará as informações e direcionar para TOTVS Carol.

...

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 enviar um objeto TOTVSMessage<EventDataCarolRequest>.

...

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

...

Como as aplicações estão em servidores diferentes, TOTVS Connector Client no On Premise OnPremise/Nuvem Privada (Private Cloud), TOTVS Connector Server na nuvem e as aplicações de terceiros podendo estar tanto na nuvem quanto On PremiseOnPremise, é possível acontecer atrasos e lentidões no envio dos dados, devido à conexão utilizada. 

...