Histórico da Página

...

• CONTEÚDO
• 01. VISÃO GERAL

01. VISÃO GERAL

O Carol Connect é a ferramenta para obter dados de qualquer banco de dados.

Atualmente, estes são os bancos de dados suportados:

• SQL Server (incluindo o SQL Server no Azure)
• Oracle
• PostgreSQL
• MySQL
• Progress OpenEdge
• MongoDB

🚧

Concessões de usuários do banco de dados

Garanta os seguintes grants para o usuário do banco de dados que será usado no 2c:

• CREATE SEQUENCE
• CREATE TABLE
• CREATE TRIGGER
• CREATE INDEX

Requisitos (servidor)

Para instalar e executar o Carol Connect perfeitamente, os seguintes requisitos devem ser atendidos:

• Ambiente (Windows ou Linux) com pelo menos 100 GB de disco rígido, 4 GB de memória RAM e acesso à Internet sem proxy. Se houver uma tabela com grandes dados de registros, como imagens, é altamente recomendável ter 8 GB de memória ram.
• Um ambiente exclusivo para evitar concorrência com outros sistemas.
• A URL *.carol.ai deve ser liberada no servidor de firewall (se aplicável).
• Um usuário com direitos administrativos no banco de dados (permissão para instalar triggers e criar tabelas). Os direitos administrativos podem ser removidos após a instalação e inicialização do ambiente.

Obs.: Caso você tenha a preferência de executar o Carol Connect por meio de uma imagem do Docker, por favor, entre em contato conosco pelo [email protected].

Requisitos de Rede

Carol Connect realiza comunicação com Carol (plataforma). Para permitir a comunicação, alguns requisitos devem ser observados:

• Caso a rede tenha um firewall ou proxy, o URL de Carol deve ser adicionado como uma exceção para o seguro de desempenho.
• Carol connect se comunica com Carol usando o domínio .carol.ai.

Instalando o Carol Connect

Se você está iniciando um projeto com Carol e precisa ter o Carol Connect para integrar seus dados, é possível fazer o download da versão mais recente em nosso repositório do Github: https://github.com/totvslabs/2c/releases .

O Carol Connect não possui instalação, basta descompactar o arquivo ZIP e executar o Carol Connect através do arquivo "run-2c.bat" ou "run-2c.sh".

Configurando Carol Connector como um Serviço

Windows

Arquivos necessários:

• carol2cservice.exe
• serviceinstall.bat
• serviceremove.bat

Instruções para registrar 2c como serviço no windows:

1. Executar o serviceinstall.bat.
2. Inciar o serviço normalmente.

Nota: Você deve estar executando o prompt do Windows como administrador.

Linux

Arquivos necessários:

• carolconnector.service

Instruções para registrar 2c como serviço no linux:

1. Edite o carolconnector.service e edite as seguintes informações:
   -- User
   -- WorkingDirectory
   -- ExecStart
2. Execute o seguinte comando (assumindo que /opt/2c é o diretório de instalação):
   -- sudo systemctl enable /opt/2c/carolconnector.service
3. Inicie o serviço executando o seguinte comando:
   -- sudo systemctl start carolconnector

Efetuando Login no Carol Connect

Acesse o URL http://localhost:8880 e digite as credenciais da Carol:

Image Removed

Alguns detalhes:

• Organization: o domínio ao acessar o ambiente da Carol. Por exemplo, se a URL da Carol for "totvs.carol.ai", sua organização/domínio será "totvs".
• Environment: chamado anteriormente de tenant. Este é o ambiente que você escolhe dentro da sua organização para trabalhar em um projeto. O nome da organização está na barra do cabeçalho da Carol e na URL: totvs.carol.ai/production. Neste exemplo, o ambiente é "production".
• Username: o mesmo que você está usando para se autenticar na Carol. Este nome de usuário será usado para integrar dados a Carol. Você pode mudar mais tarde.
• Password: a senha associada ao nome de usuário.

Criando a conexão com o banco de dados

O botão "+ Add new database" permite que você crie uma nova conexão de banco de dados. Você deve escolher um banco de dados para criar a conexão:

Image RemovedImage Modified

Depois, você deve digitar os parâmetros do banco de dados. Esses parâmetros serão salvos para integrar os dados com a Carol automaticamente.

Image RemovedImage Modified

Este é um exemplo de parâmetros para conexão do SQL Server:

Image Removed

Parâmetros importantes:

• "TOTVS Protheus database?": Este parâmetro indica que o banco de dados é Protheus. Isso significa que a exclusão reversa que ocorre no banco de dados será replicada como uma exclusão real na Carol.
• "TOTVS Protheus use company code from table name?": Este parâmetro indica para a Carol que o grupo de empresas no Protheus pertence ao nome da tabela (como prefixo). O Connector da Carol removerá o grupo da empresa do nome da tabela e o adicionará como uma coluna para todos os registros na tabela.
• "TOTVS Protheus company codes": Este parâmetro indica ao Carol Connect para permitir a conversão do grupo de empresas do prefixo em coluna apenas para os grupos de empresas especificados.

Depois de criar a conexão, você verá a interface abaixo. Esta interface mostra algumas informações importantes:

• Last batch sent: última vez que o Carol Connect enviou dados para a Carol.
• Transmission: quantidade de registros integrados com a Carol desde o último início do serviço do Carol Connect.
• Last minute rate: quantidade de registros por segundo.
• Carol Connect: conector na Carol que está recebendo os dados.
• Mean connection wait time: milissegundos que o Carol Connect está aguardando para obter uma conexão para envio dos dados.
• Mean connection usage time: milissegundos que a Carol está usando a conexão para envio dos dados para a Carol.

Se você desejar alterar os parâmetros de conexão com o banco de dados, você poderá fazer isso clicando nos pontos no lado superior direito:

Image Removed

Ao clicar em "Configure Entities", você poderá adicionar tabelas a serem integradas para a Carol.

O Carol Connect mostrará todas as entidades disponíveis no banco de dados configurado através da conexão criada:

Image Removed

Ao clicar na tabela, você poderá visualizar detalhes relacionados à tabela:

Image Removed

Alguns detalhes:

• Integration: mostra o status da integração.
• Data processing: mostra se o processamento dos dados está em execução ou não.
• Primary key information: mostra os atributos que pertencem à chave primária. Se esta entidade não tiver chave primária definida no banco de dados, você deverá selecionar o(s) atributos(s) que identificam um registro dentro da entidade (é obrigatório definir a forma de identificação dos registros na entidade, caso não haja chave primária definida).
• Condition for initialization: você pode definir uma condição para filtrar alguns dados. Por exemplo, você pode inicializar uma entidade apenas enviando "registros que têm o campo creation_date > '2017-12-10', por exemplo". Neste exemplo, "creation_date" é um atributo que pertence a tabela selecionada. Essa condição será aplicada somente ao inicializar a entidade. Todos os registros inseridos/atualizados serão integrados para a Carol sem validar a condição acima informada.

Estratégia de sincronização

• Sync using a value field: a cada momento definido pela expressão cron no arquivo de configuração, o 2C verifica se há registros incluídos ou alterados após o retorno do último registro de data e hora e envia esses registros para Carol. Ao selecionar esta opção, o campo que contém as informações de carimbo de data / hora de inclusão ou modificação deve ser escolhido. Esta operação suporta campos de sequência (com um carimbo de data / hora ou estrutura de classificação natural para determinar registros mais recentes) ou campos numéricos (tempo lógico / valores de incremento automático).
• Sync using Resync: a cada momento definido pela expressão cron no arquivo de configuração, o 2C verificará o conjunto de chaves primárias locais e os comparará com o conjunto de faixas armazenadas na Carol e enviará os registros ausentes, bem como as exclusões para os que não são registros existentes.
• Sync using Full Load: a cada momento definido pela expressão cron no arquivo de configuração, o 2C obtém todos os dados no banco de dados, exportando para o disco local, preparando os lotes para enviá-los para Carol.

Depois de clicar em "Enable", o Carol Connect irá criar a trigger para obter todos os novos registros e todos os registros atualizados. Após criar a trigger, o Carol Connect exportará todos os dados para a pasta de payload, preparando os dados em lotes para enviá-los para a Carol. A fila (carol_3c_queue) é usada para operações no banco de dados (novos registros, registros atualizados e registros excluídos).

Image Removed

Depois de habilitar a integração da entidade, você poderá habilitar outras entidades. A próxima seção descreve o monitor de integração que pode ser acessado através do menu "Database Manager".

Algumas operações adicionais estão disponíveis, permitindo ao usuário desativar a sincronização (interrompe a trigger), pausar a sincronização, reenviar todos os dados, ressincronizar e gerar um relatório para avaliar os registros enviados e os registros no banco de dados.

Criando uma conexão com o seu Diretório

Selecione a conexão por diretório.

Image Removed

Preencha as informações conforme exemplo a seguir:

Image RemovedImage Modified

Após salvar a configuração acima, uma conexão de diretório será criada.

Em seguida, o diretório precisa estar ativado para sincronizar os arquivos com Carol.

Image RemovedImage Modified

É possível criar uma condição SQL para filtrar os arquivos por restrição de dados.

Para criar a condição SQL, a conexão do diretório precisa saber qual é a conexão com o banco de dados e qual é a query de restrição.

Image Removed

A sintaxe é database_connection_name + # + query_with_files_names_result.

Exemplo: Database#select file_name from my_files where extension = 'jpg'

O resultado da query precisa ser os nomes dos arquivos que serão sincronizados para a Carol.

Anonimização de Dados

2C é capaz de anonimizar dados antes de enviá-los para Carol. Para usar esse recurso, basta selecionar o tipo de anonimização antes de ativar a sincronização da entidade.
Os tipos de anonimização são:

• None. O campo não é anonimizado.
• Base Round. Os dados do campo são arredondados usando um número base. por exemplo: 16800 usando uma base round de 1000 torna-se 17000. Defina o número base no campo de opção.
• Date. Altere os valores de data para 1 (se o campo for dia, mês ou ano) ou 0 (se o campo for hora, minutos ou segundos). Coloque a letra referindo-se aos dados de data no campo de opções. por exemplo: 12/15/2015 11:10:35 usando mdhMs opção torna-se 01/01/2015 00:00:00.
  • m mês
  • d dia do mês
  • y ano
  • h hora
  • M minuto
  • s segundo
• Email Mask. Aplique aos dados do endereço de e-mail. por exemplo: [email protected] torna-se ***@somedomain.com.
• Hash. Uma função hash é aplicada aos dados de campo. Se o campo for um número, CRC32C é selecionado, se for uma string, SHA3 é selecionado.
• Mask. Uma máscara é aplicada aos dados do campo. O caracter # significa que a posição do caractere não está mascarada. por exemplo: número do cartão: 123-456-789-012 usando a máscara XXX-XXX-XXX-### torna-se XXX-XXX-XXX-012. Defina a máscara no campo de opção.
• Supression. Este campo não é enviado para Carol. É suprimido da carga de dados.

Carol Connect Monitor

Para verificar o status relacionado a integração dos dados, você deverá acessar o menu "Database Manager" para verificar algumas informações como descrito anteriormente:

Image RemovedImage Modified

Configuração 2C

A configuração do 2C está localizada em app.config.yml arquivo.

• syncThreads: Número de jobs executores rodando paralelamente.
• poolSize: Número máximo de conexões para o banco de dados.
• ignoreTriggers: defina true se o 2C não puder criar triggers no banco de dados.
• enableReSync: defina true para ativar a estratégia ReSync.
• enableLogin: defina true se o 2C precisar solicitar login sempre que sua API for chamada.
• syncByTimestampResendLastDate: definido como true se durante uma sincronização por Timestamp, o 2C precisar reenviar registros do último timestamp. Útil quando o timestamp não tem registro de hora, apenas data.
• resendAllRecordsOnResync: defina true se o 2C precisar reenviar todos os registros sempre que o ReSync for executado.
• imageAxisPixelsLimit: se maior que zero, 2C validará e redimensionará imagens com eixo maior que o limite informado.
• ignoreQueueTable: Este parâmetro desativará o recurso que permite que o 2C crie a tabela "carol_3c_queue" automaticamente.

Configuração Cron 2C

2C tem quatro expressões cron:

• processing: Define com que frequência o 2C verifica a tabela da fila para enviar dados para Carol.
• resync: Define com que frequência o 2C irá iniciar a primeira etapa para ressincronizar uma tabela. Uma ressincronização completa tem cinco etapas: Verificar dados locais, verificar dados de teste, verificar golden records, verificar registros rejeitados, comparar local com dados remotos.
• syncbyresync: Define com que frequência o 2C iniciará um ReSync para tabelas sincronizadas pelo ReSync.
• syncbytimestamp: Define com que frequência o 2C iniciará uma sincronização por data e hora para tabelas sincronizadas dessa maneira.
• initialload: Defina cada vez que 2C verifica e inicia carregamentos iniciais para tabelas ativadas.

Requisitos do SQL Server

Estes são os requisitos que o banco de dados deve atender para funcionar perfeitamente com o Carol Connect:

• SQL Server 2008 ou superior.
• Configure o SQL Server para ouvir uma porta TCP, normalmente 1433. Por favor, siga estas instruções na seguinte URL para maiores detalhes: https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/configure-a-server-to-listen-on-a-specific-tcp-port

Requisitos do Progress OpenEdge

Estes são os requisitos que o banco de dados deve atender para funcionar perfeitamente com o Carol Connect:

• OpenEdge 10. 3 ou superior.
• O SQL Broker iniciado e aceitando conexões.
• Conceda ao usuário do Carol Connect que tenha privilégios de definição de tabela (privilégios DDL).
• Caso esse banco de dados pertença aos produtos Datasul, a tabela "carol_3c_queue" já existe no dicionário de dados. Não é necessário criá-la (altere a configuração do parâmetro para evitar a criação).
• Caso esse banco de dados não esteja relacionado ao Datasul, o Carol Connect criará a tabela de filas no banco de dados (com base na configuração do Carol Connect) ao iniciá-lo. O OpenEdge somente permite esta operação (DDL) quando nenhum outro usuário está conectado ao banco de dados.

MongoDB

Ao usar o Carol Connect integrado ao MongoDB, os seguintes itens devem ser seguidos:

• Não use o administrador do banco de dados para configurar a conexão.
• Especifique a restrição correta para o usuário que poderá sincronizar os dados.
• Nenhuma operação será executada pela integração - não há tabela de filas para o MongoDB.
• A sincronização ocorre pela estratégia "Sync using a value field".