Conteúdo

1. O que é TOTVS Agro Connector?
   
   1. TOTVS Agro Connector Client
   2. Requisitos Mínimos de Instalação
   Requisitos de Ambiente / Infraestrutura 
   3. 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 (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)Product Connection Schema (citar que irá criar triggers no momento desse cadastro) 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 EventDataEstrutura
      4. Como enviar?(rabbit + api do External Event)
3. Integração com TOTVS Carol
   1. Introdução 
   2. Contextualização
   3. EntidadesEntidades (explicar um pouco mais sobre a integração com a Carol e pensar em um diagrama para ilustrar)
   4. Autenticação
   5. Entidades
      1. Client Environment
      2. CarolUser
      3. CarolConnector
      4. CarolStagingTable
      5. EventDataCarol
   6. 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 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 apenas o TOTVS Connector Client.

TOTVS Connector Client

, 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 É a parte 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 / Nuvem Privada (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. 

Image Removed

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

Entidades

Este tópico 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 do 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 que será utilizado para enviar os dados. 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

O SchemaDefinition é uma estrutura de dados que possui as informações da tabela de origem do dado e como ele deve ser convertido para ser enviado ao TOTVS Connector Server. A gestão do SchemaDefinition é realizada apenas no TOTVS Connector Server. Uma vez publicado o SchemaDefinition, gerará uma nova versão do SchemaDefinition. Assim, todos os TOTVS Connector Client irão sincronizar os novos SchemaDefinition.

...

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
        {
        

{
    "id": "Identificador: UUID",
    "version": "Versão",
    "name": "Nome do atributo",
      "description": "Descrição",
      "statusrequired": "Status: PRODUCTION ou DEVELOPMENT",
true -- se o atributo é obrigatório,
            "createdAttype": "Data de criaçãoTipo: ELEMENT ou ARRAY",
    "updatedAt": "Data da última atualização",
    "attributesentityPrimaryKey": [false -- Arrayse queo contématributo objetosé Schemaa Attributes
primary key       {da entidade,
            "nameforeignKeyType": "NomeTipo do atributo",
       de chave estrangeira: NONE, PARENT_SCHEMA ou OTHER_SCHEMA",
     "required       "attributeProducts": true -- Array de seobjetos oSchema atributoAttribute éProduct obrigatório,[
            "type": "Tipo: ELEMENT ou ARRAY",
{
                    "entityPrimaryKeyproductName": false"Nome -- se o atributo é a primary key da entidade,
do produto",
                    "foreignKeyTypetableName": "Nome da tabela"Tipo,
 de chave estrangeira: NONE, PARENT_SCHEMA ou OTHER_SCHEMA",
              "foreignTableName": "Nome da tabela de referência a chave estrangeira",
                    "attributeProductscolumns": -- Array de objetos Schema Attribute ProductColumns [
                {
               {
     "productName": "Nome do produto",
                    "tableNamecolumnName": "Nome da tabelacoluna",
                            "foreignTableNameparentColumnName": "Nome da tabelacoluna dena referênciatabela ada chave estrangeira",
                    "columns": -- Array de objetos Schema Attribute Columns [
         "type": "Tipo da coluna: STRING, NUMBER, DATE e CLOB",
                {
            "label": "Label da coluna quando o atributo for Primary Key, Parent Schema ou Other   "columnName": "Nome da coluna",
Schema"
                        }
        "parentColumnName": "Nome da coluna na tabela da chave estrangeira",
    ]
                }
        "type": "Tipo da coluna: STRING],
 NUMBER, DATE e CLOB",
        "children": -- Array de objetos Schema Attributes quando o type for ARRAY []
        "label": "Label da coluna quando o atributo for Primary Key, Parent Schema ou Other Schema"}
    ]
}

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",
            "childrenentityPrimaryKey": --false,
 Array de objetos Schema Attributes quando o type for ARRAY []
   "foreignKeyType": "NONE",
      }
    ]
}

Segue abaixo um exemplo de SchemaDefinition:

{
    "idattributeProducts": "a126a79d-693c-4d2d-bbbd-a3cbff1abfc9",
[
     "version": "12.1.27",
    "name": "Instancia",
    "description": "Instancia", {
    "status": "PRODUCTION",
      "createdAt": null,
    "updatedAt": null,
    "attributesproductName": ["PIMSMC",
        {
            "nametableName": "nomeUNIDADEADM",
            "required": true,
            "typeforeignTableName": "ELEMENT"null,
            "entityPrimaryKey": false,
            "foreignKeyTypecolumns": "NONE",
[
              "attributeProducts": [
          {
        {
                    "productNamecolumnName": "PIMSMCDE_UNI_ADM",
                    "tableName": "UNIDADEADM",
       "parentColumnName": null,
            "foreignTableName": null,
               "type": "STRING",
    "columns": [
                       "label": {null
                        }
     "columnName": "DE_UNI_ADM",
              ]
              "parentColumnName": null  },
                {
            "type": "STRING",
       "productName": "PIMSCS",
                    "labeltableName": null"PMINSTANCIAS",
                        }"foreignTableName": null,
                    ]"columns": [
                },
        {
        {
                    "productNamecolumnName": "PIMSCSDE_INSTANCIA",
                            "tableNameparentColumnName": "PMINSTANCIAS"null,
                            "foreignTableNametype": null"STRING",
                            "columnslabel": [null
                        {}
                    ]
           "columnName": "DE_INSTANCIA",
    }
            ],
            "parentColumnNamechildren": null,[]
        },
        {
            "typename": "STRINGcodigo",
              "required": true,
              "labeltype": null"ELEMENT",
            "entityPrimaryKey": false,
            }"foreignKeyType": "NONE",
            "attributeProducts": [
        ]
        {
        }
            ]"productName": "PIMSMC",
            "children": []
        }"tableName": "UNIDADEADM",
        {
            "nameforeignTableName": "codigo"null,
            "required": true,
            "typecolumns": "ELEMENT",[
            "entityPrimaryKey": false,
            {
               "foreignKeyType": "NONE",
            "attributeProductscolumnName": ["CD_UNI_ADM",
                {
            "parentColumnName": null,
       "productName": "PIMSMC",
                    "tableNametype": "UNIDADEADMSTRING",
                            "foreignTableNamelabel": null,
                       "columns": [}
                    ]
     {
           },
                {
 "columnName": "CD_UNI_ADM",
                  "productName": "PIMSCS",
            "parentColumnName": null,
       "tableName": "PMINSTANCIAS",
                    "typeforeignTableName": "STRING"null,
                            "labelcolumns": null[
                        }{
                    ]
                }"columnName": "INSTANCIA",
                {
            "parentColumnName": null,
       "productName": "PIMSCS",
                    "tableNametype": "PMINSTANCIASSTRING",
                    "foreignTableName        "label": null,
                    "columns": [
    }
                    ]
      {
          }
            ],
            "columnNamechildren": "INSTANCIA",[]
        },
        {
            "parentColumnNamename": null"id",
               "required": true,
             "type": "STRINGELEMENT",
               "entityPrimaryKey": true,
             "labelforeignKeyType": null"NONE",
            "attributeProducts": [
           }
     {
               ]
     "productName": "PIMSMC",
          }
            ]"tableName": "UNIDADEADM",
            "children": []
       "foreignTableName": }null,
        {
            "namecolumns": "id",[
             "required": true,
          {
  "type": "ELEMENT",
            "entityPrimaryKey": true,
            "foreignKeyTypecolumnName": "NONEID_UNIDADEADM",
            "attributeProducts": [
                {"parentColumnName": null,
                    "productName": "PIMSMC",
       "type": "NUMERIC",
               "tableName             "label": "UNIDADEADMid",
                       "foreignTableName": null, }
                    "columns": []
                },
        {
        {
                    "columnNameproductName": "ID_UNIDADEADMPIMSCS",
                    "tableName": "PMINSTANCIAS",
            "parentColumnName": null,
       "foreignTableName": null,
                    "typecolumns": "NUMERIC",[
                        {
    "label": "id"
                          }"columnName": "INSTANCIA",
                    ]
                }"parentColumnName": null,
                {
            "type": "STRING",
       "productName": "PIMSCS",
                    "tableNamelabel": "PMINSTANCIASid",
                       "foreignTableName": null, }
                    "columns": []
                }
        {
    ],
            "children": []
        }
   "columnName": "INSTANCIA",
                            "parentColumnName": null,
                            "type": "STRING",
                            "label": "id"
                        }
                    ]
                }
            ],
            "children": []
        }
    ]
}

TOTVS 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 Connector Client suporta conexão com vários bancos de dados ao mesmo tempo, trabalhando com múltiplos ProductConnection. Cada banco de dados deve possuir uma tabela chamada TCC_PRODUCT_METADATA, onde deve existir um registro com o nome do produto (NAME) e a versão (VERSION). Essas informações serão necessárias para relacionar o ProductConnection com o 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), PostgreSQL e Microsoft SQL Server.

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 de dados é um endereço diferente. Abaixo, são apresentados os diferentes endereção 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;

IMPORTANTE!

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

ProductConnection com o banco de dados SQL Server:

 ]
}

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:jtds:sqlserverpostgresql://localhost:14335432/PIMS",
    "username": "PIMS",
    "password": "PIMS",
    "dataBaseType": "MSSQLSERVER",
    "enabled": true
}

ProductConnection com o banco de dados Oracle 11G:

{POSTGRESQL",
    "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 com o 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. Essa 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 possuir duas conexões com diferentes SchemaDefinition. A entidade SchemaDefinition é cadastrada no TOTVS Connector Server e a própria aplicação TOTVS Connector Client se encarrega de sincronizar, automaticamente, essa 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 integradas, o TOTVS Connector Client será notificado e processará esse registro e enviarã para o 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 atributo não precisa ser passado para criar o relacionamento. Ele é preenchido automaticamente;
• O atributo nameSchemaDefinition é o nome do SchemaDefinition relacionado. Esse atributo não precisa ser passado para criar o relacionamento. Ele é preenchido automaticamente;
• O atributo enableStandalone será explicado no tópico Modo Standalone, apresentado a seguir;

...

...

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 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 o TOTVS Connector Client com o standalone ligado. Ao ligar o standalone, o TOTVS Connector Client exigirá uma conexão com uma instância do RabbitMQ, geralmente instalada no mesmo ambiente. Uma vez definido o TOTVS Connector Client como standalone, precisamos habilitar o ProductConnectionSchema como standalone. 

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

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 habilitadoNo modo standalone desabilitado, qualquer alteração de registros no banco de dados do de um produto A, o TOTVS Connector Client será notificado e enviará esses registros para , irá notificar o TOTVS Agro Connector Server, que está no Cloud.Com o standalone habilitado, o TOTVS Connector Client também enviará os registros do produto A para a instância do RabbitMQ, que também está no On Premise. Com isso, outros produtos que estão no On Premise, por exemplo os produtos B e C, poderão escutar uma fila na instância do RabbitMQ para receber esses mesmos registros. Além disso, é possível os produtos B e C, publicarem os registros no RabbitMQ. Assim, o TOTVS Connector Client irá ser notificado e processar os registros no banco de dados do produto AClient 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. 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 Agro 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 Agro Connector Client demonstrará essa  validará e exibirá esta falta de conformidade/integridade, facilitando verificações de problemas no funcionamento desejado.

Mensagens

Fluxo

...

Geral

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

Image Added

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

Image AddedImage Removed

Entidade EventData

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

...

{
    "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 nosso caso, será acontexto atual, representa o EventData. Portanto, para enviar uma mensagem para o TOTVS Agro 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 Agro 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 Agro 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 Agro 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 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 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 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 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 Agro 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;

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

Pois podem Isto pode ser configurado de forma a conter duas ou mais formas de enviar 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á mandar 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 RemovedImage 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 irá validar 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á mandar 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 On Premise OnPremise/Nuvem Privada (Private Cloud), TOTVS Agro 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. 

...