0 Apresentando a Carol

0.1 O que é a Carol?

É uma Plataforma de Dados e Aplicativos Inteligentes (Inteligência Artificial).

0.2 Fluxo de dados

Processamento e transformação dos dados realizados pela Carol.

Pipeline dos dados na Carol representados pela funcionalidade Data Journey.

0.3 Glossário

Organization (Organização) Ambiente principal, pode conter diversos Tenants;
Tenant (Locatário): Ambiente definido pelo Cliente na Carol;
Carol Data Storage (CDS): Armazenamento de dados primário na Carol, baixo custo;
Real Time (Elasticsearch); Armazenamento de dados na camada Golden Record com maior performance, porém o custo é maior;
Assistam o vídeo! https://vimeo.com/404587121/35dc882845
Golden Records (Dados de Ouro): Dados limpos e tratados que serão utilizados pela Carol ou sistemas de terceiros;
Staging Tables (Tabelas de Preparo): Tabelas para entradas de dados na Carol;
Data Models (Modelos de Dados): Estrutura e regras de dados que transformam Staging tables em Golden Records;
Insights (Visões): Gráficos e dimensões geradas a partir das Golden Records;
NLP (Programação de Linguagem Natural): Interação via escrita ou voz com a Carol;
ETL (Extração, Transformação, Carregamento): Usado para combinar dados de diversas fontes;
MDM (Gerenciamento de Dados Mestre): Prover processos para coletar, agregar, combinar, consolidar, garantir a qualidade, persistir e distribuir dados;
API (Interface de Programação de Aplicativos): Conjunto de rotinas, protocolos e ferramentas para construir aplicações;
Endpoint (Ponto de Extremidade): É a URL onde seu serviço pode ser acessado por uma aplicação cliente;
Named Query (Consulta Nomeada): São as "views" criadas na Carol;
Data Access Level (Privacidade de Dados): Restrição de acessos aos dados dentro da Carol.

0.4 Arquivos para Exercícios

Fazer o download dos seguintes arquivos para os exercícios do treinamento.
Pessoas.xlsx
Cidades.xlsx

1. Ambientes Carol

1.1 Gerenciando Organização

Organization é o ambiente do administrador geral dos ambientes Carol.

1.1.1 Home

Total Storage Used: Armazenamento total utilizado pela Organization;
Largest Tenant: Ambiente que está consumindo mais armazenamento de dados;
Total users: Toda de usuários criados na Organization;
Storage: Total de armazenamento por Ambiente;
Tenants: Ambientes criados na Organization;
JupyterLab instances: Instâncias do Jupyter Lab criadas na Organization;
Manage: Gerenciamento da Organization.

1.1.2 Configurações

Allow all domains: Cadastro dos domínios liberados para acessar a Carol;
Locale: Localidade como os dados serão formatados: inglês (EUA), português (Brasil), espanhol;

1.1.3 Ambientes

1.1.3.1 Convidar usuário

Email: endereço de email que será enviado o convite;
Tenant: ambiente que o usuário será convidado;
User Role: permissão que será atribuída para o usuário convidado.

1.1.3.1 Criar ambiente

Label: Descrição de exibição do ambiente;
Name: Nome do ambiente;
Allow all domains: Cadastro dos domínios liberados para acessar a Carol;
Locale: Localidade como os dados serão formatados: inglês (EUA), português (Brasil), espanhol;
Activate login by SMS: Ativar login por SMS;
Send a copy of the SMS by email for login: Enviar cópia do SMS por e-mail.

1.1.4 Usuários

Active: Ativar ou desativar acesso do usuário na organization;
Role: Regra de acesso:

1. Organization Admin: Administrador da organização;
2. Organization User: Usuário da organização.

Locale: Configuração de localidade por usuário: inglês (EUA), português (Brasil), espanhol;

1.1.5 Convites

Invite a colleague: Enviar convite para um novo participante;
Re-send invite: Reenviar o convite;
Lixeira: Excluir o convite.

1.2 Gerenciando Ambiente

1.2.1 Home

1. Barra de menu principal com acessos para as principais habilidades da Carol;
2. Lista e acesso para os tenants disponíveis no Carol;
3. Gerenciamento dos registros Golden Records;
4. Gerenciamento das Stagings;
5. Gerenciamento dos usuários e suas permissões;
6. Gerenciamento do volume de dados contidos no ambiente;
7. Gerenciamento dos Carol Apps disponíveis no ambiente;
8. Acessos administrativos:
   1. Documentação;
   2. Log de atividades;
   3. Acessos aos Carol Apps;
   4. Gerenciamento do ambiente.
9. Controle de entrada de dados na Carol;
10. Controle das atividades realizadas no ambiente.

Área de gerenciamento do ambiente

1.2.2 Acessos

Allow all domains: Cadastro dos domínios liberados para acessar a Carol;
Locale: Localidade como os dados serão formatados: inglês (EUA), português (Brasil), espanhol;
Activate login by SMS: Ativar login por SMS;
Send a copy of the SMS by email for login: Enviar cópia do SMS por e-mail.

1.2.3 Usuários

Active: Ativar ou desativar acesso do usuário na tenant;
Role: Regra de acesso:

1. Tenant Admin: Administrador do ambiente;
2. Application Admin: Administrador do aplicativos instalados na tenant;
3. Business User: Usuário de negócios acesso aos insights e skills.

Locale: Configuração de localidade por usuário: inglês (EUA), português (Brasil), espanhol;

1.2.4 Convites

Invite a colleague: Enviar convite para um novo participante;
Re-send invite: Re-enviar o convite;
Lixeira: Excluir o convite.

1.2.5 Tokens

Token é um código gerado pela Carol para autenticação na plataforma.

Revoke Token: Exclusão do token gerado, se efetuado essa operação será necessário criar um novo token de acesso no Connector.

1.2.6 Acessos aos dados

1.2.6.1 Criar Grupo

Clicar no botão "Create group" localizado no canto direito superior e preencher as seguintes informações:

• Name: nome interno utilizado pela Carol;
• Label: Descrição que será exibido para o usuário final.

1.2.6.2 Restringir Data Model

Selecionar o DM no qual precisamos fazer a restrição.

1.2.6.3 Restringir Ação

Selecionar o tipo de ação que queremos restringir no DM.

• Read: Leitura;
• Create: Criação;
• Update: Alteração;
• Delete: Exclusão.

1.2.6.4 Criar Regra

Criar a regra de restrição conforme os campos x funções x valores desejados.

1.2.6.5 Adicionar Usuários

Clicar no botão "Users" para apresentar a tela de inclusão de usuários, clicar no botão "Add user" localizado no canto direito superior e então selecionar o(s) usuário(s) que deverão respeitar a regra criada para o referido grupo.

1.2.7 Configurando NLP

Levenstein: O quão permissivo ele vai ser com erros ortográficos. Por exemplo considerar "Rafael" e "Raphael" a mesma coisa;
Case Sensitive: Se "FELIPE" e "felipe" devem ser considerados como coisas diferentes pra match de entidade;
External Parser: Temos um carol app que faz algumas funções de nlp extras como procurar ranges de data na sua sentença;
Self Entity: A entidade que refere ao usuário que está falando. Por exemplo "Quantos pedidos em aberto eu tenho?". Se existir uma self-entity, a engine vai entender que o usuário está perguntando sobre o usuário que está fazendo a pergunta. Aí você consegue passar informações dele no named query model. Por exemplo, passar [[userid]] como parâmetro para uma query;
Initial Skill: A skill que vai ativar quando o usuário abre o app;
Stemming: É uma otimização agressiva que olha só pra raiz da palavra. Então ele vai considerar "desenvolvimento", "desenvolvido", e "desenvolto" como a mesma coisa.

1.3 Gerenciando Minha Conta

Área de gerenciamento da conta do usuário logado na Carol.

Account Email: Não é possível alterar;
User name: Nome do usuário;
Locale: Localidade do usuário: inglês (EUA), português (Brasil), espanhol;
Phone: Número do telefone para envio do SMS de validação para login;
Opção 1: Receber e-mails quando convites são enviados;
Opção 2: Receber emails quando convites são aceitos;
Change password: Aba para alteração da senha;
Logout: Finalizar a sessão.

2. Conectando na Carol

2.1 Connector

É a porta de entrada na Carol e os serviços disponíveis precisam do "Connector Id" para validação e integração com a plataforma.

No menu principal selecionar "Connectors", opção "All" e em seguida no botão "Add a Connector" canto direito superior.

Passo 1 - Selecionar ou criar um novo projeto.

Passo 2 - Selecionar um dos diversos tipos de "Connectors" que podemos utilizar para sincronizar dados para dentro da plataforma.

Passo 3: Configurar o "Connector" escolhido, cada connector possui sua particularidade para configurar, a seguir explicaremos os mais utilizados.

2.2 File (Arquivo)

Podemos importar dados a partir dos seguintes tipos de arquivos csv, json e xls, desde que o tamanho do arquivo seja inferior a 100mb.
Configuração de importação:

1. Connector Label: Nome para exibição (Connector Name será igual porém sem o espaço em branco);
2. Upload File: Selecionar o arquivo para carga dos dados;
3. Staging Name: Nome atribuído para a tabela de entrada que será criada;
4. Identifier Field: Campo que será usado como Primary Key (PK);
5. Botões:
   1. Cancel: Cancela a operação;
   2. Preview: Exibe no painel da direita os dados que serão importados;
   3. Next: Próximo passo para finalizar a operação.

Importar a planilha Pessoas.xlsx

Importar a planilha Cidades.xlsx

Serão criadas as Staging Tables com os dados contidos nos respectivos arquivos carregados.

Selecionar "View Staging Data" para exibir os dados importados.

Pessoas

Cidades

2.3 Carol Connect (2C)

2.3.1 Instalação

2.3.1.1 Windows

Baixar o zip de instalação {+}https://github.com/totvslabs/2c/releases+ conforme o sistema operacional do servidor.


Extrair os arquivos no diretório de destino desejado.

Executar o prompt de comando com permissão de administrador.

Entrar no diretório de instalação e executar a .bat de instalação

Inicializar o serviço Carol2CService no Windows (run services.msc)

Acessar via navegador a URL {+}http://localhost:8880+ (porta padrão de instalação)

Importante: Caso a porta 8880 ou 8881 estiverem em uso, podemos alterar a porta padrão abrindo o arquivo app.config.yml no diretório raiz e alterando as portas padrões.

2.3.1.2 Linux

wget
yum install wget
download 2c
wget https://github.com/totvslabs/2c/releases/download/2.25.4/CarolConnectorLinux.tar.gz
unzip
tar -xvzf CarolConnectorLinux.tar.gz
diretório
mover para pasta sugerida para instalação
mv 2c /opt
entrar na pasta
cd /opt/2c
editar serviço (VIM)
abrir: vi carolconnector.service
sair: :wq!
User = Usuário Linux (root);
WorkingDirectory = Diretório de Instalação (/opt/2c);
ExecStart = Ajustar o caminho de execução.
remover serviço
sudo systemctl disable /opt/2c/carolconnector.service
instalar serviço
sudo systemctl enable /opt/2c/carolconnector.service
inicializar serviço
sudo systemctl start carolconnector
parar serviço
sudo systemctl stop carolconnector
log serviço
systemctl status carolconnector

2.3.1.3 Mac

Instalar JDK na máquina. https://www.oracle.com/technetwork/java/javase/downloads/jdk13-downloads-5672538.html
Localizar o caminho do Java executando a seguinte instrução.
comando: which java
resultado: /usr/bin/java
Alterar arquivo 2c.sh substituindo o novo caminho do java no início da linha de comando.
resultado: /usr/bin/java -Dfile.encoding=UTF-8..
Executar o arquivo 2c.sh
comando: ./2c.sh

2.3.2 Configuração

No arquivo app.config.yml localizado no diretório raiz de instalação do 2c, as principais chaves são:
syncThreads: Número de threads para conexão com o banco de dados;
ignoreQueueTable: Ignora a criação da tabela de fila do 2c no banco de dados do cliente;
enableReSync: Habilitar a sincronização por ReSync;
generateScriptsOnly: Não é criada as triggers no banco de dados do cliente;
server / maxThreads: Número de threads internas do 2c;
applicationConnectors / port: Porta padrão de instalação;
adminConnectors / port: Porta padrão de instalação;
syncbyresync: Schedule para sync ReSync;
syncbytimestamp: Schedule para sync Value;
syncbyfullload: Schedule para Full Load

2.3.3 Atualização

Para atualizar o 2c é bem simples basta seguir o seguinte passo-a-passo:

1. Parar o serviço do 2c - carol2cservice;
2. Remover o serviço do 2c através do arquivo serviceremove.bat no diretório raiz;
3. Baixar a nova versão do 2c no portal {+}https://github.com/totvslabs/2c/releases+;
4. Extrair e sobrepor os arquivos no diretório que o 2c está instalado;
5. Reinstalar o 2c através do arquivo serviceinstall.bat no diretório raiz (conforme o capítulo anterior);
6. Iniciar o serviço do 2c - carol2cservice;
7. Não é necessário refazer as configurações já efetuadas.

2.3.4 Sincronização de dados

2.3.4.1 Banco de Dados

Ao concluir a instalação do 2C, precisamos autenticar o serviço na Carol e selecionar o tipo de banco de dados para criar uma conexão de dados.
A sincronização de dados padrão do 2c é por TRIGGER, se houver restrição na utilização consulte o capítulo 2.3.5 Configuração por schedule.


Exemplo utilizando MS SQL SERVER.
importante: Ativar o protocolo TCP para comunicação. https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/configure-a-server-to-listen-on-a-specific-tcp-port

Se for uma ambiente TOTVS Protheus

1. Ativar integração com TOTVS Protheus;
2. Informar se o ambiente TOTVS Protheus possui mais de um grupo de empresa configurado;
3. Informar quais grupos de empresas serão sincronizados, caso não seja informado nenhum valor todos os grupos de empresas serão sincronizados.

Se a configuração for concluída com sucesso, será exibida a tela de gerenciamento de sincronização e para sincronizar uma tabela precisamos selecionar o botão "configure entities".

Será exibida a tela de configuração de entidades

Com as seguintes funcionalidades:

Pesquisador de objetos;

Lista de objetos (tabelas ou views) disponíveis no banco de dados configurado;

Campo(s) que sera(ão) usado(s) para PK;

Filtro SQL para restrição de dados;

Botão de teste da restrição SQL configurada;

Sync por Valor: Opção de selecionar e formatar campos a partir de valores definidos para sincronização dos dados;

Sync por Resync: Opção de sincronizar os dados confrontando as PKs que estão na tabela com as PKs que estão na Carol, motivo o qual esse processo é muito mais demorado;

Sync Full Load: Sempre será enviado uma carga completa para a Carol e ela fará o tratamento do que é inclusão ou edição de dados.

Sync por Trigger: Sincronização padrão do 2c, se nenhuma das syncs anteriores Valor, ReSync e Full Load, não forem configuradas será ativada a integração por Trigger.
Opção de enviar os dados diretamente para a Storage da Carol sem passar pelo elasticsearch;

Controle das operações de sincronização

Enable: Ativa a sincronização dos dados para a Carol, se trigger será criada automaticamente no BD;
Disable: Desativa a sincronização dos dados para a Carol, se trigger será excluída do BD;
Pause: Pausa a sincronização;
Resend all data: Força a carga completa dos dados na Carol;
ReSync: Força o sync por Resync;
ReSync report: Efetua todos os processamentos do Resync, porém não envia dos dados para a Carol;
View report: Ao término do ReSync report o relatório ficará disponível para visualização.
Botões para ativar ou desativar a sincronização em lote das tabelas selecionadas na lista de objetos;

Anonimização de Dados, selecionar o tipo de anonimização que será aplicada. Para mais detalhes acessar a documentação do 2c, https://docs.carol.ai/docs/carol-connect-2c#section-data-anonymization

Ao finalizar o processo de configuração, o 2c começará a enviar os dados das tabelas do banco de dados para a referida Staging Table na Carol.

2.3.4.2 Diretório e Arquivos

Para adicionar arquivos na Carol pelo 2c precisamos adicionar um database do tipo Directory (Diretório)




Com as seguintes configurações:

• Connection Name: Nome da conexão;
• Carol Connector: Conector da Tenant;
• Folder Name: Diretório dos arquivos que serão sincronizados;
• File Filters: Filtros aplicados no diretório dos arquivos.

Ao concluir a configuração será criada uma nova conexão no 2c para o conector selecionado.

Na configuração de entidades o diretório selecionado será tratado como se fosse uma tabela, onde podemos aplicar filtros nos arquivos através de condições SQL (dados), para isso, precisamos informar para a conexão de arquivos qual é a conexão de dados.

Adicionando na campo de restrição SQL o seguinte comando: NOME_CONEXAO_DADOS#SELECT

Exemplo: Totvs Protheus#select A.ACB_OBJETO from ACB990 A inner join AC9990 B on B.AC9_CODOBJ = A.ACB_CODOBJ where B.AC9_ENTIDA = 'SRA'
Importante! O resultado do select precisa conter os nomes dos arquivos que serão enviados para a Carol.

2.3.5 Configuração por schedule (Cron)

Temos três tipos de Jobs / Schedule no 2c:

• Value (chave syncbytimestamp dentro do arquivo app.config.yml): por coluna de valor onde é validado o dado de forma incremental para sincronização na Carol, exemplo: campo de data / hora;

• Resync (chave syncbyresync dentro do arquivo app.config.yml): por confronto de PKs existentes (registros) na tabela do Banco de Dados com as PKs existentes (registros) na Staging Table criada na Carol.

Esse tipo de sincronização é mais custoso e demorado.
Na sync são 9 fases de processamento para enviar os dados para a Carol, sendo as principais fases:
1) Valida registros locais;
2) Valida os dados na Staging Table;
3) Valida os dados na Golden Record;
4) Válida os dados rejeitados;
5) Diferença dados x carga payload;
9) Limpeza dos dados.
Importante! As fases 6,7 e 8 são processos internos do 2c.

• Full Load (chave syncbyfullload dentro do arquivo app.config.yml): por carga geral, sempre será enviado todos os registros das tabelas e a Carol irá controlar o que é inclusão ou alteração de dados.

Para configurarmos JOB no 2c precisamos informar o tempo de execução utilizando a expressão Cron. Para montar a expressão utilize o seguinte website: https://www.freeformatter.com/cron-expression-generator-quartz.html

Criada a expressão em Cron, o próximo passo é alterar os respectivos valores das referidas chaves dentro do arquivo app.config.yml conforme o tipo de sync desejado.

2.3.6 Log de sincronização

Na página de gerenciamento do Connector é possível consultar o log de sincronização entre o 2c e o referido connector da Carol.

2.3.7 Documentação

https://docs.carol.ai/docs/carol-connect-2c

3. Aplicando ETL

Entrar na Staging Table e selecionar a opção ETL.

3.1 Função Duplicate

Duplicar uma Staging Table em duas Stagings Tables exatamente com os mesmos dados.

3.2 Função Join

Juntar duas Stagings Tables em uma Staging Table a partir de uma regra de junção.

3.3 Função Split

Separar uma Staging Table em duas ou mais Stagings Tables com os dados distribuídos a partir de condições configuradas.

4. Criando Modelos de Dados

4.1 Adicionando Data Model (DM)

No menu principal selecionar "Data Models", opção "All" e clicar no botão "Add a Data Model" no canto direito superior.

Passo 1: Escolher ou criar um projeto para o DM

Passo 2: Escolher ou criar um DM

São cinco tipos de Data Models:

Localização: modelo de dados relacionado à localização;
Organização: modelo de dados relacionado a empresas. Por exemplo: empresa, transportadores, empresas de transporte, etc;
Pessoa: modelo de dados relacionado a uma pessoa. Por exemplo: estudante, funcionário, etc;
Produto: modelo de dados que descreve produtos. Por exemplo: produtos, serviços, etc;
Transação: modelo de dados relacionado a dados transacionais, normalmente relacionados a uma data / hora específica. Por exemplo: recibos, tickets, eventos, pedidos, etc.

Passo 3: Escolher o segmento do negócio do DM

Passo 4: Informar o nome do DM

Passo 5: Confirmar a criação do DM

4.2 Criando Campos

1. Clicar no Botão "Add +";
2. Selecionar um campo pré-configurado;
3. Criar um novo campo, conforme as seguintes propriedades:
4. Label: Título do campo;
5. Description: Comentário do campo;
6. Field Name: Nome do campo;
7. Type: Tipos:

Boolean: Lógico;
Data: Data;
Long: Numérico Inteiro;
Nested: Várias instâncias de objetos;
String: Caracter;
Binary: Arquivo;
Enum: Classificação;
Object: Uma única instância de objeto;
Geopoint:Geo-localização (Longitude e latitude).

1. Tags: Rótulo para identificação do campo;
2. Flag Rules: Regra de aviso conforme condições definidas;
3. Skip Rules: Regra para ignorar valores recebidos no campo; Importante: Rejection ignora todo registro para o Data Model e o Skip ignora apenas o valor do campo.
4. Survive Rules: Regra de sobrevivência:

Oldest Value: Valor mais antigo;
Most Recent Value: Valor mais atual;
Most Frequently Updated: Valor atualizado frequentemente;
Survive File: Valor carregado por arquivo.

Estrutura final do Data Model Pessoas

4.3 Criando Regras de Validação

Após criar todos os campos no Data Model precisamos configurar as regras e permissões de como os dados serão tratados no referido Data Model.
Reorder Fields: Ordenar os campos.

Profile Title: Campo(s) para visualização principal do dado quando explorado dentro da Carol.

Tags = Palavras-chaves para identificar o Data Model.

Rejection Rules: Regra(s) em que o Data Model irá rejeitar os dados.
Condição "E"
(+ Add Rule) Condição "OU"

Merge Rules: Regra(s) para unificação dos dados e porcentagem (%) da proximidade e semelhança que será aplicado para a comparação.
Condição "E"
(+ Add Rule) Condição "OU"

Relationship: Relacionamento entre dois Data Models.

1. Selecionar os Data Models;
2. Selecionar os Campos Identificadores que farão a junção dos Data Models;
3. Apelido para identificar o relacionamento criado;
4. Salvar o relacionamento.

4.4 Agregação de Valores

Fazer o upload novamente da planilha Cidades, porém criando a Staging Table de Estados.



Criar o Data Model de Estados

Efetuar o mapeamento entre a Staging e DM de Estados.

Resultado. As 5.507 Cidades foram agrupadas dentro dos respectivos 26 Estados rejeitando o DF.

4.5 Publicando Data Model

Finalizar a criação de todos campos e as referidas regras o próximo passo é publicar o Data Model.

4.6 Opções do Data Model

4.6.1 Carol Data Storage

Enable: Habilita a gravação dos dados do DM no CDS;
Delete: Delete o armazenamento no CDS;
Export: Exporta os dados para o CDS

4.6.2 Timestamps

Habilita o registro de transações por timestamp.

4.6.3 Delete

Cuidado! Só é possível excluir um DM mediante confirmação.

4.7 Relacionamentos dos Data Models

Podemos visualizar todos os relacionamentos entre os DMs.

5. Mapeando Staging Table x Data Model

5.1 Criando Mapeamento

Para sincronizar os dados da Staging Table para o Data Model precisamos acessar a opção "Map & Cleanse" localizado dentro das opções da Staging Table.

Passo 1: Escolher o Data Model.

Passo 2: Carregar ou criar as regras de mapeamento.

Passo 3: Confirmar a criação do mapeamento.

5.2 Configurando Mapeamento

Fields: São os campos do Data Model;
Functions: Funções Carol para tratamento e/ou transformação dos dados;
Add Source: Campo(s) da Staging Table que será mapeado com o campo do DM;
Data Profiler: Visualizar o "valor" ou "tamanho" do dados após o mapeamento
Map Summary: Resumo e publicação do mapeamento efetuado.

5.3 Usando Funções

Funções Carol: Selecionar e arrastar a função na área correspondente para manipulação do dado.

Concatenação: adicionar os campos nome e sobrenome separados por "espaço em branco ", resultado da fórmula é apresentado no painel do lado direito.

Comparação, Condição e Atribuição de Valores: Se nascido até 1990 considerado "idoso" caso contrário "jovem".

Lookup: Buscar informações de outras fontes de dados (Staging ou Data Model) para mapeamento local.
Premissa a fonte externa precisa ser configurada como "lookup table".

Função Javascript: Caso não exista uma função Carol que atenda a necessidade de mapeamento é possível criar funções em javascript, para isso é preciso correlacionar os campos da Staging com os parâmetros de entradas da função e o return da função será o resultado final do mapeamento.

Importante! Toda vez que for adicionado ou alterado uma regra de mapeamento é preciso reprocessar os dados no DM para que a nova modificação seja aplicada.

5.4 Publicando Mapeamento

Ao finalizar o mapeamento é preciso revisar e publicar o conteúdo. Então os dados serão transformados em Golden Records e poderão ser explorados.

6. Utilizando Explorer

6.1 Acessando Explorer

No menu principal selecionar "Explorer", opção "All" para visualizar todos os Data Models ou acessar diretamente um DM clicando no referido nome.

6.2 Widget do Data Model

1. Total de Registros classificados como Golden;
2. Total de Registros classificados como Rejeitados;
3. Total de Registros unificados (Merge);
4. Total de Registros sinalizados (Flagged);
5. Total de Registros recomendados para unificação (Merge Recommended).

6.3 Navegando pelo Explorer

1. Criar Golden Record: Incluir diretamente no Data Model.

1. Reprocessar os Registros: Mover ou Copiar os dados novamente para a Staging Table de origem.

1. Apagar os dados do Data Model e mover para a Staging, então os dados serão reprocessados para o Data Model novamente;

1. Copiar os dados do Data Model para a Staging, então os dados serão reprocessados com merge para o Data Model outra vez.

1. Pesquisar: A palavra-chave é pesquisada em todas as colunas existentes no Data Model.

1. Filtrar:
2. Record Type: Por tipo de classificação do registro;

1. In Fields: Por quais colunas o pequisa vai buscar a palavra-chave;

1. Filter: Combinação de filtros.

1. Paginar os dados.

1. Page: Digitando o número da página que deseja carregar os dados;
2. Botões de navegação: Acessando a próxima página ou anterior.

1. Configurar quais colunas serão exibidas no grid.

1. Exportar os dados: Os dados de um Data Model podem ser exportados pelos seguintes tipos:

Importante: a exportação respeita o filtro realizado no explorer e limite máximo de 200 mil registros.

Quando finalizar a exportação dos dados o arquivo ficará disponível para download na central de atividades da Carol.

6.4 Criando Golden Record

Clicar no botão "create a golden record" ao explorar um determinado DM.

6.5 Alterando Golden Record

Na página de detalhe do registros clicar no botão de "edit record" (lápis)

6.6 Excluindo Golden Record

6.6.1 Direta

Na página de detalhe do registros clicar no botão de "delete record" (lixeira)

6.6.2 Movendo para Staging (Recomendado)

Pausar o processamento de dados na Staging que alimentar o referido DM.

Aplicar filtro para buscar os dados que serão excluídos.
Cuidado! Se não aplicar filtro todos os dados serão excluídos.

Clicar no botão "reprocess records" na opção "reprocess by moving to staging".

Ao reprocessar o dado será reenviado para a Staging

Na Staging que está pausada clicar no botão "drop table or delete records" (lixeira)

Será exibido as opções de exclusão da Staging, selecionar a opção "delete all realtime records".
Cuidado! Não selecionar a opção "drop staging table", pois será deletada a Staging e consequentemente será "quebrado" o Carol App Instalado na Carol.

Após exclusão dos dados é preciso reiniciar o processamento de dados na Staging.

Então, os dados serão apagados corretamente desde a sua origem.

7. Exibindo Insights

7.1 Criando Dashboard

No menu principal selecionar "Insights", opção "All" e clicar no botão "Create a New Dashboard" no canto direito superior.

Passo 1: Identificar o Dashboard com um nome.



Passo 2: Configurar as permissões.

Passo 3: Revisar e confirmar a criação.

Ao Finalizar os passos acima o widget do Dashboard será criado.

7.2. Criando Visões

Acessar o Dashboard criado clicar no botão "Add a new Insight" no canto direito superior.

Podemos adicionar no dashboard insights já criados ou criar novos.

Selecionar o Data Model responsável em fornecer as informações para o insight.

Configurar as propriedades do insight.

Dimensions: Dimensões são campos do tipo caracter;
Measures: Medidas são campos numéricos ou datas;
Filters: Filtro para exibição dos dados;
Chart Properties: Propriedades para exibição dos dados;
Show: Limitação para exibição das informações;
Order by: Ordenação dos dados;
Publish: Publicação do gráfico.

Exemplo de Dashboard com insights criados.

7.3 Usando Dashboard

Três pontinhos: Opções de gerenciamento do insight;
Detalhe no Insight: Seleção dos dados para exibição no "matching record list";
Filter: Filtro aplicado na exibição dos dados;
Matching Record List: Acesso rápido para explorar o dados selecionado.

8. Conhecendo o Swagger

8.1 O que é Swagger?

Ferramentas para projetar, criar, documentar e consumir serviços da Web via RESTful.
Toda Organization na Carol possui sua instância no swagger, adicionando o caminho /swagger-ui/ após a raiz da URL. Exemplo: {+}https://trainingcarol.carol.ai/swagger-ui/+

Access Token: Campo para inserir o token de autenticação gerado;
Organization ID: Campo para inserir o nome da organização para redirecionar a autenticação;
Tenant ID: Campo para inserir o nome do ambiente para redirecionar a autenticação.

8.2.Efetuando Requisição

A requisição 'oauth2/token' gera o token de validação e sua autenticação é pelo login na Carol

1. Endereço do endpoint;
2. Tipo de autenticação para gerar o token, no caso por 'password';
3. Connector Id na Carol;

1. E-mail de login;
2. Senha de login;
3. Domínio da tenant;
4. Botão para executar a requisição.

O token de acesso será enviado na resposta da requisição.

8.3 Autenticando o Acesso

Copiar e colar o token gerado na área de autenticação e sair do campo com o "tab" e se validado o semáforo mudará para a cor verde.

8.4 Recuperando Token ++

Recuperando token de acesso gerado pela plataforma usando o devtools (F12) do navegador.

1. Aba "Application";
2. Menu lateral "Local Storage";
3. Localizar o token do referido ambiente na coluna "Key";
4. Copiar a Chave de Autorização na coluna "Value".

9. Fazendo Queries na Carol

9.1 Endpoint

Requisição.

Resposta.

9.2 Query na Staging

Selecionar o indexType = STAGING.
<span style="color: #ff0000"><strong>Importante!</strong></span> o nome da tabela é composta por: ConnectorId+"_"+NameStagingTable
Exemplo: "select * from pessoas_user"
{
"mustList": [
{
"mdmFilterType": "TYPE_FILTER",
"mdmValue": "a6c76e1aa5dc429496cd0d293b928f44_pessoas_user"
}
]
}

9.3 Query no Data Model

Selecionar o indexType = MASTER.
Importante! o nome da tabela é composta por: DataModelName+"Golden"

SELECT

"select * from people"
{
"mustList": [
{
"mdmFilterType": "TYPE_FILTER",
"mdmValue": "pessoasGolden"
}
]
}

SELECT com WHERE

"select * from people where name like '%lucinda%'"
{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
},
{
"mdmFilterType":"MATCH_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.name.folded",
"mdmValue":"lucinda"
}
]
}

SELECT com JOIN e WHERE

"select a.* from pessoasGolden a inner join cidadesGolden b on b.code = a.citycode where b.code >= 5481"
{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
},
{
"mdmFilterType":"TERMS_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.citycode",
"mdmValuesField":"mdmGoldenFieldAndValues.code",
"mdmValuesQuery":{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"cidadesGolden"
},
{
"mdmFilterType":"TERMS_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.code",
"mdmValue":5481
}
]
}
}
]
}

SELECT com JOIN "RESOLVER" e WHERE

"select a.* from pessoasGolden a inner join cidadesGolden b on b.code = a.citycode where a.citycode = 5481"
{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
},
{
"mdmFilterType":"TERM_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.citycode",
"mdmValue":5481
}
],
"resolver":[
{
"type":"FETCH",
"fieldSource":"mdmGoldenFieldAndValues.citycode",
"fieldTarget":"mdmGoldenFieldAndValues.code",
"targetType":"cidadesGolden",
"resolvedName":"pessoascidades"
}
]
}

SELECT com JOIN "CAROL" e WHERE

"select a.* from pessoasGolden a inner join cidadesGolden b on b.code = a.citycode where a.citycode = 5481"
{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
},
{
"mdmFilterType":"TERM_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.citycode",
"mdmValue":5481
}
],
"resolveRelationships": true
}

SELECT com NOT EXISTS e WHERE

"select * from pessoasGolden a where not exists (select 1 from cidades b where b.code = a.citycode and b.state = 'TO')
{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
}
],
"mustNotList":[
{
"mdmFilterType":"TERMS_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.citycode",
"mdmValuesField":"mdmGoldenFieldAndValues.code",
"mdmValuesQuery":{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"cidadesGolden"
},
{
"mdmFilterType":"TERM_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.state",
"mdmValue":"TO"
}
]
}
}
]
}

SELECT com GROUP BY

{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
}
],
"aggregationList":[
{
"type":"TERM",
"name":"anos",
"size":1000,
"sortBy": "_term",
"sortOrder": "ASC",
"params":[
"mdmGoldenFieldAndValues.year.raw"
],
"subAggregations":[
{
"type":"SUM",
"name":"pessoas",
"params":[
"mdmGoldenFieldAndValues.code"
]
},
{
"type":"SUM",
"name":"cidades",
"params":[
"mdmGoldenFieldAndValues.citycode"
]
}
]
}
]
}

10. Criando Named Query

10.1 Utilizando Interface

Named queries (NQ) são views com passagem de parâmetros dinâmicos criadas na Carol.

"select * from people where name like '%parametro_name%' and city like '%parametro_city%'"
{
"excludeMergePending": false,
"filtering": true,
"indexType": "MASTER",
"minimumShouldMatch": 1,
"mustList": [
{
"mdmFilterType": "TYPE_FILTER",
"mdmValue": "pessoasGolden"
},
{
"mdmFilterType": "MATCH_FILTER",
"mdmKey": "mdmGoldenFieldAndValues.name.folded",
"mdmValue": "name"
}
],
"resolveRelationships": false
}

10.2 Utilizando Swagger

10.2.1 Criando NQ

Endpoint.

Requisição.

SELECT DM

"select * from people where name like '%parametro_name%'"
{
"excludeMergePending": false,
"filtering": true,
"minimumShouldMatch": 1,
"mustList": [
{
"mdmFilterType": "TYPE_FILTER",
"mdmValue": "pessoasGolden"
},
{
"mdmFilterType": "MATCH_FILTER",
"mdmKey": "mdmGoldenFieldAndValues.name.folded",
"mdmValue": "name"
}
],
"resolveRelationships": false
}

SELECT DM com GROUP BY e HAVING COUNT > 1

<span style="color: #ff0000"><strong>Importante! Para obter apenas o resultado da agregação é preciso passar o valor 0 (zero) no parâmetro pagesize.</strong></span>
"select year, count from people where year = {yearbirth} group by year having count > 1"
{
"mdmType":"pessoasGolden",
"mdmQueryName":"nqpessoasporanos",
"mdmQueryDescription":"",
"mdmQueryFields":{
},
"mdmFilterQuery":{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"pessoasGolden"
}
],
"aggregationList":[
{
"type":"TERM",
"name":"groupByYear",
"params":[
"mdmGoldenFieldAndValues.year.raw"
],
"minDocCount":2
}
],
"minimumShouldMatch":1,
"resolveRelationships":false,
"excludeMergePending":false
}
}

SELECT DM VIEW com WHERE

<span style="color: #ff0000"><strong>Importante! Executar a configuração explicada no próximo capítulo.</strong></span>
"select [Campos_Source], [Campos_Target] from data_model_view where campo_source_customercode = customercode and campo_target_mdmname = mdmname"
{
"mdmQueryName":"nqordersofcustomer",
"mdmQueryDescription":"",
"mdmQueryFields":{
},
"mdmFilterQuery":{
"mustList":[
{
"mdmFilterType":"TYPE_FILTER",
"mdmValue":"ordersofcustomer"
},
{
"mdmFilterType":"TERM_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.customercode.raw",
"mdmValue":"customercode"
},
{
"mdmFilterType":"TERM_FILTER",
"mdmKey":"mdmGoldenFieldAndValues.ordersofcustomer.mdmname.folded",
"mdmValue":"mdmname"
}
]
}
}

10.2.2 Executando NQ

Endpoint.

Requisição para a passagem de parâmetro.

11. Configurando Data Model View

11.1 Criando DM View

Endpoint para criação.

Endpoint para buscar "Mapping Id"

{
"mdmActions":[
{
"inputFieldname":"code",
"operation":"SUM",
"outputFieldname":"total"
}
],
"mdmName":"pessoasanos",
"mdmRelationshipMappingId":"302ae61123f142f9b3540be8386e6cb1",
"mdmRelationshipViewSourceEntityInputField":[
"code",
"name",
"year"
],
"mdmRelationshipViewTargetEntityInputField":[
"mdmcity",
"mdmstate"
]
}
mdmActions: Executa operação a partir de um campo do Data Model Source;
mdmName: Nome da view;
mdmRelationshipMappingId: Id do mapeamento, é como a view executa o join;
mdmRelationshipViewSourceEntityInputField: Campos do Data Model Source;
mdmRelationshipViewTargetEntityInputField: Campos do Data Model Target.

11.2 Reprocessando DM View

Qualquer alteração na estrutura da DM View é preciso reprocessar os dados.

11.3 Filtrando DM View

Endpoint para execução.

11.4 Filtrando por Query

Endpoint.

Selecionar o indexType = VIEW.
{
"mustList": [
{
"mdmFilterType": "TYPE_FILTER",
"mdmValue": "pessoasanos"
},
{
"mdmFilterType": "TERM_FILTER",
"mdmKey": "mdmGoldenFieldAndValues.name.folded",
"mdmValue": "lucinda"
},
{
"mdmFilterType": "TERM_FILTER",
"mdmKey": "mdmGoldenFieldAndValues.pessoas_cidades.mdmstate.raw",
"mdmValue": "MG"
}
]
}

12. Configurando NLP

No menu principal selecionar "NLP" opção "All".

12.1 Configurando Entidade

Entidade é o input da informação que será enviada pelo usuário através de texto ou voz.

1. Name: Nome da Entidade;
2. Connect to a Data Model: Input de dados a partir de um DM
   1. Select a Data Model: Selecionar o DM;
   2. Select a Field: Selecionar um campo do DM;
   3. Tokenize: Carol irá tratar todas as variantes dos valores de entrada do referido DM.
3. Add items to the ignore list: Entrada de dados que serão ignorados pela Carol;
4. Add a predefined values: Lista de valores pré-definidos para entrada de dados, como as palavras-chaves contidas nas perguntas vão fazer a Carol buscar as respostas.

Entidade com valor pré-definido

Entidade com valor dinâmico (DM)

12.2 Criando Skill

Onde a magia acontece, como fazemos a Carol nos entender.

1. Name: Nome da skill;
2. Entity: Entradas de dados que vão direcionar a Carol em fazer a busca da resposta;
3. Named Query Models: Como as informações serão buscadas na Carol:
   1. Model Name: Alias da configuração realizada;
   2. Named Query Name: Nome da named query criada;
   3. Number of Records: Número de registros que serão retornados;
   4. Input Params (Where): Relação da Entity com o parâmetro da Named Query:

Param: Nome do parâmetro na Named Query;
Value: Nome da Entidade criada para input.

1. 1. Output Params: Relação entre a variável de saída com o campo retornado na Named Query:

NQ Param: Variável criada para receber o valor de retorno;
Value: Como o valor será buscado na Named Query;
Idx: Índice de retorno começando por 0 (zero).

1. Example Question: Exemplo de como a pergunta deverá ser feita para a Carol;
2. Voice Message: Resposta que será dada pela Carol, onde o resultado buscado será mostrado na tag <ModelName:OutputParams>;
3. NLP Fallback Answers: Resposta padrão quando a Carol não souber responder.

12.3 Conversando com a Carol

Área de conversação com a Carol a partir das Entidades e Skills criados.

12.4 Histórico das Conversas

Toda interação com a Carol via NLP é gravado no histórico de perguntas e respostas.

Interessante! Ao clicar no registro o texto da pergunta é copiado para a área de transferência.

13. Carol App

13.1 Criando Carol App

No menu principal selecionar "Carol Apps", opção "All" e clicar no botão "Create an App".

13.1.1 Identificação

Preencher as informações necessárias para identificação do app.

Label: Descrição de exibição do App.
Name: Nome do App.
Version: Versionamento do App.
Description: Descrição do App;

13.1.2 Overview

Revisão de todos os componentes que compõe o Carol App.

13.1.2 Monitor

Monitoramento das tarefas de processamento incluídas no Carol App.

13.1.2 Settings

Criação de parâmetros para configurar o comportamento do Carol App

13.1.2 Files

Área de upload de arquivos para o Carol App, os arquivos podem ser dos seguintes tipo:

• WEB: Interface gráfica;
• AI: Algoritmo de inteligência Artificial.

13.1.2 Installation

Página para criar os pacotes de instalação do Carol App. Exemplo: Se o Carol Clock-in App será instalado para o ambiente Totvs Protheus ou Outro ERP.

13.2 Instalando / Atualizando Carol App

No menu principal selecionar "Carol Apps", opção "All" e clicar no botão "Available Apps".

Será apresentado os Carol Apps disponíveis para instalação / atualização

Próximo passo é selecionar o grupo de conectores que será instalado no Carol App.

Ao finalizar será apresentada da página de confirmação da instalação do Carol App.

Ao clicar no botão "go to app" podemos acompanhar a instalação.


Depois da instalação é necessário publicar o Carol App.

13.3 Gerenciando Carol App

Para gerenciar um Carol App podemos acessar via o botão "your apps" ou "carol apps" no menu principal.

13.3.1 Executando Tarefas

Aba "Overview" na seção "Process Management"

13.3.1.1 Execução Manual

Podemos executar manualmente a tarefa clicando no botão "run" exibido ao passar o mouse sobre ela.

13.3.1.2 Execução Agendada

É possível agendar as execução da tarefa clicando no botão "edit" exibido ao passar o mouse sobre ela.

Starts after: Data e Hora inicial que a tarefa será executada.

Repeats: Recorrência que será executada a tarefa.

Timezone: Em qual fuso horário a tarefa será executada.

Run as: Qual login será executada a tarefa.

Run schedule: Resumo das 5 próximas execuções.

13.3.2 Monitorando Tarefas

Quando uma tarefa é executada podemos acompanhar o log de execução das seguintes formas:

13.3.2.1 Área de notificação

13.3.2.2 Gerenciamento de Atividades

Página principal de monitoramento.

Podemos acessar o detalhe da execução ao clicar na referida tarefa.

Acompanhar os processamentos internos da tarefa na seção "logs"

Aplicar filtro de pesquisas para buscar o log desejado.

13.3.3 Parametrizando Carol App

Aba "Settings" é possível parametrizar o comportamento do Carol App no ambiente do cliente.

13.3.4 Carol Data Storage (CDS)

Os arquivos gerados pelo Carol App serão disponibilizados nessa seção.

13.3.5 Web Carol App

Se o Carol App possuir uma interface / página web podemos acessar através dos seguintes caminhos.

14. Carol Developer

Para ter acesso ao ambiente de desenvolvimento da Carol é preciso ter permissão "dev" no ambiente.

14.1 Jupyter Lab

É o ambiente oficial da Carol para desenvolvimento, pois a mesma foi adotada pela comunidade dos cientistas de dados. {+}https://jupyter.org/+
Pela Carol podemos gerenciar a VM do Jupyter Lab com as seguintes ações:



Manage Resource: Gerenciamento de recurso (máquina)

Start / Resume Instance: Cria ou inicia uma VM

Terminate Instance: Elimina a VM criada

14.2 Hello World

Iniciar um Python 3 Notebook

No menu de componentes selecionar o componente desejado e com o botão direito do mouse selecionar as funcionalidades pré-definidas pela Carol. Como exemplo vamos utilizar o employee DM (Funcionários)

Primeiro passo: Fazer o login dentro do ambiente.

Será criado o código fonte para efetuar o login na Carol, na variável "password" colocar sua senha registrada na Carol. Pressionar as teclas "Shift" + "Enter" para executar o comando.

Segundo passo: Fazer uma query nos dados de funcionários.

Será criado o código fonte para pesquisar os dados do employee DM. Pressionar as teclas "Shift" + "Enter" para executar o comando, se o comando for executado com sucesso o número de funcionários encontrado será exibido.

Terceiro passo: Formatar e exibir o resultado, para isso vamos transformar um resultado num DataFrame.

14.3 pyCarol

Biblioteca de APIs da Totvs Carol escritas em Python.
https://pycarol.readthedocs.io/en/latest/index.html