Conteúdo

O que é TOTVS Connector?
1. TOTVS Connector Client
2. TOTVS Connector Server
Integração com aplicações TOTVS e de terceiros
1. Entidades
  1. TOTVS Connector Server
    1. Client Environment
    2. SchemaDefinition
  2. TOTVS Connector Client
    1. Product Connection
    2. Product Connection Schema
    3. 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 Connector Server
  3. Entidade EventData
  4. Como enviar?
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?
Observações
1. Tempo de envio de dados

01. O que é TOTVS Connector?

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

TOTVS 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 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 Connector Server

O TOTVS 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 Connector Client devem ser capazes de acessá-lo via requisição Internet/HTTP.

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

Entidades

Este tópico apresenta e descreve as entidades utilizadas 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 correto funcionamento do TOTVS 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 Connector Client, pois a plataforma TOTVS 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 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 Connector Server. A gestão do SchemaDefinition é realizada apenas no TOTVS Connector Server. Uma vez publicado o SchemaDefinition, será gerada uma nova versão do SchemaDefinition. Assim, todos os TOTVS 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 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ões com vários bancos de dados ao mesmo tempo, possibilitando que uma mesma instalação de TOTVS Connector Client monitore e integre dados a partir de múltiplos ProductConnection (por exemplo, Oracle, Microsoft SQL Server e PostgreSQL). Cada banco de dados deve possuir uma tabela chamada TCC_PRODUCT_METADATA, 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 Connector Server e a própria aplicação TOTVS Connector Client encarrega-se de sincronizar, automaticamente, esta entidade.

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

Atributos

O atributo id é o identificador do registro;
O atributo idProductConnection é o id do registro da entidade ProducConnection;
O atributo idSchemaDefinition é o id do registro da entidade SchemaDefinition;
O atributo versionSchemaDefinition é a versão do SchemaDefinition relacionado. 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;

{
"id": "39956f0f-341a-48c6-9c80-b5b3498e6899",
"idProductConnection": "20fbd5a8-8ab4-4a16-8cc2-44702a36b8b1",
"idSchemaDefinition": "8a14924d-7f93-4e2b-87af-c8622cd68859",

"enablePublishRemote": "true",
"enableStandalone": "false",

"versionSchemaDefinitoin": "não_precisa_de_valor",
"nameSchemaDefinition": "não_precisa_de_valor"
}

Métodos de Publicação de Mensagens

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

Nível TOTVS Connector Client:

Ao subir um TOTVS Connector Client, temos os dois parâmetros de publicação para definirmos se publicará mensagens localmente, remotamente (TOTVS 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 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 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 ponto 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 Connector Client com o standalone ligado. Ao habilitar o standalone, o TOTVS Connector Client exigirá uma conexão com uma instância do RabbitMQ, instalada, por padrão, no mesmo ambiente. Uma vez definido o TOTVS 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 Connector Client e RabbitMQ instalados.

Com o standalone habilitado, o TOTVS 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 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:

TOTVS AGRO > TOTVS Agro Connector > image2020-10-23_8-30-54.png

Publish Remote

Com o publishRemote habilitado, qualquer alteração de registros no banco de dados de um produto, irá notificar o TOTVS Connector Client para que faça o envio destes registros para o TOTVS 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 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 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 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 Connector Server e Totvs Connector Client:

TOTVS AGRO > TOTVS Agro Connector > image2020-10-22_18-15-52.png

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

TOTVS AGRO > TOTVS Agro Connector > image2020-12-14_15-37-16.png

Entidade EventData

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

{

"header": {
"type": "atributo_name_do_schemaDefinition",
"generatedOn": "2000-01-01T00:00:00.000000Z",
"locale": "pt_BR"
},

"content": { }

}

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

{
"organizationSubdomain": "ambienteteste",
"password": "senha_carol",
"subdomain": "clienteteste",
"username": "usuario_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 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 Connector Server diferenciar dos nomes das StagingTable. Por exemplo, na TOTVS Carol contém uma StagingTable chamada "inspecao" e no TOTVS Connector Server, contém duas CarolStagingTable que apontam para a StagingTable "inspecao" na TOTVS Carol. Para diferenciar as duas CarolStagingTable, utiliza-se o atributo name;
O atributo description representa uma descrição sobre a CarolStagingTable;

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

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

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

TOTVS AGRO > TOTVS Agro Connector > image2020-10-22_18-18-19.png

Entidade EventDataCarolRequest

A entidade EventDataCarolRequest é utilizada para encapsular os dados para enviar ao TOTVS 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 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 Connector Server: /v1/environment/carol/eventsDataCarol

No corpo da requisição, passa-se uma lista de EventDataCarolRequest. Após o envio de dados via HTTP, o TOTVS Connector Server validará as informações e direcionar para TOTVS Carol.

Via Mensageria

Para enviar os dados via mensageria para o TOTVS Connector Server, deve-se enviar a entidade TOTVSMessage<T>. A entidade TOTVSMessage é uma classe da biblioteca TJF, que encapsula a mensagem a ser enviada por mensageria.

O tipo genérico T é a entidade a ser encapsulada que, no nosso caso, será a EventDataCarolRequest. Portanto, para enviar uma mensagem para o TOTVS Connector Server, destinada à Carol, deverá 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;

{

"header": {
"type": "atributo_name_da_entidade_CarolStagingTable",
"generatedOn": "2000-01-01T00:00:00.000000Z",
"locale": "pt_BR"
},

"content": { }

}

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 Connector Client no OnPremise/Nuvem Privada (Private Cloud), TOTVS 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.