---
isPublished: true
template: "page.peb"
title: "Handle Salesforce Files with OCR and Run Agent"
displayName: "File OCR with Run Agent"
description: "Use a Salesforce file-attachment Flow and one Run Agent action to process an attached file with an DialogueOne agent."
category: "resources"
contentType: "article"
audience: "administrator"
tags: "salesforce,flow,run-agent,ocr,file-processing,heic,pdf"
section: "resources"
seoTitle: "Salesforce File OCR Automation with Run Agent"
seoDescription: "Configure a Salesforce file-attachment Flow to process images and documents with an DialogueOne agent."
---

# Handle Salesforce Files with OCR and Run Agent

Use this procedure to process a file after a user attaches it to a Salesforce record.

The file can be a business card, receipt, contract, application, invoice, form, photograph, or PDF.

OCR means optical character recognition. OCR changes text in an image or document into readable text.

The Flow uses one processing action: **Run Agent Action (AI)**. Supported images use **Analyze Image** automatically.
Other supported documents keep their existing text preparation. The agent uses your instructions, the file and the
related Salesforce record. Configure any business tools needed to create or update records.

```mermaid
sequenceDiagram
    actor User
    participant SF as Salesforce record
    participant Flow as Event-triggered Flow
    participant RunAgent as Run Agent action
    participant Agent as Background agent

    User->>SF: Attach image or document
    SF->>Flow: Send file event
    Flow->>RunAgent: Send file IDs, record ID, and agent
    RunAgent-->>Flow: Accept request
    RunAgent->>Agent: Start agent with image or prepared text
    alt Supported image
        Agent->>Agent: Convert HEIC when needed and analyze image
    else Other supported document
        Agent->>Agent: Use prepared document text
    end
    Agent->>SF: Use configured tools and rules
```

## Understand background processing

Salesforce starts both supported Flow types in real time. Flow Builder does not show a separate asynchronous path
for these Flow types.

Set **Run in Background** to `true`. This setting controls the DialogueOne agent. It does not control a Flow path.

The Run Agent action accepts the request. Then, DialogueOne processes the file outside the Flow transaction.

The Flow sends file IDs and a related record ID. Do not send the file content in a Flow input.

### Understand Run Context scope

Agent prompts and tools have a **Run Context** in Agent Studio. DialogueOne applies the same scope to both the
instructions sent to the model and the tools the model can invoke:

| Agent Studio Run Context | Available during Chat | Available during Background |
| --- | --- | --- |
| All or blank | Yes | Yes |
| Chat | Yes | No |
| Background | No | Yes |

File processing with this procedure runs in the Background context. Mark tools required by the file automation as
**All** or **Background**. Keep tools that require a live person, such as interactive questions or approval controls,
scoped to **Chat**.

You do not need to add Analyze Image in Agent Studio. DialogueOne reuses an eligible configured skill or provides it
automatically. Configure business tools such as `dml_sobjects` separately when record changes are required.

The dialogue transcript identifies the effective Run Context and lists **Runtime Tooling**, which contains only the
tools offered for that run. A blank request context remains Chat for compatibility with existing chat agents.

### Backwards compatibility

Run Context enforcement refines the scope of existing prompts and tools; it does not add a new context or require
agent metadata changes. Existing Chat agents continue to receive All and Chat items, and existing Background agents
continue to receive All and Background items. A tool intentionally marked All remains available in both contexts;
there is no function-name blacklist.

Older dialogues without a stored Run Context remain readable. If a previously queued continuation attempts a tool
that is no longer eligible in its effective context, DialogueOne returns a normal unavailable-tool result without
invoking the function. This prevents an interactive control, duplicate side effect, or worker exception while
compatible continuations proceed normally.

## Before you start

Make sure that these requirements are complete:

- Install an DialogueOne package version that shows **Process File Before Running Agent**.
- Install an DialogueOne package version that includes **Related Record ID** on the DialogueOne Event. This requirement
  applies only to the DialogueOne Platform Event option.
- Configure an active DialogueOne connection.
- Make sure that the connection has available usage capacity.
- Configure an DialogueOne agent with a background model.
- Add instructions for the file types that the agent must process.
- Add the Salesforce tools or business tools that the agent must use.
- Give the run-as user permission to read the file.
- Give the run-as user permission to read or update the related Salesforce record.
- Make the new Flow scope different from the scope of each other file-processing Flow.

Do not let two Flows process the same file upload. Two Flows can cause duplicate record changes.

Put classification and business rules in Agent Studio. For example, tell the agent how to identify a business card,
receipt, or contract. Also, tell the agent when a person must review the result.

## Select a Flow trigger

You can use one of these Flow types:

- **Automation Event-Triggered Flow**
- **Platform Event-Triggered Flow**

Both Flow types can start the same Run Agent action.

![Choose an Automation Event-Triggered Flow or Platform Event-Triggered Flow for OCR Agent processing](/assets/img/articles/ocr-agent/choose-event-triggered-flow.png)

### Option 1: Use a Salesforce Automation Event-Triggered Flow

Use the Salesforce **File Attach** event for a supported standard object. This option is usually the simplest option.
The event is already related to one parent object. It also supplies file filters.

1. In Salesforce Setup, open **Flows**.
2. Select **New Flow**.
3. Select **Automation Event-Triggered Flow**.
4. In the Event Library, select **File Attach**.
5. Select an object-specific event. For example, select **File Attach to Account**.

![Select an object-specific Salesforce File Attach automation event](/assets/img/articles/ocr-agent/select-native-file-attach-event.png)

6. Include the event fields that your entry conditions use.
7. Add the necessary file filters.

You can filter by file name, description, file type, file extension, owner, creator, or creation date. For example,
send only PDF and image files to a contract agent. You can also send all Account files to a general file agent.

![Configure native Salesforce File Attach event filters](/assets/img/articles/ocr-agent/configure-native-file-filters.png)

8. Add **Run Agent Action (AI)** after the Start element.
9. Map the Content Document ID to the matching Run Agent input.
10. Map the Content Version ID to the matching Run Agent input.
11. Map the attached business record ID to **Record ID**.

Salesforce does not currently supply File Attach automation events for custom objects. Use the DialogueOne Platform
Event option when the required parent object is not available. For more information, see
[Build Automation Event-Triggered Flows](https://help.salesforce.com/s/articleView?id=platform.automate_flow_build_create_automation_event_triggered_flow.htm&language=en_US&type=5).

### Option 2: Use an DialogueOne Platform Event-Triggered Flow

Use this option to keep record-upload processing separate from Image Scanner submissions, or when the Salesforce
File Attach event does not support the parent object.

1. Create a **Platform Event-Triggered Flow**.
2. Select the DialogueOne Event platform event.
3. Add a Decision element.
4. Set **Event Type** to `CONTENT_VERSION_INSERT`.
5. Set **Related Record Type** to the API name of the parent object. For example, use `Account`.

For business-record processing, select **All Conditions Are Met (AND)**:

| Event field | Operator | Value |
| --- | --- | --- |
| **Event Type** (`rooms__Type__c`) | Equals | `CONTENT_VERSION_INSERT` |
| **Related Record Type** (`rooms__RelatedRecordType__c`) | Equals | `Account`, or the intended object API name |
| **Related Record ID** (`rooms__RelatedRecordID__c`) | Is Null | `False` |

These event conditions exclude private uploads that have no related business record. Image Scanner versions with
private upload attach selected Files only at Submit and use `IMAGE_SCAN_SUBMITTED` for processing. Their insert
events retain **Origin** `apex`; do not filter those events by an `imageScanner` origin. Earlier scanner versions
attach during upload and require an upgrade for this behavior.

For example, a sales rep can submit business card images through Image Scanner on an Account. The scanner agent
receives both images and that Account. The rep can also upload an RFP through the Account's native Files component.
The Account insert-event handler sends that file to an RFP agent that creates a new Opportunity and its Tasks.
An RFP can also be an image, so file extension alone does not separate these workflows.

Keep Library-only routing separate; it does not require a related business record. Native Salesforce **File Attach**
handlers can run when scanner Submit adds record links, so review their conditions for duplicate processing. See
[Image Scanner Flow configuration](/support/idp/configure-image-scanner.html).

![Filter the DialogueOne event to ContentVersion inserts](/assets/img/articles/ocr-agent/filter-idialogue-content-version-event.png)

#### Route one Library folder by name

Use Library and folder conditions when one agent must process files from one Salesforce Library folder. A Salesforce
Library is a `ContentWorkspace` record.

For example, use these conditions to route business cards from the `AI Inbox` Library. Select
**All Conditions Are Met (AND)**.

| Event field | Operator | Value |
| --- | --- | --- |
| **Event Type** (`rooms__Type__c`) | Equals | `CONTENT_VERSION_INSERT` |
| **Content Workspace Name** (`rooms__ContentWorkspaceName__c`) | Equals | `AI Inbox` |
| **Content Folder Name** (`rooms__ContentFolderName__c`) | Equals | `Business Cards` |

A user can change a Library name or folder name. Two Libraries can have folders with the same name. Use
`rooms__ContentWorkspaceID__c` and `rooms__ContentFolderID__c` when the Flow needs stable and unique routing.

`rooms__RelatedRecordID__c` can be blank for a file that a user uploads only to a Library. Leave the **Record ID**
input blank when the agent does not need a related business record. Always map `rooms__ContentVersionID__c` and
`rooms__ContentDocumentID__c` to the matching Run Agent inputs.

See the [DialogueOne Platform Event reference](/support/events/index.html) for the field schema. See
[DialogueOne Platform Event types](/support/events/types.html) for the event-type list.

6. Add **Run Agent Action (AI)** to the matching Decision path.
7. Map the event fields as shown in this table.

| Run Agent input | DialogueOne Event field |
| --- | --- |
| Record ID | `rooms__RelatedRecordID__c` |
| Content Version ID | `rooms__ContentVersionID__c` |
| Content Document ID | `rooms__ContentDocumentID__c` |

For this event, `rooms__RecordId__c` contains the Content Version ID. Do not map this field to **Record ID**. Use
`rooms__RelatedRecordID__c` for the Account, Contact, Opportunity, or other related business record.

![Configure Run Agent from an DialogueOne ContentVersion platform event](/assets/img/articles/ocr-agent/configure-run-agent-action.png)

## Configure the Run Agent action

Use these settings for both Flow options:

| Input | Value |
| --- | --- |
| Agent ID or Agent Name | Select the DialogueOne agent that processes the file. |
| Record ID | Select the ID of the related business record. |
| Content Version ID | Select the Content Version ID from the event. |
| Content Document ID | Select the Content Document ID from the event. |
| Dialogue ID | Leave this input blank to start a new background dialogue. |
| User Prompt | Leave this input blank for general file processing. Use a prompt only for a narrow Flow purpose. |
| Run in Background | Set this input to `true`. |
| Process File Before Running Agent | Set this input to `true`. |

Do not put file content, credentials, or Salesforce IDs in **User Prompt**. Use Flow resources for all ID inputs.

For a general OCR Flow, leave **User Prompt** blank. The agent instructions must classify the file and select the
correct action.

Use a Flow prompt only when the Flow has one specific purpose. For example:

> Process this new Account file. Analyze the image or use the document text. Follow your configured instructions and tools.
> Do not guess missing values. Do not create duplicate records.

Keep these items in Agent Studio:

- Classification rules
- Data extraction rules
- Record update rules
- Duplicate prevention rules
- Tool instructions
- Human review rules

Do not copy these rules into each Flow.

## What happens after a file upload

1. Run Agent validates the request.
2. Run Agent accepts the background request.
3. Supported images start a file-aware agent. The agent analyzes the image for its assignment and converts HEIC or
   HEIF when needed. It can start before conversion happens.
4. Other supported documents use the existing text preparation before the agent starts.
5. The agent uses the findings, prompt and related record with its configured tools. Required analysis must succeed
   before related record changes. The original Salesforce file stays unchanged.

Images use Analyze Image in Chat and Background even when **Process File Before Running Agent** is disabled.
That setting still controls deferred document preparation. Explicit Extract Text actions and their events are unchanged.

| File type | Processing |
| --- | --- |
| PNG, JPEG/JPG, WebP, non-animated GIF | Automatic image analysis |
| HEIC, HEIF | Convert when needed, then analyze; reuse the conversion for later questions |
| PDF, TIFF, Excel, Word and supported text files | Existing document processing |
| Other formats, animated GIF or invalid image data | Existing unsupported-file handling or an image-analysis error |

## Monitor the request

Use **DialogueOne Events** in Salesforce to troubleshoot a failed request.

1. Open the Salesforce App Launcher.
2. Select **DialogueOne Admin**.
3. Open the **DialogueOne Events** tab.
4. Select a list view that has this filter: **Event Type** equals `ERROR`.
5. Create the filtered list view if it does not exist.
6. Review these fields:

   - **Subject**
   - **Action Type**
   - **Body**
   - **Content Version ID**
   - **Record ID**
   - **Agent**
   - **Created Date**

An error event contains a summary and a recommended action. It also contains available file and record IDs. The
**Body** field contains a reference ID for DialogueOne Support.

The error event does not contain file content or extracted text.

If you cannot see **DialogueOne Admin** or **DialogueOne Events**, assign the **iDialogue Admin User** permission set.

DialogueOne Events contains error records only. The absence of an error record does not show that processing is
complete. To verify success, review the expected agent response, record update, or other business result.

## Verify the result

Use a test record. Use an agent that makes safe and visible changes.

1. Attach a supported image or document to the test record.
2. Confirm that the Flow starts.
3. Confirm that DialogueOne accepts one Run Agent request.
4. Confirm that no related DialogueOne Event has **Event Type** equal to `ERROR`.
5. Open the original Salesforce file.
6. Confirm that the original file did not change.
7. Confirm that the agent uses information from the file correctly.
8. Confirm that the agent receives the correct related business record.
9. If transcript logging is enabled, confirm that the transcript shows **Run Context: Background**.
10. Confirm that **Runtime Tooling** contains only All and Background tools and does not contain Chat-only tools.
11. Confirm that the agent uses only the permitted tools.
12. Confirm that the agent makes only the expected record changes.

### Test file chat

1. Open the Content Version or Content Document record.
2. Find the Agent Assistant component.
3. Ask an agent to summarize the file.

4. For an image, ask a second visual question in the same dialogue. For example, first request console letters,
   then ask for red indicators. Confirm that both answers use the image correctly.
5. Ask the agent to put existing findings in a table. This can reuse the conversation without new image analysis.
6. For another document type, allow existing file preparation to finish if requested, then continue the dialogue.

Image processing can take time. You do not need to refresh or start a new dialogue for each image question. Identical
analysis requests can reuse completed results. A changed visual question can require new analysis of the same image.

Use representative test files. Examples include:

- A photograph of a business card
- A receipt
- A scanned contract
- A multiple-page PDF
- A supported iPhone HEIC image

## Understand file limits

OCR results depend on the file format, image quality, document layout, and visible text.

Some HEIC or HEIF variants are not supported. Test files from each device and source that your team uses.

DialogueOne does not change the original Salesforce file if file preparation fails.

Optional file-reading tools remain available to the agent. These tools can provide more file information. The Flow
does not require these tools.

## Troubleshooting

### Trace one Library upload

Use one test file with a unique file name. Start the Platform Event Flow debug session before you upload the file.
Flow debug can run the configured Apex action. Use an agent and file that are safe for testing.

Follow these checks in order:

1. Inspect the platform event in Flow debug.
2. Confirm that **Event Type** is `CONTENT_VERSION_INSERT`.
3. Confirm that **Content Version ID** and **Content Document ID** contain Salesforce IDs.
4. Confirm that **Content Workspace Name** is `AI Inbox`.
5. Confirm that **Content Folder Name** is `Business Cards`.
6. Confirm that the folder Decision uses **All Conditions Are Met (AND)**.
7. Confirm that the Flow takes the path to **Run Agent Action (AI)**.
8. Inspect the Run Agent outputs. Review **Success**, **Error Message**, and **Dialogue ID**.

Salesforce can make folder information available after an upload. If the folder is blank, verify the file's Library
and folder in Salesforce. A Flow that requires `Business Cards` must not match a blank folder. Confirm that the Flow
reaches Run Agent, then review its outputs and any related DialogueOne error event.

An DialogueOne Event record reports a request error or a terminal file-processing error. A successful request does not
create an DialogueOne Event record. The absence of an error record does not prove that the Flow matched the event or that
processing completed.

| Problem | Action |
| --- | --- |
| The Flow does not start. | Confirm that the selected File Attach event supports the parent object. For an DialogueOne event, confirm `CONTENT_VERSION_INSERT` and the object API name. |
| The Library-folder path does not run. | Use Flow debug. Confirm **Content Workspace Name**, **Content Folder Name**, and the AND condition. |
| No Run Agent result appears. | Confirm that the Flow reached **Run Agent Action (AI)**. Then review the action outputs and DialogueOne Events. |
| The agent receives the wrong record. | For an DialogueOne event, map `rooms__RelatedRecordID__c` to **Record ID**. Do not use `rooms__RecordId__c`. |
| Run Agent does not accept the request. | Check the DialogueOne connection, package access, usage capacity, selected agent, and background model. |
| File processing does not finish. | Open **DialogueOne Admin**. Select **DialogueOne Events**. Filter **Event Type** to `ERROR`. Review **Subject** and **Body**. |
| You need help from DialogueOne Support. | Send Support the reference ID and Content Version ID from the error event. Do not send file content unless Support requests it. |
| The agent does not take the expected action. | Check the Agent Studio instructions, related record, enabled tools, run-as permissions, and duplicate prevention rules. |
| The record updates two times. | Confirm that other file-processing Flows do not process the same file. For Image Scanner, check the business-record event conditions and any native File Attach handler. |
| An Experience Cloud upload causes a Flow error. | Confirm that the uploader has access to the platform event. |
