Suporte Okai

Aplica-se a: Gestão de fontes de dados e integrações do workspace que alimentam campos, formulários, listas controladas, automações e dados auxiliares usados na operação.

Fonte de dados é uma decisão de confiança

Configure uma fonte de dados quando um campo, formulário, lista ou automação precisa buscar valores de um lugar confiável em vez de depender de digitação livre. A fonte define quais valores podem ser usados, de onde eles vêm, quem pode vê-los, quem pode mantê-los e como a Okai deve reagir quando algo muda ou falha na origem.

Pense na fonte como um contrato operacional. Se uma lista de unidades, fornecedores, processos, categorias, áreas internas ou sistemas aparece em vários pontos do workspace, ela não deve ser reconstruída em cada formulário. Uma única fonte reduz divergência, evita valores escritos de formas diferentes e mantém a busca, os filtros e as automações falando a mesma língua.

A integração externa entra quando a informação oficial já vive em outro sistema. Nesse caso, a Okai consome os dados para apoiar a execução, mas a decisão mais importante continua sendo a mesma: qual sistema é a verdade para cada dado. Sem essa definição, a integração só movimenta inconsistência mais rápido.

Comece pela origem oficial: Antes de configurar campos ou automações, registre qual origem vence em caso de conflito. Se o cadastro corporativo diz uma coisa e uma planilha local diz outra, a fonte precisa refletir a autoridade correta, não a lista mais fácil de importar.

Quando usar lista, fonte interna ou integração

Nem toda escolha em um formulário exige integração. O melhor desenho é o mais simples que preserva governança, atualização e rastreabilidade. Uma lista controlada pequena pode ser mantida diretamente no workspace; uma base grande, volátil ou governada por outro time costuma pedir integração.

• Use lista controlada para valores estáveis e curtos, como prioridade, criticidade, tipo de evidência, canal, estágio ou classificação interna.
• Use fonte interna quando os valores pertencem ao workspace, precisam ser reaproveitados em vários formulários e têm responsável claro de manutenção.
• Use integração externa quando o dado oficial está em ERP, CRM, diretório corporativo, sistema regulatório, ferramenta de tickets, base de fornecedores ou outro repositório que já governa o ciclo de vida do cadastro.
• Evite integração para listas pequenas que mudam raramente. O custo de credenciais, monitoramento e tratamento de falhas pode ser maior que o benefício.
• Evite digitação livre quando a resposta precisa acionar automação, alimentar indicador, definir permissão, filtrar relatórios ou ser comparada depois.
• Não duplique uma lista só para mudar um rótulo em uma tela. Se a mesma entidade aparece em mais de um processo, ajuste a fonte, o campo exibido ou a regra de apresentação correta.

Integração não é validação automática: Receber dados de outro sistema não prova que eles estão corretos para o processo. Valide escopo, status, chaves, campos obrigatórios e significado de cada valor antes de tratar a integração como verdade operacional.

Decisões que precisam ficar claras

A configuração fica sustentável quando cada fonte responde a algumas perguntas antes de ser usada em produção. Essas decisões evitam listas abandonadas, permissões amplas demais e automações que falham justamente quando a rotina depende delas.

• Nome e finalidade: deixe claro que dado a fonte entrega e em quais processos ela pode ser usada.
• Responsável de manutenção: defina quem atualiza valores, revisa erros, aprova mudanças de escopo e decide aposentadoria da fonte.
• Origem oficial: indique se os dados são mantidos na Okai ou sincronizados de outro sistema, incluindo o contato técnico ou funcional da origem externa.
• Chave de identificação: escolha um identificador estável para cada registro. Nome visível pode mudar; a chave precisa continuar reconhecendo a mesma entidade.
• Campos exibidos: diferencie o valor técnico, o nome mostrado nos formulários e campos auxiliares usados para filtro, agrupamento ou automação.
• Escopo de uso: limite a fonte aos workspaces, áreas, formulários ou fluxos que realmente precisam dela.
• Permissões: trate a fonte como dado do produto. Quem pode selecionar um valor nem sempre deve enxergar todos os metadados ou editar a lista.
• Cadência de atualização: registre se a atualização é imediata, periódica, manual ou dependente de importação aprovada.
• Comportamento de valores inativos: decida se registros antigos continuam aparecendo em respostas já enviadas e se podem ser escolhidos em novos formulários.
• Plano de falha: defina o que acontece quando a origem externa fica indisponível, retorna erro ou envia dados incompletos.

Configurar sem perder controle

1. Mapeie o uso antes de criar a fonte: Liste os campos, formulários, automações e relatórios que dependerão do dado. Inclua também quem mantém a origem e quem será impactado se a lista mudar.
2. Crie a fonte com nome específico: Use um nome que explique a entidade e o escopo, como Fornecedores homologados, Unidades operacionais ou Categorias de risco. Nomes genéricos como Cadastro principal dificultam suporte e manutenção.
3. Escolha o tipo de alimentação: Para dados mantidos no workspace, cadastre ou importe os valores conforme o processo interno. Para integração externa, configure a conexão, credenciais, endpoint ou mecanismo disponível, respeitando as permissões do sistema de origem.
4. Mapeie identificadores e campos visíveis: Associe a chave estável ao registro e defina qual campo será exibido para seleção. Quando houver código e nome, mostre informação suficiente para evitar escolha errada, mas sem transformar o campo em uma ficha cadastral completa.
5. Aplique escopo e permissões: Libere a fonte somente para os contextos necessários. Se valores de uma área não podem aparecer para outra, resolva isso na fonte ou na permissão, não com orientação informal para ignorar opções.
6. Vincule a fonte aos campos certos: Substitua texto livre por seleção controlada nos formulários e campos que precisam de consistência. Se o campo já tem respostas antigas, avalie como elas serão interpretadas antes de alterar o tipo de entrada.
7. Teste atualização, busca e automação: Crie ou atualize um valor de teste na origem, confirme se ele aparece na Okai, selecione o valor em um formulário e verifique se filtros, regras e automações usam o identificador correto.
8. Documente a rotina de manutenção: Registre quem pode pedir inclusão, alteração, inativação ou correção. Uma fonte sem dono degrada aos poucos e costuma virar exceção manual.

Alterações em fonte usada merecem janela de validação: Renomear campos, trocar chaves, remover valores ou alterar filtros pode afetar formulários existentes, automações e relatórios. Faça primeiro uma validação com exemplos reais e confirme que registros históricos continuam compreensíveis.

Como validar antes de liberar

A validação não termina quando a conexão responde. Uma fonte está pronta quando entrega o valor certo para a pessoa certa, no contexto certo, e quando uma falha deixa sinal suficiente para diagnóstico. Teste com dados que representem a operação real, incluindo registros ativos, inativos, duplicados, com nomes parecidos e com campos obrigatórios ausentes.

• Confirme que a quantidade de registros recebidos faz sentido quando comparada à origem oficial.
• Pesquise por nomes com acento, abreviações, códigos e termos comuns para verificar se a seleção é encontrável.
• Abra um formulário que usa a fonte e teste a escolha com perfis diferentes de permissão.
• Verifique se valores inativos aparecem apenas onde deveriam: no histórico, em registros antigos ou em exceções permitidas.
• Dispare uma automação baseada no campo e confirme se ela lê a chave correta, não apenas o texto exibido.
• Revise logs, alertas ou mensagens de falha para saber se a equipe conseguirá agir quando a origem externa parar de responder.
• Peça validação funcional para quem conhece o cadastro. Erros de significado raramente aparecem só com teste técnico.

O teste mais útil: Escolha um caso real que já causou retrabalho: fornecedor com nome parecido, área reorganizada, categoria aposentada ou registro sem código. Se a nova fonte resolve esse caso sem ajuste manual, o desenho está mais próximo do uso diário.

Diagnóstico quando algo não aparece ou aparece errado

Quando um valor não aparece em um campo, investigue a cadeia inteira antes de corrigir a tela ou criar uma lista paralela. O problema pode estar na origem, no filtro da integração, na permissão, no status do registro, no mapeamento de campo, na última atualização ou no formulário que consome a fonte.

1. Confira se o registro existe na origem oficial: Procure pelo identificador estável, não apenas pelo nome. Se a origem não tem o registro ou ele está inativo, corrija primeiro no sistema responsável.
2. Revise filtros e escopo: Verifique se a integração limita por unidade, área, status, tipo ou data. Um filtro correto para um processo pode esconder dados necessários em outro.
3. Teste com o perfil afetado: Se administradores enxergam o valor e outras pessoas não, o caminho mais provável é permissão, escopo de workspace ou regra de visibilidade.
4. Compare chave e rótulo: Dois registros podem ter nomes parecidos ou o mesmo nome visível. Confirme se o campo usa a chave certa e se o rótulo exibido não está induzindo seleção errada.
5. Verifique a última atualização: Em fontes sincronizadas, veja quando a carga rodou pela última vez e se houve erro parcial. Dados novos na origem podem ainda não ter chegado à Okai.
6. Corrija na fonte certa: Se a classificação, o nome ou o vínculo está errado, ajuste a origem, o mapeamento ou a regra de integração. Evite criar substituições visuais para mascarar dado incorreto.

Lista duplicada vira dívida operacional: Criar uma nova lista para contornar uma falha costuma resolver a seleção de hoje e multiplicar inconsistência amanhã. Só faça isso quando a nova fonte representar uma entidade diferente, com dono e ciclo de vida próprios.

Manutenção contínua

Depois de liberada, acompanhe a fonte como parte da operação do workspace. Revise valores sem uso, registros duplicados, falhas recorrentes, pedidos de inclusão e campos que voltaram para texto livre. Uma fonte saudável diminui exceções; uma fonte esquecida cria atalhos fora do processo.

• Agende revisão periódica para fontes críticas, especialmente as que alimentam automações ou indicadores executivos.
• Mantenha histórico de mudanças relevantes, como troca de origem, alteração de chave, mudança de permissão ou desativação de valores.
• Oriente responsáveis por formulários a reaproveitar fontes existentes antes de criar novas listas.
• Ao aposentar uma fonte, confirme quais campos, formulários, relatórios e automações ainda dependem dela.
• Quando a integração depende de credenciais, acompanhe expiração, rotação de segredo e contato responsável pelo sistema externo.