This article explains each strategy, shows the Salesforce use cases each one fits, and gives the sample resolution prompt to enter for each case. Use it when you are configuring a mapper that writes to an object with one or more lookup fields.
For the full configuration workflow this fits into, see Document Mapper Setup.
How lookup resolution works
Each lookup field on a mapper has an operation and, for Get Existing, a resolution strategy.
The operation controls the outcome:
| Operation | Result |
|---|---|
| Get Existing | Finds a record that already exists. Can optionally create one if nothing matches. |
| Create New | Always creates a new record and points the lookup at it. |
| Call Flow Action | Runs an autolaunched Flow you have built and uses the record it returns. |
For Get Existing, you describe your strategy in the resolution chat. CloudFiles converts your description into a deterministic execution plan and saves it with the mapper. At run time, CloudFiles follows the saved plan step by step. The AI reads the document and extracts values, but it does not decide which record matches. The comparison logic in the plan does that, which is why the same document and the same records always produce the same result.
Open the resolution chat by selecting the lookup field in the mapper's field list, choosing Get Existing, and typing your strategy in the chat box. The plan appears below the chat and updates as you refine it.
Strategy reference
1. Deterministic match
Purpose: Find a record by matching a value from the document against a field that uniquely identifies the record.
When to use it: The document carries an identifier that already exists on your Salesforce records. Tax IDs, customer account numbers, policy numbers, purchase order numbers are all good candidates.
What you need: A field on the target object holding that identifier, ideally marked as External ID and Unique.
Resolution prompt:
Match the 'Tax ID' extracted from the document against Tax_ID__c on Account.
Notes: This is the most reliable strategy and should be your first choice whenever the document contains an identifier. Because the match is exact, a formatting difference between the document and the record will cause a miss. If your records store tax IDs with separators and your documents do not, normalize one side before you rely on exact matching.
2. Fuzzy match
Purpose: Find a record by matching a name or description that will not be character-for-character identical, then narrow multiple candidates using additional fields.
When to use it: The document has no identifier and the only common value is a company name, person name, or address. Vendor invoices from small suppliers, signed forms, and scanned correspondence usually fall here.
What you need: The name field to match against, a similarity threshold, and at least one disambiguator field that appears both in the document and on the record.
Resolution prompt:
Fuzzy match the parsed 'Company Name' from the document against Account.Name
with a similarity threshold of 85%. If more than one Account matches,
disambiguate using BillingCity and BillingCountry that are present in the document.Notes: Always configure at least one disambiguator. Company names repeat across regions and legal entities, and a name-only match on a large Account table will return several candidates more often than admins expect. Set the threshold based on how clean your source documents are. Start at 85% and lower it only if you see false misses on documents you have inspected.
3. Context Reference
Purpose: Point the lookup at a record that CloudFiles already knows about at run time, without searching for it.
When to use it: Two situations, both of which use the same mechanism.
The first is a child record pointing back at its parent. When a mapper creates a parent record and its related child records in the same run, each child's lookup to the parent resolves to the parent created moments earlier in that run. Invoice and Invoice Line Items, Order and Order Products, Claim and Claim Items, all follow this shape.
The second is a record supplied by where the mapper was launched. When a mapper runs from a Salesforce record page, the ID of that page's record is available to the mapper. A lookup can point at it directly.
What you need: For the parent case, a child collection configured on the mapper. For the launch case, the mapper must be launched from a record page whose object type matches the lookup's target object.
Resolution prompt for the parent case:
Use the Invoice record created by this run.
Resolution prompt for the launch case:
Use the record from the page the mapper was launched from.
Notes: For the launch case, the object type must match. A lookup to Account will not resolve from a Case record page. Configure a fallback so the run does not fail when the mapper is triggered from somewhere else, such as a Flow or the API, where no page record exists.
4. Static Reference
Purpose: Point the lookup at the same fixed record on every run.
When to use it: The lookup represents a constant in your process rather than something that varies per document. Common cases include an intake channel record, a processing queue owner, a single legal entity in an org that only operates one, a default price book, or a partner record used for all documents from one source.
What you need: The Salesforce record ID of the target record.
Resolution prompt:
Always use the Intake_Channel__c record with ID a0X5g000004ABcDEA2.
Notes: Record IDs differ between sandbox and production. If you deploy mappers across environments, record the ID mapping in your deployment notes and update the strategy after each deployment. Where the constant record can be found by name, prefer a deterministic match on the name field instead, which survives deployment without edits.
5. Multi-strategy cascade
Purpose: Try several strategies in a defined order and use the first one that finds a record.
When to use it: Your documents arrive from mixed sources with varying quality. Some carry an identifier, some carry only a name, and some correspond to a customer who is not in Salesforce yet.
What you need: The inputs for each strategy in the chain, ordered from most reliable to least.
Resolution prompt:
First, match the parsed 'Tax ID' from the document against Tax_ID__c on Account. If no Account is found, fuzzy match the parsed 'Company Name' against Account.Name at 85% similarity and disambiguate using BillingCity. If still no Account is found, use the record from the page the mapper was launched from.
Notes: Order matters. Put deterministic steps before fuzzy steps so a clean identifier is never overridden by a name guess. Keep the chain short. Three steps plus a creation fallback covers almost every real case, and longer chains become hard to reason about when a run produces an unexpected result.
Choosing a strategy
Use this table to pick a starting point.
| What the document contains | What you know at run time | Strategy |
|---|---|---|
| A unique identifier that exists on your records | Nothing else needed | Deterministic match |
| A company or person name only | A second field to break ties | Fuzzy match |
| Nothing relevant to this lookup | The mapper creates the parent in the same run | Context reference, parent variant |
| Nothing relevant to this lookup | The mapper runs from the target record's page | Context reference, launch variant |
| Nothing relevant to this lookup | The record is always the same | Static reference |
| Different values depending on the source | Several of the above apply | Multi-strategy cascade |
| Nothing relevant to this lookup | A new record needs to be created at run time | Create New Record |
Handling ambiguity and failure
When a lookup cannot be resolved, the run is sent to the review queue. This applies both when no record matched and when more than one record matched. The run pauses with status Pending Review, and a reviewer opens it, picks the correct record or corrects the extracted value, and completes the run.
Every run is stored as a record of the CloudFiles_DocAI_Run__c object in Salesforce. Open the Doc AI Runs list view to see all runs alongside their status, the mapper configuration used, and the user who triggered them. Runs waiting on a lookup decision appear there with status Pending Review.