File Mapping Tools
What is a File Mapping Tool?
File Mapping is one of the three tool types you can build in the REDA AI Tool Builder. It is the right choice when:
- The same shape of CSV is processed repeatedly (e.g. a weekly upload from another system)
- You want a predictable mapping the agent cannot change at runtime
- You don’t want to write Apex
- The destination is a single Salesforce object — create new records, or update existing records by a key
The mapping is defined when you build the tool. At runtime the agent only chooses the file to import; it cannot reshape the mapping, change the target object, or switch between create and update. That makes File Mapping tools safe to put in front of less-experienced users and easy to govern.
How a File Mapping Tool Works
-
Locked at design time
You declare the target object, the operation (create or update), the column-to-field mapping, and — for updates — the match key. The platform stores this as a Tool Definition custom metadata record.
-
Minimal agent contract
The model only sees one input on this tool: the ContentVersion ID of the CSV to import. Everything else is fixed.
-
User uploads file
A user uploads or references a CSV in the conversation. The agent recognises that this is the file the tool needs and proposes the import.
-
Action confirmation
Because File Mapping tools write to Salesforce, they are categorised as Action tools. The agent shows an action confirmation card before executing — unless Auto Execute File Actions is enabled on the agent.
-
Execution
Small imports run inline and return a result in the same conversation turn. Larger imports are handed off to a batch job that processes the file asynchronously.
-
Per-row results
Imports run in partial-success mode. Rows that succeed are committed; rows that fail are reported with the reason. The user sees a summary of created, updated and failed rows.
Design-Time Configuration
File Mapping tools are built in the Tool Builder. After choosing the File Mapping type card, you complete four configuration blocks:
| Block | What you set |
|---|---|
| Target Object | The Salesforce object the rows will be written to. Standard or custom — anything the running user is allowed to access. |
| Operation | create to insert new records, or update to update existing records. There is no upsert mode — update always matches against an existing record using the match key. |
| Field Mapping | For each CSV column you want to load, the field API name on the target object. Columns that aren’t mapped are ignored. Headers are case-sensitive and trimmed. |
| Match Key (update only) | The field used to find the existing record for each row. Pick Salesforce Id if the CSV contains record Ids, or External Id / unique field and name the field on the target object that the CSV value should match. |
The Tool Builder’s AI Generator can fill all four blocks for you when you upload a sample CSV alongside a short description of what the tool should do. You then review and edit the generated mapping before saving.
See Configuring Tools for the full Tool Builder walkthrough — type cards, the live impact panel, and category locking.
Runtime Behaviour
What the agent sees
The agent receives a tool with a single input: the ContentVersion ID of the CSV. The mapping, target object and operation are not exposed to the model — this prevents the agent from improvising changes to the import contract.
Inline vs batch execution
Small files are processed in the same turn so the user gets an immediate summary. Larger files are handed off to an asynchronous batch job. When that happens, the agent reports that the import has started and that results will be visible on the resulting Scheduled Action record.
Partial success
Imports run with all-or-nothing turned off. A row that fails validation, that violates a duplicate rule, or that targets a record the user cannot edit is reported as a row error; the rest of the file still loads. The summary the agent returns lists how many rows succeeded, how many failed, and the reason for the first batch of failures.
Updates and matching
For update operations the platform looks up existing records by the match key:
- Salesforce Id — the CSV column contains the record’s 15- or 18-character Id and is applied directly.
- External Id / unique field — the platform queries the target object for records whose chosen field equals the CSV value. Any unique field works; a true External Id is not required.
Rows whose match key returns no record are reported as not-found errors. Rows whose match key returns multiple records are rejected to prevent ambiguous updates.
Security & Governance
- Field-level security is enforced. Imports run in user mode. A field the running user cannot edit will fail at write time and be reported as a row error.
- The mapping is admin-only. The agent cannot rewrite the field mapping, change the target object, or flip the operation. To change any of these, an administrator must edit the Tool Definition.
- Action confirmation by default. Like every other Action tool, File Mapping tools surface an action confirmation card before running, unless the agent is configured for Auto Execute File Actions.
- Audit trail. Inline runs are recorded on the Conversation and Message records. Batch runs also create a Scheduled Action record and a row-level error report.
When to Use File Mapping vs the Alternatives
| If you need to… | Use |
|---|---|
| Let a user ask ad-hoc questions about a CSV without importing it | The conversational pattern with built-in tools — see Document Processing |
| Load CSV rows into one Salesforce object using a stable mapping | File Mapping tool (this page) |
| Extract from a non-tabular file (PDF, image), reconcile against existing records, write to multiple objects, or call out to another system | An Apex tool with file processing — see Apex Class Tools |
| Run a parameterised SOQL query as a tool | A SOQL Template tool — see SOQL Template Tools |
Best Practices
Map only the columns you need. Trim the CSV down to the columns the import actually uses. The agent processes the file content too, so a leaner file is cheaper and more accurate.
Pick the simplest match key that works. A Salesforce Id is the most reliable. Use an external or unique field only when the source system has no Salesforce Ids to share.
Validate the mapping with a small file first. Run the tool against a 5-10 row sample before pointing it at a production file. Row errors are easier to diagnose at small volume.
Be deliberate about Auto Execute. File Mapping tools write to Salesforce. Leaving the action confirmation step in place is the safe default unless the agent is internal-only and the file shape is well understood.
Document the contract on the tool name. Use a Tool Builder name and description that makes the target object and operation obvious to future admins, e.g. “Import Accounts (Create)” rather than “Import Tool 1”.
Frequently Asked Questions
No. Each File Mapping tool targets exactly one object. If you need to load related records across objects from the same file, use an Apex tool with file processing instead.
No. The two supported operations are create and update. Choose update when the file contains a match key that identifies an existing record.
The row is skipped and reported as an error; the rest of the file still loads. The agent returns a summary listing successful and failed row counts and shows the first batch of error reasons.
No. The mapping is part of the Tool Definition. Only an administrator editing the Tool Definition can change the mapping, target object, operation or match key.
Yes. Imports run in user mode under the running user’s permissions. Fields the user cannot edit will fail at write time and be reported as row errors.
The same Platform Settings that govern uploaded files apply — Max File Size (MB) and Max CSV Characters. Above the inline-execution threshold, imports automatically run in batch mode in chunks rather than synchronously.
The agent uses the file the user has uploaded or referenced in the conversation. A clear tool name and description help the agent match the right file to the right tool when several files are in play.
Next Steps
Read Document Processing for the broader picture of how files flow through REDA AI, or Apex Class Tools when your import logic outgrows declarative mapping.