...

Conteúdo

1. O que é TOTVS Connector
   
   1. TOTVS Connector ServerTOTVS Connector Client
      1. Requisitos Mínimos de Instalação
      2. Requisitos de Ambiente / Infraestrutura 
   2. TOTVS Connector Server
   3. Diagrama da arquitetura do TOTVS Connector(Tentar generalizar para atender o da Carol, se não, criar 2 diagramas e colocar nos respectivos tópicos abaixo)
2. Integração com aplicações TOTVS e de terceirosIntrodução (explicar um pouco mais sobre as integrações de produtos internos e externos, pensar em um diagrama para ilustrar)
   
   1. Entidades (Cadastros ?)
      1. TOTVS Connector Server
         1. Client Environment 
         2. SchemaDefinition
      2. TOTVS Connector Client
         1. Product Connection (citar que o usuário do banco cadastrado no product connection, precisa de permissão para inserir, alterar e deletar, criar e alterar triggers e tabelas)
         2. Product Connection Schema (citar que irá criar triggers no momento desse cadastro) 
         3. Modo Standalone
         4. External Event
   2. Mensagens
      1. Fluxo das mensagens
      2. Estrutura
      3. Como enviar? (rabbit + api do External Event)
3. Integração com TOTVS Carol (Cadastros ?)Carol
   1. Introdução 
   2. Entidades (explicar um pouco mais sobre a integração com a Carol e pensar em um diagrama para ilustrar)
   3. Autenticação
   4. Entidades
      1. Client Environment
      2. CarolUser
      3. CarolConnector
      4. CarolStagingTable
      5. EventDataCarol
   5. Mensagens
      1. Fluxo
      2. Estrutura das mensagens (EventDataCarolRequest)Entidade EventDataCarolRequest
      3. Como enviar?(rabbit + endpoint)
4. Observações importantes
   1. Tempo de envio das mensagens (explciar que pode demorar por conta da conexão / processamento)de dados

01. O que é TOTVS Connector?

...

Por meio de dois componentes dispostos em ambientes diferentes, é possível uma aplicação On Premise ficar sincronizada com um aplicação em Cloud. Um desses componentes é o TOTVS Connector Client, que é instalado no ambiente On Premise / Nuvem Privada (Private Cloud). O outro componente é o TOTVS Connector Server, gerenciado pela TOTVS, é responsável de receber todo fluxo de dados. Portanto, o cliente deverá instalar e configurar apenas o TOTVS Connector Client.

...

É a parte responsável por ler os dados das aplicações On Premises, seja aplicações TOTVS ou de terceiros. Ele é instalado em uma máquina que possa se conectar com o banco de dados do produto On Premise / Nuvem Privada (Private Cloud). O TOTVS Connector Client precisa de uma instância do PostgreSQL e, dependendo da configuração standalone (explicação no tópico 2. Integração com produtos TOTVS e externos), uma instância do RabbitMQ.

...

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. 

Diagrama da arquitetura do TOTVS Connector

A imagem a seguir representa a arquitetura do TOTVS Connector:

...

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

Introdução

Entidades

Este tópico irá apresentar apresentará as entidades de cadastros utilizados no TOTVS Connector Server e TOTVS Connector Client.

TOTVS Connector Server

Client Environment

A entidade Client Environment representa o ambiente no 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 , ou seja, todo dado trafegado deve possuir um token do cliente. Além disso, o token deve ser 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

TOTVS Connector Client

Product Connection

...

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.

A estrutura do SchemaDefinition é representada pelo JSON abaixo:

{
    "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 abaixo um 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ã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.

Exemplo de  ProductConnection com o banco de dados 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
}

Exemplo de um ProductConnection com o 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
}

Exemplo de 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

Após a criação de um Product Connection, é necessário definir quais schemas serão integrados.
Essa definição é feita pelo Product Connection Schema, nele estaremos relacionando um Product Connection e um Schema Definition.
Outra informação importante é se esse relacionamento irá habilitar o modo standalone, onde iremos explicar no tópico Modo Standalone .
Após realizar o relacionamento, o TOTVS Connector Client irá iniciar o monitoramento das tabelas definidas no Schema Definition, e assim que houver qualquer alteração em qualquer registro, o TOTVS Connector Client será notificado e irá processar esse dado e enviar para o TOTVS Connector Server.

Modo Standalone

External Event

Mensagens

Fluxo de Mensagens

...

03. Integração com TOTVS Carol

Introdução

A TOTVS Carol é uma plataforma de dados com inteligência artificial, podendo aplicar todas as funcionalidades do MDM (Master Data Management, ou Gestão de Dados Mestre, em Português), como por exemplo: capacidade de receber dados de qualquer fonte,  garantir a qualidade dos dados e centralizar os dados de sua aplicação. Além disso, também possui a capacidade de desenvolver aplicativos e implantá-los na plataforma e utilizar a Assistente Carol. Para saber mais sobre a plataforma, você pode acessar a sua documentação.

...

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 AddedDiagrama mostrando a mensagem saindo do produto e chegando na totvs carol: produto (interno e externo) → tc-server → totvs carol

Entidade 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 On Premise / Nuvem Privada (Private Cloud), TOTVS Connector Server na nuvem e as aplicações de terceiros podendo estar tanto na nuvem quanto On Premise, é possível acontecer atrasos e lentidões no envio dos dados, devido à conexão utilizada.