Conteúdo

...

1. O que é TOTVS Agro Connector?
   
   1. TOTVS Agro Connector Client
   2. TOTVS Agro Connector Server
2. Integração com aplicações TOTVS e de terceiros
   
   1. Entidades 
      1. TOTVS Agro Connector Server
         1. Client
      1. Requisitos Mínimos de Instalação
      2. Requisitos de Ambiente / Infraestrutura 
   2. 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)
3. 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)
4. 1. 1. 1. Environment 
         2. SchemaDefinition
      2. TOTVS Agro Connector Client
         1. Product Connection
         2. Product Connection Schema
         3. Métodos de Publicação
         4. Modo Standalone
         5. Publicação Remota
         6. External Event
   2. Mensagens
      1. Fluxo Geral
      2. Fluxo de envio e recebimento de mensagens do TOTVS Agro Connector Server
      3. Entidade EventData
      4. Como enviar?
5. Integração com TOTVS Carol
   1. Contextualização
   2. Entidades
   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 (Entidade EventDataCarolRequest)
      3. Como enviar?(rabbit + endpoint)
6. Observações importantes
   1. Tempo de envio das mensagens (explciar que pode demorar por conta da conexão / processamento)de dados

01. O que é TOTVS Agro Connector?

O TOTVS Agro 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 Agro 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 Agro Connector Client, ferramenta que é instalado no ambiente On Premise / instalada em ambiente OnPremise/Nuvem Privada (Private Cloud). O outro Outro componente é , o TOTVS Agro 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 Agro Connector Client.

TOTVS Agro 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 conectar-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 Agro 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.

• 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:
• 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.com

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;

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 de 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 cliente na TOTVS Carol para o MESMO connector. Diferentes connectors possuem diferentes connectorToken para o mesmo usuário. Enquanto que 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.

Atributos

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

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

Carol Staging Table

Event Data Carol

Mensagens

Fluxo

Estrutura das mensagens

Como enviar?

04. Observações

TOTVS Agro Connector Server

O TOTVS Agro Connector Server é responsável por receber os dados que serão integrados, originados em aplicações OnPremise/Nuvem Privada (Private Cloud), aplicações SaaS e até não-TOTVS, por meio de aplicações de terceiros. Este componente fica em um ambiente exposto na nuvem, uma vez que todos os demais TOTVS Agro Connector Client devem ser capazes de acessá-lo via requisição Internet/HTTP. 

Image Added

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

Entidades

Este tópico apresenta e descreve as entidades utilizadas no TOTVS Agro Connector Server e TOTVS Agro Connector Client.

TOTVS Agro Connector Server

Client Environment

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

SchemaDefitinion

O SchemaDefinition é 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 se dá a conversão para ser enviado ao TOTVS Agro Connector Server. A gestão do SchemaDefinition é realizada apenas no TOTVS Agro Connector Server. Uma vez publicado o SchemaDefinition, será gerada uma nova versão do SchemaDefinition. Assim, todos os TOTVS Agro Connector Client também são responsáveis pelo processo de sincronismo de novos SchemaDefinition.

A estrutura do SchemaDefinition é representada pelo JSON:

{
    "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 novo exemplo de SchemaDefinition:

{
    "id": "a126a79d-693c-4d2d-bbbd-a3cbff1abfc9",
    "version": "12.1.27",
    "name": "Instancia",
    "description": "Instancia",
    "status": "PRODUCTION",
    "createdAt": null,
    "updatedAt": null,
    "attributes": [
        {
            "name": "nome",
            "required": true,
            "type": "ELEMENT",
            "entityPrimaryKey": false,
            "foreignKeyType": "NONE",
            "attributeProducts": [
                {
                    "productName": "PIMSMC",
                    "tableName": "UNIDADEADM",
                    "foreignTableName": null,
                    "columns": [
                        {
                            "columnName": "DE_UNI_ADM",
                            "parentColumnName": null,
                            "type": "STRING",
                            "label": null
                        }
                    ]
                },
                {
                    "productName": "PIMSCS",
                    "tableName": "PMINSTANCIAS",
                    "foreignTableName": null,
                    "columns": [
                        {
                            "columnName": "DE_INSTANCIA",
                            "parentColumnName": null,
                            "type": "STRING",
                            "label": null
                        }
                    ]
                }
            ],
            "children": []
        },
        {
            "name": "codigo",
            "required": true,
            "type": "ELEMENT",
            "entityPrimaryKey": false,
            "foreignKeyType": "NONE",
            "attributeProducts": [
                {
                    "productName": "PIMSMC",
                    "tableName": "UNIDADEADM",
                    "foreignTableName": null,
                    "columns": [
                        {
                            "columnName": "CD_UNI_ADM",
                            "parentColumnName": null,
                            "type": "STRING",
                            "label": null
                        }
                    ]
                },
                {
                    "productName": "PIMSCS",
                    "tableName": "PMINSTANCIAS",
                    "foreignTableName": null,
                    "columns": [
                        {
                            "columnName": "INSTANCIA",
                            "parentColumnName": null,
                            "type": "STRING",
                            "label": null
                        }
                    ]
                }
            ],
            "children": []
        },
        {
            "name": "id",
            "required": true,
            "type": "ELEMENT",
            "entityPrimaryKey": true,
            "foreignKeyType": "NONE",
            "attributeProducts": [
                {
                    "productName": "PIMSMC",
                    "tableName": "UNIDADEADM",
                    "foreignTableName": null,
                    "columns": [
                        {
                            "columnName": "ID_UNIDADEADM",
                            "parentColumnName": null,
                            "type": "NUMERIC",
                            "label": "id"
                        }
                    ]
                },
                {
                    "productName": "PIMSCS",
                    "tableName": "PMINSTANCIAS",
                    "foreignTableName": null,
                    "columns": [
                        {
                            "columnName": "INSTANCIA",
                            "parentColumnName": null,
                            "type": "STRING",
                            "label": "id"
                        }
                    ]
                }
            ],
            "children": []
        }
    ]
}

TOTVS Agro Connector Client

Product Connection

A entidade ProductConnection representa as informações da conexão do banco de dados do produto que será integrado. O TOTVS Agro Connector Client suporta conexões com vários bancos de dados ao mesmo tempo, possibilitando que uma mesma instalação de TOTVS Agro 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, responsável pelo controle de nome do produto (NAME) e a versão do produto que está sendo monitorado/integrado (VERSION). Estas informações são necessárias para relacionar as entidades ProductConnection 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 e 12c), 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 banco de dados, utiliza-se um endereço diferente. Nesta documentação, também são apresentados os diferentes 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;
• O atributo enabled representa se a conexão está habilitada ou desabilitada;

IMPORTANTE!

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 banco de 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 para conexões com banco de dados Oracle 11g:

{
    "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 banco de dados PostgreSQL:

{
    "id": "68eaa1a2-aedb-4ba9-9015-a01a31bead89",
    "productName": "PIMS",
    "productVersion": "12.1.27",
    "url": "jdbc:postgresql://localhost:5432/PIMS",
    "username": "PIMS",
    "password": "PIMS",
    "dataBaseType": "POSTGRESQL",
    "enabled": true
}

Product Connection Schema

A entidade ProducConnectionSchema representa a relação entre as entidades ProductConnection e SchemaDefinition. Esta relação significa que uma determinada conexão integrará determinados SchemaDefinition. Por exemplo: 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 configurar duas conexões com diferentes SchemaDefinition. A entidade SchemaDefinition é cadastrada no TOTVS Agro Connector Server e a própria aplicação TOTVS Agro Connector Client encarrega-se de sincronizar, automaticamente, esta entidade. 

Após realizar o relacionamento, o TOTVS Agro Connector Client iniciará o monitoramento das tabelas definidas no SchemaDefinition. Assim que houver qualquer alteração em um ou mais registros das tabelas monitoradas, o TOTVS Agro Connector Client será notificado e processará este registro, enviando-o à plataforma TOTVS Agro 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. Este atributo não precisa ser passado para criar o relacionamento. Preenchido automaticamente;
• O atributo nameSchemaDefinition é o nome do SchemaDefinition relacionado. Este atributo não precisa ser passado para criar o relacionamento. Preenchido automaticamente;
• O atributo enableStandalone será explicado no tópico Modo Standalone;
• O atributo enablePublishRemote será explicado no tópico Modo Publish Remote;

Métodos de Publicação de Mensagens

Existem dois métodos de publicação de mensagens no TOTVS Agro Connector Client, a publicação local (Standalone) e a publicação remota (PublishRemote). Esses métodos são configurados em dois níveis: TOTVS Agro Connector Client e Product Connection Schema.

Nível TOTVS Agro Connector Client:

Ao subir um TOTVS Agro Connector Client, temos os dois parâmetros de publicação para definirmos se publicará mensagens localmente, remotamente (TOTVS Agro Connector Server) ou em ambos, ou seja, um é independente do outro. Por padrão temos a publicação remota (PublishRemote) ativa e a publicação local (Standalone) desativa. Em um cenário com apenas um método de publicação ativo, como por exemplo o cenário padrão, o TOTVS Agro Connector Client irá publicar somente de maneira remota, ou seja, mesmo que em nível de Product Connection Schema seja requerido a publicação local, não irá ser publicada a mensagem localmente.

Nível Product Connection Schema:

Tendo um cenário com os dois métodos de publicação ativos, ou seja, o TOTVS Agro Connector Client terá suporte para as duas opções, não necessariamente a mensagem será publicada das duas maneiras, a partir de agora isso é definido por um ProductConnectionSchema, sendo por meio dos atrubitos enablePublishRemote e enableStandalone a definição de onde os dados gerados serão publicados.

Modo Standalone

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

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

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

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

Image Added

Publish Remote

Com o publishRemote habilitado, qualquer alteração de registros no banco de dados de um produto, irá notificar o TOTVS Agro Connector Client para que faça o envio destes registros para o TOTVS Agro Connector Server - que está disposta em Cloud - Fazendo com que essas alterações estejam disponíveis por uma fila do RabbitMQ para o algum outro produto que seja interessante tê-las.

External Event

Um ExternalEvent (ou Evento Externo, em Português), é um endpoint no TOTVS Agro 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. Importante mencionar que não há um endpoint que seja possível recuperar mensagens. As mensagens somente são disponibilizadas no RabbitMQ (local) via modo standalone.

Database Structure

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

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

Mensagens

Fluxo Geral

Fluxo de mensagens das aplicações OnPremise/Nuvem Privada (Private Cloud) e Cloud, por meio do TOTVS Agro Connector Server e TOTVS Agro Connector Client:

Image Added

Diagrama do fluxo de envio e recebimento de mensagens do TOTVS Agro Connector Server

Image Added

Entidade EventData

A entidade EventData é utilizada para encapsular os dados enviados ao TOTVS Agro Connector Server, componente destinado às aplicações 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;

{
    "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 Agro 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 contexto atual, representa o EventData. Portanto, para enviar uma mensagem para o TOTVS Agro Connector Server, deverá 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 content é o tipo genérico T. No nosso caso, será a entidade EventData;

Estrutura final TOTVSMessage<EventData>

Exemplo de uma mensagem com um schema fictício 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 e inteligência artificial da TOTVS, podendo-se aplicar as funcionalidades de um MDM (Master Data Management ou Gestão de Dados Mestre), como, por exemplo: capacidade de receber dados de qualquer fonte, garantir a integridade dos dados e centralizar os dados de sua aplicação. Além disso, também possui a capacidade de desenvolver aplicativos e os implantar na plataforma, por meio de Carol Apps e Carol Assistant. Para saber mais sobre a plataforma Carol, pode-se acessar sua documentação.

O TOTVS Agro Connector possui integração com a TOTVS Carol, possibilitando a disponibilização de dados de aplicações OnPremise ou SaaS para a plataforma Carol. Neste tópico, são explicados os processo de configuração e uso do TOTVS Agro Connector Server junto à plataforma TOTVS Carol.

Autenticação

Para enviar dados à TOTVS Carol, torna-se necessária a realização da autenticação do usuário, podendo esta ser feita de duas maneiras: pelo accessToken ou pelo connectorToken. Para o TOTVS Agro Connector Server, a autenticação será feita pelo connectorToken. Portanto, gera-se o connectorToken na plataforma Carol e, após geração, o connectorToken é utilizado no cadastro da entidade CarolConnector.

Entidades

Client Envrionment

Como 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 contempla as informações de autenticação/login da plataforma Carol e deve ser cadastrada no TOTVS Agro 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;

Carol Connector

A entidade CarolConnector representa quais Connectors (da TOTVS Carol) que o usuário possui no ambiente, assim como seus Connector Tokens. Na TOTVS Carol, pode-se gerar um Connector Token para cada Connector e são utilizados para o processo de autenticação/identificação de 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 um mesmo Connector. Diferentes Connectors possuem diferentes Connector Token para o mesmo usuário. Por fim, o token da entidade Client Environment é utilizado para identificação no TOTVS Agro 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;

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

Atributos

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

• O atributo name representa um "apelido" para o TOTVS Agro Connector Server diferenciar dos nomes das StagingTable. Por exemplo, na TOTVS Carol contém uma StagingTable chamada "inspecao" e no TOTVS Agro 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 Agro Connector Server apontando para a mesma StagingTable na TOTVS Carol?

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

{
  "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 Agro Connector Server, destinada à TOTVS Carol, a entidade EventDataCarolRequest deverá conter, exatamente, o valor do atributo name. Portanto, não deverá enviar o atributo stagingTableName na mensagem.

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:

Image Added

Entidade EventDataCarolRequest

A entidade EventDataCarolRequest é utilizada para encapsular os dados para enviar ao TOTVS Agro 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;

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

Via Mensageria

Para enviar os dados via mensageria para o TOTVS Agro 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 Agro Connector Server, destinada à Carol, deverá enviar 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;

Estrutura Final TOTVSMessage<EventDataCarolRequest>

{
   "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": [
         {}
      ]
   }
}

04. Observações

Tempo de envio de dados

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

...