Ferramentas de mapeamento de arquivos
O que é uma ferramenta de mapeamento de arquivos?
O mapeamento de arquivos é um dos três tipos de ferramenta que você pode criar no Tool Builder da REDA AI. É a escolha certa quando:
- O mesmo formato de CSV é processado repetidamente (por exemplo, um envio semanal de outro sistema)
- Você quer um mapeamento previsível que o agente não possa alterar em tempo de execução
- Você não quer escrever Apex
- O destino é um único objeto do Salesforce — criar novos registros ou atualizar registros existentes por uma chave
O mapeamento é definido quando você cria a ferramenta. Em tempo de execução, o agente só escolhe o arquivo a importar; ele não pode reformular o mapeamento, alterar o objeto de destino ou alternar entre create e update. Isso torna as ferramentas de mapeamento de arquivos seguras para expor a usuários menos experientes e fáceis de governar.
Como funciona uma ferramenta de mapeamento de arquivos
-
Bloqueado em tempo de design
Você declara o objeto de destino, a operação (create ou update), o mapeamento de colunas para campos e — para atualizações — a chave de correspondência. A plataforma armazena isso como um registro de metadados customizados de Definição de Ferramenta.
-
Contrato mínimo com o agente
O modelo enxerga apenas uma entrada nessa ferramenta: o ID do ContentVersion do CSV a importar. Tudo o mais é fixo.
-
Usuário envia o arquivo
Um usuário envia ou referencia um CSV na conversa. O agente reconhece que esse é o arquivo de que a ferramenta precisa e propõe a importação.
-
Confirmação de ação
Como as ferramentas de mapeamento de arquivos gravam no Salesforce, elas são classificadas como ferramentas de ação. O agente exibe um cartão de confirmação de ação antes de executar — a menos que Auto Execute File Actions esteja habilitado no agente.
-
Execução
Importações pequenas rodam em linha e retornam um resultado no mesmo turno da conversa. Importações maiores são repassadas a um job em lote que processa o arquivo de forma assíncrona.
-
Resultados por linha
As importações rodam em modo de sucesso parcial. As linhas bem-sucedidas são confirmadas; as linhas com falha são reportadas com o motivo. O usuário vê um resumo das linhas criadas, atualizadas e com falha.
Configuração em tempo de design
As ferramentas de mapeamento de arquivos são criadas no Tool Builder. Depois de escolher o cartão de tipo File Mapping, você preenche quatro blocos de configuração:
| Bloco | O que você define |
|---|---|
| Objeto de destino | O objeto do Salesforce em que as linhas serão gravadas. Padrão ou customizado — qualquer objeto ao qual o usuário em execução tenha permissão de acesso. |
| Operação | create para inserir novos registros, ou update para atualizar registros existentes. Não há modo upsert — update sempre busca a correspondência com um registro existente usando a chave de correspondência. |
| Mapeamento de campos | Para cada coluna do CSV que você quer carregar, o nome de API do campo no objeto de destino. Colunas não mapeadas são ignoradas. Os cabeçalhos diferenciam maiúsculas de minúsculas e têm os espaços removidos. |
| Chave de correspondência (somente update) | O campo usado para localizar o registro existente de cada linha. Escolha Salesforce Id se o CSV contiver Ids de registro, ou External Id / campo exclusivo e informe o campo no objeto de destino com o qual o valor do CSV deve corresponder. |
O Gerador de IA do Tool Builder pode preencher os quatro blocos para você quando você envia um CSV de exemplo junto com uma breve descrição do que a ferramenta deve fazer. Em seguida, você revisa e edita o mapeamento gerado antes de salvar.
Consulte Configuração de ferramentas para o passo a passo completo do Tool Builder — os cartões de tipo, o painel de impacto em tempo real e o bloqueio de categoria.
Comportamento em tempo de execução
O que o agente vê
O agente recebe uma ferramenta com uma única entrada: o ID do ContentVersion do CSV. O mapeamento, o objeto de destino e a operação não são expostos ao modelo — isso impede que o agente improvise alterações no contrato de importação.
Execução em linha vs. em lote
Arquivos pequenos são processados no mesmo turno, de modo que o usuário recebe um resumo imediato. Arquivos maiores são repassados a um job em lote assíncrono. Quando isso acontece, o agente informa que a importação foi iniciada e que os resultados ficarão visíveis no registro de Ação agendada de IA resultante.
Sucesso parcial
As importações rodam com o modo tudo-ou-nada desativado. Uma linha que falha na validação, que viola uma regra de duplicidade, ou que tem como alvo um registro que o usuário não pode editar é reportada como erro de linha; o restante do arquivo ainda é carregado. O resumo retornado pelo agente lista quantas linhas tiveram sucesso, quantas falharam e o motivo do primeiro lote de falhas.
Atualizações e correspondência
Para operações update, a plataforma busca os registros existentes pela chave de correspondência:
- Salesforce Id — a coluna do CSV contém o Id de 15 ou 18 caracteres do registro e é aplicada diretamente.
- External Id / campo exclusivo — a plataforma consulta o objeto de destino em busca de registros cujo campo escolhido seja igual ao valor do CSV. Qualquer campo exclusivo funciona; um External Id verdadeiro não é obrigatório.
Linhas cuja chave de correspondência não retorna nenhum registro são reportadas como erros de não encontrado. Linhas cuja chave de correspondência retorna vários registros são rejeitadas para evitar atualizações ambíguas.
Segurança e governança
- A segurança em nível de campo é aplicada. As importações rodam em modo usuário. Um campo que o usuário em execução não pode editar falhará no momento da gravação e será reportado como erro de linha.
- O mapeamento é exclusivo do administrador. O agente não pode reescrever o mapeamento de campos, alterar o objeto de destino ou inverter a operação. Para alterar qualquer um desses itens, um administrador precisa editar a Definição de Ferramenta.
- Confirmação de ação por padrão. Como qualquer outra ferramenta de ação, as ferramentas de mapeamento de arquivos exibem um cartão de confirmação de ação antes de executar, a menos que o agente esteja configurado para Auto Execute File Actions.
- Trilha de auditoria. As execuções em linha são registradas nos registros de Conversa e Mensagem. As execuções em lote também criam um registro de Ação agendada de IA e um relatório de erros por linha.
Quando usar mapeamento de arquivos vs. as alternativas
| Se você precisa… | Use |
|---|---|
| Deixar um usuário fazer perguntas pontuais sobre um CSV sem importá-lo | O padrão conversacional com ferramentas integradas — veja Processamento de documentos |
| Carregar linhas de CSV em um único objeto do Salesforce usando um mapeamento estável | Ferramenta de mapeamento de arquivos (esta página) |
| Extrair de um arquivo não tabular (PDF, imagem), conciliar com registros existentes, gravar em vários objetos ou chamar outro sistema | Uma ferramenta Apex com processamento de arquivos — veja Ferramentas de classe Apex |
| Executar uma consulta SOQL parametrizada como ferramenta | Uma ferramenta de modelo SOQL — veja Ferramentas de modelo SOQL |
Boas práticas
Mapeie apenas as colunas de que você precisa. Reduza o CSV às colunas que a importação realmente usa. O agente também processa o conteúdo do arquivo, então um arquivo mais enxuto é mais barato e mais preciso.
Escolha a chave de correspondência mais simples que funcione. Um Salesforce Id é o mais confiável. Use um campo externo ou exclusivo apenas quando o sistema de origem não tiver Salesforce Ids para compartilhar.
Valide o mapeamento primeiro com um arquivo pequeno. Execute a ferramenta com uma amostra de 5 a 10 linhas antes de apontá-la para um arquivo de produção. Erros de linha são mais fáceis de diagnosticar em volumes pequenos.
Seja criterioso quanto ao Auto Execute. As ferramentas de mapeamento de arquivos gravam no Salesforce. Manter a etapa de confirmação de ação é o padrão seguro, a menos que o agente seja apenas interno e o formato do arquivo seja bem conhecido.
Documente o contrato no nome da ferramenta. Use um nome e uma descrição no Tool Builder que deixem claro o objeto de destino e a operação para futuros administradores, por exemplo “Importar Contas (Create)” em vez de “Ferramenta de Importação 1”.
Perguntas frequentes
Não. Cada ferramenta de mapeamento de arquivos tem como destino exatamente um objeto. Se você precisar carregar registros relacionados em vários objetos a partir do mesmo arquivo, use uma ferramenta Apex com processamento de arquivos.
Não. As duas operações suportadas são create e update. Escolha update quando o arquivo contiver uma chave de correspondência que identifique um registro existente.
A linha é ignorada e reportada como erro; o restante do arquivo ainda é carregado. O agente retorna um resumo com o número de linhas bem-sucedidas e com falha e mostra o primeiro lote de motivos de erro.
Não. O mapeamento faz parte da Definição de Ferramenta. Somente um administrador que edite a Definição de Ferramenta pode alterar o mapeamento, o objeto de destino, a operação ou a chave de correspondência.
Sim. As importações são executadas em modo usuário, sob as permissões do usuário em execução. Campos que o usuário não pode editar falharão no momento da gravação e serão reportados como erros de linha.
Aplicam-se as mesmas Platform Settings que regem os arquivos enviados — Max File Size (MB) e Max CSV Characters. Acima do limite de execução em linha, as importações passam automaticamente a rodar em modo de lote, em blocos, em vez de de forma síncrona.
O agente usa o arquivo que o usuário enviou ou referenciou na conversa. Um nome e uma descrição de ferramenta claros ajudam o agente a associar o arquivo certo à ferramenta certa quando vários arquivos estão em jogo.
Próximos passos
Leia Processamento de documentos para entender o panorama geral de como os arquivos fluem pela REDA AI, ou Ferramentas de classe Apex quando sua lógica de importação for além do mapeamento declarativo.