> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Conectar fontes e organizar o Catálogo de Dados > Guia de configuração: conectar as fontes de dados da empresa ao console e preparar, no Catálogo de Dados, o que entra no contexto dos agentes. 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](#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 > [!WARNING] > > **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 | > [!NOTE] > > 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 1. Em **Conectores**, clique em **Nova Conexão**, no canto superior direito. 2. Na tela **Conectar Novo Conector**, procure a fonte em **Buscar integrações…** ① ou nos grupos **Bancos de Dados**, **Aplicações** e **Documentos**. 3. Clique no card do conector ②. ![Tela Conectar Novo Conector com a busca de integrações e os cards de bancos de dados](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/01-nova-conexao.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=729e66ed76bae0f621285d12123b0908) Figura 1. Tela Conectar Novo Conector: busca ① e card de um conector ②. > **[Documentação de conectores](https://docs.strattum.ai/connectors/overview.md)** > > 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). 1. Preencha os campos ①. 2. Leia a orientação abaixo dos campos ②. Ela explica como gerar a credencial na fonte. 3. Clique em **Testar Conexão** ③, na barra inferior. 4. 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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/02-conexao.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=c0c51e0451fb38d0523c42a0bc393c4d) 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 1. Abra **Frequência de Sincronização** ①. 2. Escolha o intervalo. O console marca com **(recomendado)** ② a opção indicada para aquele conector. 3. Clique em **Próximo**. ![Etapa Sincronização com a lista de frequências aberta](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/03-sincronizacao.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=df1d13a0c9fddac97e40b10f2615b256) 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 1. Em **Comportamento dos dados** ①, escolha como os registros aparecem para cada pessoa. 2. Em **Quem pode usar este conector** ②, escolha quem tem acesso ao conector. 3. 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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/04-permissionamento.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=395dac2d32ed5753d3f8dce829b57534) 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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/05-comportamento.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=f3b9829f0670ec5b5f7e6975139b4b09) ![Opções Todos os usuários e Apenas times específicos](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/05-quem-usa.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=ee95882dc27d916e8da0b8968edbcae8) Figura 5. Opções de cada campo da etapa Permissionamento: Comportamento dos dados (esquerda) e Quem pode usar este conector (direita). > [!WARNING] > > 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 1. Confira as seções **Conexão**, **Sincronização**, **Acesso** e **Teste de conexão**. Para corrigir algo, clique em **Editar** ① na seção. 2. Confirme que o teste de conexão mostra **Conectado** ②. 3. Clique em **Salvar Conector** ③. 4. 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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/06-revisao.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=4529e309b4fb35999f84da0584740aed) 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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/07-sucesso.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=0a0aa7a158837df15cfa72fec9cca9e2) Figura 7. Janela exibida depois de salvar: o que foi criado no catálogo ① e o botão Abrir Catálogo de Dados ②. > [!TIP] > > **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](#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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/08-arvore.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=1f1aefb19bda64af2181d7e2de1db11d) 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. > [!NOTE] > > 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. 1. Clique na tabela, na árvore. 2. Use a chave **No contexto** ① para ligar ou desligar a tabela inteira. 3. 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](https://mintcdn.com/strattumai/y6wEIa21nNtv9p_J/images/guides/connectors-catalog/09-schema.png?fit=max\&auto=format\&n=y6wEIa21nNtv9p_J\&q=85\&s=e9d22f9f0974c36584415d7e780d9e19) 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 ⑥. > [!NOTE] > > 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. > [!WARNING] > > 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**. > [!WARNING] > > 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 1. Com a revisão feita, clique em **Carregar dados** ⑥ (Figura 9). O botão aparece no conector e em cada tabela. 2. Acompanhe o andamento em **Conectores**, nas colunas **Status**, **Última Sincronização** e **Último Run**. 3. 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. > [!TIP] > > **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. | > [!NOTE] > > 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](https://docs.strattum.ai/admin/ontology-guide.md), no menu IA / Ops, para o Memory montar o grafo de entidades da sua empresa. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.