TOTVS Clock In

Atalhos

Árvore de páginas

CONTEÚDO


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

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

03. REQUISITOS (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.

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

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

06. EFETUANDO LOGIN NO CAROL CONNECT

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

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.

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

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.

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

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:

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:

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

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.

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

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.

09. CRIANDO UMA CONEXÃO COM O SEU DIRETÓRIO

Selecione a conexão por diretório.

Preencha as informações conforme exemplo a seguir:

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.

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

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.

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

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

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

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

14. REQUISITOS DO SQL SERVER

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

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

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

  • Sem rótulos