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 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?
3. Integração com TOTVS Carol
   1. 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

01. O que é TOTVS Agro Connector?

O TOTVS Agro Connector é uma ferramenta/plataforma que possibilita a integração entre softwares 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).

...

Por meio de dois componentes dispostos em contextos/ambientes distintos, é possível garantir que uma aplicação OnPremise fique sincronizada com uma aplicação em Cloud/SaaS. Para viabilizar este cenário, um dos componentes é o TOTVS Agro Connector Client, ferramenta que é instalada em ambiente OnPremise/Nuvem Privada (Private Cloud). Outro componente, o TOTVS Agro Connector Server, gerenciado pela TOTVS, é responsável de receber todo o fluxo de dados, 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

É o componente responsável por ler os dados das aplicações OnPremise, sejam aplicações TOTVS ou de terceiros. A instalação é realizada em uma máquina que de forma a conectar-se com o banco de dados do produto 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, mencionado no tópico 2 (Integração com produtos TOTVS e externos), uma instância do RabbitMQ (para comunicação via mensageria AMQP).

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. 

...

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.

...

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

...

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.

...

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.

...

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.

...

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.

...

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.

...

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.

...

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

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

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.

...

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

...

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.

...

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.

...

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

...

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

...

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 é utilizada para encapsular os dados para enviar ao TOTVS Agro Connector Server, destinada à TOTVS Carol.

...

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

...

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.

...

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

...

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. 

...