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 | If it does not resolve |
|---|---|---|
| Get Existing | Finds a record that already exists. It never creates one. | No match is handled by the fallback you select. Multiple matches always go to the review queue. |
| Create New | Always creates a new record from values extracted off the document and points the lookup at it. No matching is attempted. | Only a refused save can fail, and it goes to the review queue. |
| Call Flow Action | Runs an autolaunched Flow you have built and uses the record it returns. Because the Flow can hold any logic, it can search first and create only if nothing is found. | A null return goes to the review queue. |
Do not update if a value is already present sits above the resolution strategy and applies to all three operations. When it is checked and the lookup on the target record already holds a value, that value is kept and the document does not overwrite it. Use it when documents may be reprocessed and the link written the first time should win.
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. Until you do, Current Plan reads Not generated yet. The plan appears below the chat and updates as you refine it.
Create New has no resolution chat, because nothing is searched for. Instead you configure the fields the new record is created with — see strategy 6 below.
Strategy reference
Strategies 1 to 5 are resolution strategies you describe in the resolution chat under Get Existing. Strategy 6 is its own operation, configured with field mappings rather than a prompt.
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 covers almost every real case, and longer chains become hard to reason about when a run produces an unexpected result. A cascade runs entirely within Get Existing, so it cannot end in record creation. If unmatched documents should produce a record rather than wait for review, use Call Flow Action and put the search-then-create sequence in the Flow.
6. Create New
Purpose: Create a record from values extracted off the document and point the lookup at it, on every run.
When to use it: The lookup's target record is expected to be new each time, so searching for it is wasted work. Intake forms that introduce a supplier or applicant the org has never seen, staging objects where each document is meant to stand on its own, and per-document records such as a shipment or a submission all fit. If existing records should be reused where they exist, use a Get Existing strategy instead. If creation should happen only when nothing matches, use Call Flow Action.
What you need: Every required field on the target object, with an extraction prompt for each. Required fields appear in the New Record Fields list automatically and are marked with a red asterisk; the mapper cannot be saved until each one is configured.
What you configure: Create New is set up with field mappings rather than a resolution prompt.
- Select the lookup field, then select the Create New card.
- Under New Record Fields, configure each field. Each row shows the field label, its API name and type, and its extraction prompt beneath — for example,
Name · TEXT · find name of companyfor Account Name. Select a row to edit it. - Use Add a field to map… to populate optional fields at creation as well, such as BillingCity, a record type, or an external ID carried on the document.
- Review If creation fails. Documents whose record cannot be saved are sent to the review queue. This is fixed and cannot be changed, and it applies only when Salesforce itself refuses the save — a validation rule, a missing permission, a duplicate rule.
Notes: Create New has no other fallback. Nothing is searched for, so there is no no-match or multiple-match outcome to route; a refused save is the only failure. The trade-off is duplicates: the same entity appearing on two documents produces two records. Populate an external ID field in the New Record Fields list and back it with a Salesforce duplicate or matching rule if that matters for the object. Fill in more than the required fields where the document supports it — a record created with only a Name is harder to reconcile later than one carrying an address or an identifier.
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 |
| The details a new record needs | The record will not already exist | Create New |
| The details a new record needs | It may or may not exist, and creation must be conditional | Call Flow Action |
Handling ambiguity and failure
Each operation has exactly one way to fail, and every failure ends in the same place.
| Operation | Failure | Configurable |
|---|---|---|
| Get Existing | No record matched | Yes — select the behaviour under If no match is found |
| Get Existing | More than one record matched | No — always sent to the review queue |
| Create New | Salesforce refused the save | No — always sent to the review queue |
| Call Flow Action | The Flow returned no record Id | No — always sent to the review queue |
A run sent to the review queue pauses with status Pending Review. A reviewer opens it, picks the correct record or corrects the extracted value, and completes the run. For a Create New lookup, the reviewer can also pick an existing record instead of creating one.
Because only the no-match case is configurable, the fallback you choose there is the only lever you have on lookup failure. Everything else is decided by the plan, the object's validation rules, or the Flow.
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.