Conectar fontes e organizar o Catálogo de Dados

Este guia mostra como conectar as fontes de dados da sua empresa ao console da Strattum e como preparar, no Catálogo de Dados, o que entra no contexto dos agentes. A plataforma só lê as fontes, e os dados ficam no data lake do ambiente da sua empresa.

Como o dado chega aos agentes

Cada conector lê uma fonte e grava os dados no Catálogo de Dados, em duas camadas. A camada raw guarda o dado como veio da fonte. A camada clean guarda o dado normalizado, sem duplicatas e com chaves padronizadas, como CPF, CNPJ e e-mail. Memory, Knowledge e Skills leem da clean. Os detalhes estão em O que é a tabela clean.

Fonte  →  Conector  →  Raw  →  Clean  →  Agentes
          └─ Parte 1 ─┘  └── Parte 2 ──┘

O que você vai fazer

São duas partes, nesta ordem. Salvar o conector não inicia a carga de dados: antes de carregar, você revisa no catálogo as tabelas, as colunas e os dados pessoais.

Parte 1 · Conectores

1.1 Escolher o conector
1.2 Preencher a conexão e testar
1.3 Escolher a frequência de sincronização
1.4 Definir quem acessa os dados
1.5 Revisar e salvar o conector

Parte 2 · Catálogo de Dados

2.1 Conferir as tabelas do conector
2.2 Escolher o que entra no contexto
2.3 Marcar os dados pessoais (PII)
2.4 Ajustar a carga de cada tabela (opcional)
2.5 Selecionar as pastas (fontes de documentos)
2.6 Carregar os dados

Segurança. As credenciais ficam em cofre, no ambiente da sua empresa, e não aparecem de novo na tela. Use sempre um usuário somente leitura: a plataforma só lê as fontes. Não envie credenciais por e-mail, chat ou chamado.

Antes de começar

Separe estes itens antes de criar o primeiro conector. A última coluna indica o passo em que cada um é usado.

O que você precisa	Onde conseguir	Passo
Acesso de administrador ao console da Strattum	Guia de configuração de SSO e modelos de IA	1.1
Credencial somente leitura de cada fonte. Em bancos de dados, um usuário com `USAGE` e `SELECT` no schema (no MongoDB, a role `read`). Em aplicações, o token ou OAuth Client que a tela do conector pede	Administrador de cada fonte	1.2
Lista das colunas com dados pessoais: CPF, CNPJ, e-mail, telefone e campos de texto livre	Responsável pelos dados da sua empresa	2.3

Para começar, conecte um banco de dados ou CRM e uma fonte de documentos.

Parte 1 · Conectores

Você escolhe a fonte, testa a credencial, define a frequência e quem acessa os dados. O assistente tem quatro etapas: Conexão, Sincronização, Permissionamento e Revisão. Onde: Camada de dados › Conectores

1.1 Escolha o conector

Onde: Conectores › Nova Conexão

Em Conectores, clique em Nova Conexão, no canto superior direito.
Na tela Conectar Novo Conector, procure a fonte em Buscar integrações… ① ou nos grupos Bancos de Dados, Aplicações e Documentos.
Clique no card do conector ②.

Tela Conectar Novo Conector com a busca de integrações e os cards de bancos de dados — Figura 1. Tela Conectar Novo Conector: busca ① e card de um conector ②.

Documentação de conectores

Lista dos conectores disponíveis, com uma página para cada um: credenciais, permissões e campos de configuração. Consulte a página da sua fonte antes de preencher a conexão.

1.2 Preencha a conexão e teste

Onde: Etapa 1 de 4 · Conexão Cada conector pede campos próprios, e os campos com asterisco são obrigatórios. No Zendesk, por exemplo:

Campo	Preenchimento	O que informar
Nome do Conector	Opcional	Nome que aparece na lista de conectores.
Subdomínio	Obrigatório	O endereço da sua conta, antes de `.zendesk.com`.
Client ID e Client Secret	Obrigatório	Do OAuth Client criado no Zendesk.

Em bancos de dados, escolha entre URL de Conexão e Campos (host, porta, banco, usuário e senha).

Preencha os campos ①.
Leia a orientação abaixo dos campos ②. Ela explica como gerar a credencial na fonte.
Clique em Testar Conexão ③, na barra inferior.
Com o teste aprovado, clique em Próximo ④. O botão só libera depois de um teste bem-sucedido.

Etapa Conexão do Zendesk com os campos Nome do Conector, Subdomínio, Client ID e Client Secret — Figura 2. Etapa Conexão do Zendesk: campos ①, orientação da fonte ② e, na barra inferior, Testar Conexão ③ e Próximo ④. Os valores são exemplos.

1.3 Escolha a frequência de sincronização

Onde: Etapa 2 de 4 · Sincronização

Abra Frequência de Sincronização ①.
Escolha o intervalo. O console marca com (recomendado) ② a opção indicada para aquele conector.
Clique em Próximo.

Etapa Sincronização com a lista de frequências aberta — Figura 3. Etapa Sincronização: campo de frequência ① e opção recomendada ②.

Opção	Uso típico
A cada 10 min ou 15 min	Tickets de suporte, chat e filas de atendimento
A cada 1h	CRM, pipeline comercial e operação do dia a dia
A cada 6h	ERP e cadastros
Diário	Bases de referência e documentação
Semanal	Histórico e tabelas de apoio estáveis
Personalizado	Janela fixa, com expressão cron em UTC. Exemplo: `0 2 * * *` roda todo dia às 02:00 UTC.

A frequência vale para todas as tabelas do conector e pode ser mudada depois, sem reprocessar o histórico. Frequência mais alta traz dados mais atuais, mas consome mais chamadas de API da fonte. Fontes com limite diário de API podem atingir o teto.

1.4 Defina quem acessa os dados

Onde: Etapa 3 de 4 · Permissionamento

Em Comportamento dos dados ①, escolha como os registros aparecem para cada pessoa.
Em Quem pode usar este conector ②, escolha quem tem acesso ao conector.
Clique em Próximo.

Campo	Opção	O que acontece
Comportamento dos dados	Aberto	Quem tem acesso ao conector vê todos os registros copiados da fonte.
	Espelhar a fonte	Cada pessoa vê apenas os registros que a própria fonte libera para ela.
Quem pode usar este conector	Todos os usuários	Qualquer pessoa da empresa pode usar este conector.
	Apenas times específicos	Só os times que você selecionar. Os times são criados em Configurações › Workspace › Times.

Etapa Permissionamento com os campos Comportamento dos dados e Quem pode usar este conector e um aviso sobre o espelhamento — Figura 4. Etapa Permissionamento: comportamento dos dados ①, quem pode usar o conector ② e aviso sobre o espelhamento de permissões ③.

Opções Aberto e Espelhar a fonte — Figura 5. Opções de cada campo da etapa Permissionamento: Comportamento dos dados (esquerda) e Quem pode usar este conector (direita).

Opções Todos os usuários e Apenas times específicos — Figura 5. Opções de cada campo da etapa Permissionamento: Comportamento dos dados (esquerda) e Quem pode usar este conector (direita).

Com Espelhar a fonte, os registros sincronizados ficam invisíveis no console e no chat até o primeiro espelhamento de permissões rodar ③. Isso é esperado: a permissão de cada registro vem da fonte.

Nem toda fonte oferece as duas opções de comportamento. No PostgreSQL, por exemplo, o comportamento é fixo em Aberto.

1.5 Revise e salve o conector

Onde: Etapa 4 de 4 · Revisão

Confira as seções Conexão, Sincronização, Acesso e Teste de conexão. Para corrigir algo, clique em Editar ① na seção.
Confirme que o teste de conexão mostra Conectado ②.
Clique em Salvar Conector ③.
Na janela Conector configurado com sucesso!, clique em Abrir Catálogo de Dados (Figura 7).

Etapa Revisão com as seções Conexão, Sincronização, Acesso e Teste de conexão — Figura 6. Etapa Revisão: Editar ①, resultado do teste de conexão ② e, na barra inferior, Salvar Conector ③. Os valores são exemplos.

Janela Conector configurado com sucesso com o resumo do que acontece agora e o botão Abrir Catálogo de Dados — Figura 7. Janela exibida depois de salvar: o que foi criado no catálogo ① e o botão Abrir Catálogo de Dados ②.

Parte 1 concluída. Ao salvar, o console cria e habilita no Catálogo de Dados as tabelas clean padrão do conector, quando ele tem. Salvar não inicia uma carga de dados. Antes de carregar, faça a revisão da Parte 2.

Parte 2 · Catálogo de Dados

Antes da primeira carga, você escolhe as tabelas e as colunas que entram no contexto e marca os dados pessoais. Depois, carrega os dados. Onde: Camada de dados › Catálogo de Dados

2.1 Confira as tabelas do conector

Onde: Catálogo de Dados › Árvore de tabelas A árvore à esquerda da tela separa as tabelas em Raw, agrupadas por conector, e Clean.

① Tabela ativada. Num conector novo, as tabelas raw usadas pelas cleans padrão já vêm no contexto.
② Tabela esmaecida. Fica fora do contexto até você selecionar.
③ Clean. Tabelas tratadas a partir da raw, que alimentam os agentes. Veja O que é a tabela clean, logo abaixo.

O resumo no topo da página mostra quantas tabelas raw estão no contexto e quantas já têm dados. Antes da primeira carga, ele mostra “nenhuma com dados”.

Árvore do Catálogo de Dados com tabelas raw do Zendesk e o grupo Clean — Figura 8. Árvore do catálogo: tabela ativada ①, tabela fora do contexto ② e grupo Clean ③.

O que é a tabela clean

A raw guarda o dado exatamente como veio da fonte e não muda depois da carga. A clean é a versão tratada desse dado: a cada carga, a plataforma lê a raw, aplica as regras da clean e grava o resultado no data lake do ambiente da sua empresa. Memory, Knowledge e Skills leem da clean.

Limpa duplicidade

Cada registro vira uma linha, com os valores atuais. Um cliente editado várias vezes na fonte aparece uma vez só para os agentes.

Unifica as fontes

Coloca as chaves no mesmo formato em todas as fontes, como e-mail em minúsculas e sem espaços, e CPF e CNPJ num padrão único. Assim, o cliente que está no CRM e no helpdesk com o mesmo e-mail vira uma pessoa só no Memory.

Prepara para a ontologia

Entrega cada tabela com o identificador do registro na fonte, na coluna external_id, e com as colunas de identidade, como e-mail. A ontologia usa essas colunas para criar as entidades e as relações entre elas.

Exemplo. Uma pessoa cadastrada num CRM, antes e depois da clean:

O que muda	Na raw	Na clean
Alterações	O registro chega com o histórico de edições de cada campo	Uma linha por pessoa, com os valores atuais
E-mail	`Ana.Souza@Exemplo.COM`	`ana.souza@exemplo.com`
Vários e-mails	Todos no mesmo campo	O principal na coluna `email` e todos numa tabela auxiliar
Identificador	Com o nome que a fonte usa, como `record_id`	`external_id`, com o mesmo nome em todas as cleans

Ao salvar um conector, a plataforma cria as cleans padrão dele, quando ele tem. Elas aparecem no grupo Clean do catálogo, com o nome do conector no início, como zendesk_tickets. Ao abrir uma clean, Fontes mostra de quais tabelas raw ela lê, e a aba SQL mostra a regra que gera a tabela.

Para juntar fontes numa tabela só ou criar uma tabela própria, use Nova clean, no topo do catálogo. Você escolhe as fontes, escreve o SQL ou pede ao construtor da clean, pode adicionar colunas geradas por IA e confere a prévia antes de salvar. Esse passo é opcional e costuma ser feito com o FDE da Strattum.

2.2 Escolha o que entra no contexto

Onde: Catálogo de Dados › Tabela › Aba Schema Só o que está no contexto chega aos agentes.

Clique na tabela, na árvore.
Use a chave No contexto ① para ligar ou desligar a tabela inteira.
Na aba Schema, use a coluna No contexto ② para ligar ou desligar cada coluna. Tirar todas do contexto ③ desliga todas de uma vez.

Tabela raw zendesk.organizations no catálogo, com a aba Schema, as colunas PII e No contexto e o botão Carregar dados — Figura 9. Tabela raw no catálogo: chave No contexto da tabela ①, chave por coluna ②, Tirar todas do contexto ③, coluna PII ④, aba Carga ⑤ e Carregar dados ⑥.

Colunas obrigatórias, como a chave primária, ficam sempre ativas. As alterações valem a partir da próxima carga. A linha Alimenta, no topo da tabela, mostra quais cleans dependem dela.

2.3 Marque os dados pessoais (PII)

Onde: Catálogo de Dados › Tabela › Aba Schema Na aba Schema, a coluna PII ④ tem três opções para cada campo (Figura 9):

Opção	Quando usar	O que acontece
Sem PII	Campo sem dado pessoal	O valor é gravado como veio da fonte.
Coluna inteira	Identificador: CPF, CNPJ, e-mail ou telefone	O valor vira um token, na mesma coluna.
Campo livre	Texto livre que pode conter dado pessoal	O texto fica, e cada dado pessoal vira um marcador, como `[CPF]` ou `[EMAIL]`.

O token é gerado com uma chave da instalação, guardada no ambiente da sua empresa.

Marque os dados pessoais antes de clicar em Carregar dados. Mudar a marcação depois de uma carga faz a tabela ser relida inteira, e desmarcar não devolve os valores já tokenizados até a carga seguinte terminar.

2.4 Ajuste a carga de cada tabela (opcional)

Onde: Catálogo de Dados › Tabela › Aba Carga Na aba Carga ⑤, o card Configuração da carga define como a tabela é atualizada a cada sincronização.

Modo	Como funciona	Quando usar
Carga completa	A cada carga, substitui todos os dados da tabela raw pelos dados atuais da fonte.	Tabelas pequenas ou fontes que apagam registros
Incremental	Carrega só o que mudou desde a última carga, a partir da coluna de cursor.	Tabelas grandes, com coluna de alteração confiável

No modo Incremental, informe o Cursor, a coluna que indica quando a linha mudou (em geral updated_at), e a Chave Primária, que evita linhas duplicadas. Escolha também como o cursor avança: pelo horário da execução, que é a opção mais segura, ou pelo maior valor lido, só quando a coluna de cursor é confiável. Depois, clique em Salvar configuração da carga.

No modo incremental, linhas apagadas na fonte continuam no catálogo, e alterações que não atualizam o cursor não são percebidas. A coluna de cursor precisa registrar quando a linha foi gravada.

Alguns conectores controlam a carga sozinhos e não mostram essa opção, como GitHub, Notion e Google Drive.

2.5 Selecione as pastas (fontes de documentos)

Onde: Catálogo de Dados › Conector de documentos Em conectores de documentos, como o Google Drive, clique no conector na árvore e defina o Modo de leitura em Documentos no catálogo:

Opção	O que entra no catálogo
Todas as pastas	Tudo o que a conta de serviço acessa. É o padrão recomendado.
Pastas selecionadas	Só as pastas marcadas, com as subpastas.

Depois de escolher, clique em Salvar seleção.

2.6 Carregue os dados

Onde: Catálogo de Dados › Conector ou tabela

Com a revisão feita, clique em Carregar dados ⑥ (Figura 9). O botão aparece no conector e em cada tabela.
Acompanhe o andamento em Conectores, nas colunas Status, Última Sincronização e Último Run.
Volte ao catálogo. As tabelas raw passam a mostrar o número de linhas, e as cleans deixam de mostrar “nenhum dado importado”.

Status do conector	Significado
Conectado	A última execução terminou bem. O Último Run mostra Concluída.
Sem execuções	O conector ainda não rodou.
Erro	A última execução falhou. O Último Run mostra Falhou: confira a credencial e a rede.

A primeira carga é completa e pode levar alguns minutos, conforme o volume. Depois dela, a sincronização segue a frequência escolhida no passo 1.3.

Parte 2 concluída. Os dados do conector estão no Catálogo de Dados, com as colunas certas no contexto e os dados pessoais protegidos.

Como confirmar que deu certo

Em Conectores, o conector aparece como Conectado, e o Último Run mostra Concluída.
No Catálogo de Dados, as tabelas raw no contexto mostram o número de linhas.
As colunas com dados pessoais estão marcadas na coluna PII.
As tabelas clean do conector mostram dados.
Com Espelhar a fonte, depois do primeiro espelhamento, cada pessoa vê só os registros que a fonte libera para ela.

Se algo não funcionar

Sintoma	O que conferir
O teste de conexão falha com conexão recusada	Libere os IPs de saída da plataforma no firewall ou no security group da fonte.
Falha de autenticação	Confira usuário, senha e acesso ao banco ou à aplicação.
O banco exige SSL	Ative a opção de SSL na conexão.
Erro 401 Unauthorized	Gere um novo token ou OAuth Client com os escopos corretos.
Os registros não aparecem logo depois da carga, com Espelhar a fonte	É esperado até o primeiro espelhamento de permissões rodar.
Uma tabela esperada não aparece	Pode ser uma view, que não é listada, ou faltar permissão de `USAGE` e `SELECT` no schema.
Uma tabela parou de sincronizar depois de marcar PII	Falta configurar a chave de tokenização da instalação. Fale com o FDE da Strattum.
A tabela clean continua sem dados	Confira se a carga terminou e se as tabelas raw de origem estão no contexto e com linhas.

Se o problema continuar, fale com o FDE da Strattum que acompanha a sua implantação e envie um print da tela com o erro. Antes de enviar, confira que nenhuma credencial aparece no print.

Próximo passo

Com os dados no catálogo, configure a Ontologia, no menu IA / Ops, para o Memory montar o grafo de entidades da sua empresa.

Deploy

Instalação

Configuração

Guias de configuração

Conectar fontes e organizar o Catálogo de Dados

Como o dado chega aos agentes

O que você vai fazer

Parte 1 · Conectores

Parte 2 · Catálogo de Dados

Antes de começar