Herramientas de mapeo de archivos
¿Qué es una herramienta de mapeo de archivos?
El mapeo de archivos es uno de los tres tipos de herramienta que puedes crear en el Tool Builder de REDA AI. Es la opción adecuada cuando:
- Se procesa repetidamente el mismo formato de CSV (por ejemplo, una carga semanal desde otro sistema)
- Quieres un mapeo predecible que el agente no pueda cambiar en tiempo de ejecución
- No quieres escribir Apex
- El destino es un solo objeto de Salesforce: crear registros nuevos o actualizar registros existentes mediante una clave
El mapeo se define al crear la herramienta. En tiempo de ejecución, el agente solo elige el archivo que se va a importar; no puede rediseñar el mapeo, cambiar el objeto de destino ni alternar entre crear y actualizar. Eso hace que las herramientas de mapeo de archivos sean seguras para ponerlas al alcance de usuarios con menos experiencia y fáciles de gobernar.
Cómo funciona una herramienta de mapeo de archivos
-
Fijado en tiempo de diseño
Declaras el objeto de destino, la operación (crear o actualizar), el mapeo de columna a campo y —para actualizaciones— la clave de coincidencia. La plataforma almacena esto como un registro de metadatos personalizados de Definición de herramienta.
-
Contrato mínimo con el agente
El modelo solo ve una entrada en esta herramienta: el ID de ContentVersion del CSV que se va a importar. Todo lo demás está fijo.
-
El usuario carga el archivo
Un usuario carga o menciona un CSV en la conversación. El agente reconoce que este es el archivo que la herramienta necesita y propone la importación.
-
Confirmación de acción
Como las herramientas de mapeo de archivos escriben en Salesforce, se clasifican como herramientas de acción. El agente muestra una tarjeta de confirmación de acción antes de ejecutar, a menos que la opción Auto Execute File Actions esté habilitada en el agente.
-
Ejecución
Las importaciones pequeñas se ejecutan en línea y devuelven un resultado en el mismo turno de la conversación. Las importaciones más grandes se derivan a un trabajo por lotes que procesa el archivo de forma asíncrona.
-
Resultados por fila
Las importaciones se ejecutan en modo de éxito parcial. Las filas que se procesan correctamente se confirman; las filas que fallan se informan con el motivo. El usuario ve un resumen de las filas creadas, actualizadas y fallidas.
Configuración en tiempo de diseño
Las herramientas de mapeo de archivos se crean en el Tool Builder. Después de elegir la tarjeta de tipo File Mapping, completas cuatro bloques de configuración:
| Bloque | Qué defines |
|---|---|
| Objeto de destino | El objeto de Salesforce en el que se escribirán las filas. Estándar o personalizado: cualquiera al que el usuario que ejecuta tenga permitido acceder. |
| Operación | create para insertar registros nuevos, o update para actualizar registros existentes. No hay un modo upsert: update siempre busca la coincidencia con un registro existente mediante la clave de coincidencia. |
| Mapeo de campos | Para cada columna del CSV que quieras cargar, el nombre de API del campo en el objeto de destino. Las columnas que no se mapean se ignoran. Los encabezados distinguen mayúsculas de minúsculas y se recortan los espacios. |
| Clave de coincidencia (solo actualización) | El campo que se usa para encontrar el registro existente de cada fila. Elige Id de Salesforce si el CSV contiene Id de registros, o Id externo / campo único e indica el campo del objeto de destino con el que debe coincidir el valor del CSV. |
El Generador de IA del Tool Builder puede completar los cuatro bloques por ti cuando cargas un CSV de muestra junto con una breve descripción de lo que debe hacer la herramienta. Luego revisas y editas el mapeo generado antes de guardar.
Consulta Configuración de herramientas para ver el recorrido completo del Tool Builder: las tarjetas de tipo, el panel de impacto en vivo y el bloqueo de categoría.
Comportamiento en tiempo de ejecución
Qué ve el agente
El agente recibe una herramienta con una sola entrada: el ID de ContentVersion del CSV. El mapeo, el objeto de destino y la operación no se exponen al modelo; esto evita que el agente improvise cambios en el contrato de importación.
Ejecución en línea frente a por lotes
Los archivos pequeños se procesan en el mismo turno para que el usuario obtenga un resumen inmediato. Los archivos más grandes se derivan a un trabajo por lotes asíncrono. Cuando eso ocurre, el agente informa que la importación ha comenzado y que los resultados serán visibles en el registro de Acción programada resultante.
Éxito parcial
Las importaciones se ejecutan con el modo todo o nada desactivado. Una fila que no supera la validación, que infringe una regla de duplicados o que apunta a un registro que el usuario no puede editar se informa como un error de fila; el resto del archivo se carga de todos modos. El resumen que devuelve el agente indica cuántas filas se procesaron correctamente, cuántas fallaron y el motivo del primer conjunto de fallos.
Actualizaciones y coincidencia
Para las operaciones update, la plataforma busca los registros existentes mediante la clave de coincidencia:
- Id de Salesforce — la columna del CSV contiene el Id de 15 o 18 caracteres del registro y se aplica directamente.
- Id externo / campo único — la plataforma consulta en el objeto de destino los registros cuyo campo elegido es igual al valor del CSV. Sirve cualquier campo único; no se requiere un verdadero Id externo.
Las filas cuya clave de coincidencia no devuelve ningún registro se informan como errores de registro no encontrado. Las filas cuya clave de coincidencia devuelve varios registros se rechazan para evitar actualizaciones ambiguas.
Seguridad y gobierno
- Se aplica la seguridad a nivel de campo. Las importaciones se ejecutan en modo de usuario. Un campo que el usuario que ejecuta no puede editar fallará al momento de escribir y se informará como un error de fila.
- El mapeo es exclusivo del administrador. El agente no puede reescribir el mapeo de campos, cambiar el objeto de destino ni invertir la operación. Para cambiar cualquiera de estos, un administrador debe editar la Definición de herramienta.
- Confirmación de acción de forma predeterminada. Como cualquier otra herramienta de acción, las herramientas de mapeo de archivos muestran una tarjeta de confirmación de acción antes de ejecutarse, a menos que el agente esté configurado para Auto Execute File Actions.
- Registro de auditoría. Las ejecuciones en línea se registran en los registros de Conversación y Mensaje. Las ejecuciones por lotes también crean un registro de Acción programada y un informe de errores a nivel de fila.
Cuándo usar el mapeo de archivos frente a las alternativas
| Si necesitas… | Usa |
|---|---|
| Permitir que un usuario haga preguntas puntuales sobre un CSV sin importarlo | El patrón conversacional con herramientas integradas — consulta Procesamiento de documentos |
| Cargar filas de un CSV en un solo objeto de Salesforce usando un mapeo estable | Herramienta de mapeo de archivos (esta página) |
| Extraer de un archivo no tabular (PDF, imagen), conciliar con registros existentes, escribir en varios objetos o llamar a otro sistema | Una herramienta Apex con procesamiento de archivos — consulta Herramientas de clases Apex |
| Ejecutar una consulta SOQL parametrizada como herramienta | Una herramienta de plantilla SOQL — consulta Herramientas de plantillas SOQL |
Prácticas recomendadas
Mapea solo las columnas que necesites. Reduce el CSV a las columnas que la importación realmente usa. El agente también procesa el contenido del archivo, así que un archivo más liviano es más económico y más preciso.
Elige la clave de coincidencia más simple que funcione. Un Id de Salesforce es lo más confiable. Usa un campo externo o único solo cuando el sistema de origen no tenga Id de Salesforce para compartir.
Valida el mapeo primero con un archivo pequeño. Ejecuta la herramienta con una muestra de 5 a 10 filas antes de apuntarla a un archivo de producción. Los errores de fila son más fáciles de diagnosticar con volúmenes pequeños.
Sé deliberado con la ejecución automática. Las herramientas de mapeo de archivos escriben en Salesforce. Mantener el paso de confirmación de acción es la opción segura de forma predeterminada, salvo que el agente sea de uso interno únicamente y el formato del archivo se conozca bien.
Documenta el contrato en el nombre de la herramienta. Usa un nombre y una descripción en el Tool Builder que dejen claro el objeto de destino y la operación para los administradores futuros, por ejemplo “Importar cuentas (crear)” en lugar de “Herramienta de importación 1”.
Preguntas frecuentes
No. Cada herramienta de mapeo de archivos apunta exactamente a un objeto. Si necesitas cargar registros relacionados en varios objetos a partir del mismo archivo, usa en su lugar una herramienta Apex con procesamiento de archivos.
No. Las dos operaciones admitidas son create y update. Elige update cuando el archivo contenga una clave de coincidencia que identifique un registro existente.
La fila se omite y se informa como un error; el resto del archivo se carga de todos modos. El agente devuelve un resumen que indica cuántas filas se procesaron correctamente y cuántas fallaron, y muestra el primer conjunto de motivos de error.
No. El mapeo forma parte de la Definición de herramienta. Solo un administrador que edite la Definición de herramienta puede cambiar el mapeo, el objeto de destino, la operación o la clave de coincidencia.
Sí. Las importaciones se ejecutan en modo de usuario, con los permisos del usuario que las ejecuta. Los campos que el usuario no puede editar fallarán al momento de escribir y se informarán como errores de fila.
Se aplican las mismas opciones de Configuración de la plataforma que rigen los archivos cargados — Max File Size (MB) y Max CSV Characters. Por encima del umbral de ejecución en línea, las importaciones se ejecutan automáticamente en modo por lotes, en fragmentos, en lugar de hacerlo de forma síncrona.
El agente usa el archivo que el usuario cargó o mencionó en la conversación. Un nombre y una descripción de herramienta claros ayudan al agente a asociar el archivo correcto con la herramienta correcta cuando hay varios archivos en juego.
Próximos pasos
Lee Procesamiento de documentos para tener una visión más amplia de cómo fluyen los archivos por REDA AI, o Herramientas de clases Apex cuando tu lógica de importación supere las posibilidades del mapeo declarativo.