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.
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.
É 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.
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).
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:
Este tópico irá apresentar as entidades de cadastros utilizados no TOTVS Connector Server e TOTVS Connector Client.
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.
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.
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.
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.
A entidade CarolUser são informações de login da plataforma Carol que deve ser cadastrada no TOTVS Connector Server.
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;
| { "organizationSubdomain": "ambienteteste", "password": "senha_carol", "subdomain": "clienteteste", "username": "usuario_carol" } |
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.
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.
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 representa uma StagingTable 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.
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;
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.
|
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.
Diagrama mostrando a mensagem saindo do produto e chegando na totvs carol: produto (interno e externo) → tc-server → totvs carol
A entidade EventDataCarolRequest é utilizada para encapsular os dados para enviar ao TOTVS Connector Server.
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;
|
A seguir, são explicados os métodos de envio de dados para o TOTVS Connector Server, direcionados à TOTVS Carol.
Como os envios de dados são feitos de forma assíncrona, pode-se levar algum tempo até os dados serem processados e enviados.
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>.
|
{ |