---
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 iDialogue 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 iDialogue 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)**. iDialogue gets the file and prepares its text. Then,
iDialogue starts the selected agent. The agent receives the file text and the related Salesforce record as context.

```mermaid
sequenceDiagram
    actor User
    participant SF as Salesforce record
    participant Flow as Event-triggered Flow
    participant RunAgent as Run Agent action
    participant Service as iDialogue file processing
    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->>Service: Prepare file in background
    Service->>Service: Convert image when necessary
    Service->>Service: Extract readable text
    Service->>Agent: Send file text and record context
    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 iDialogue agent. It does not control a Flow path.

The Run Agent action accepts the request. Then, iDialogue 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.

## Before you start

Make sure that these requirements are complete:

- Install an iDialogue package version that shows **Process File Before Running Agent**.
- Install an iDialogue package version that includes **Related Record ID** on the iDialogue Event. This requirement
  applies only to the iDialogue Platform Event option.
- Configure an active iDialogue connection.
- Make sure that the connection has available usage capacity.
- Configure an iDialogue 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 legacy OCR 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 iDialogue 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 iDialogue Platform Event-Triggered Flow

Use this option when the Salesforce File Attach event does not support the parent object.

1. Create a **Platform Event-Triggered Flow**.
2. Select the iDialogue 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`.

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

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

| Run Agent input | iDialogue 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 iDialogue 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 iDialogue 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. Use the document text in context. 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. iDialogue gets the referenced Salesforce file.
4. iDialogue keeps the original Salesforce file unchanged.
5. iDialogue converts a supported HEIC or HEIF image when conversion is necessary.
6. iDialogue extracts readable text from the file.
7. iDialogue starts the background agent.
8. The agent receives the prompt, file text, and related Salesforce record as context.
9. The agent follows its instructions and uses its permitted tools.

## Monitor the request

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

1. Open the Salesforce App Launcher.
2. Select **iDialogue Admin**.
3. Open the **iDialogue 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 iDialogue Support.

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

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

iDialogue 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 iDialogue accepts one Run Agent request.
4. Confirm that no related iDialogue 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. Confirm that the agent uses only the permitted tools.
10. 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.

On first access, the agent can show this response:

> Give me a minute (or two) to analyze this file. First time I've seen this. It should be available for chat soon.

4. Wait for the file processing to finish.
5. Refresh the page, or start a new dialogue.
6. Ask the agent to summarize the file again.
7. Confirm that the agent uses the prepared file text.

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.

iDialogue 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

| Problem | Action |
| --- | --- |
| The Flow does not start. | Confirm that the selected File Attach event supports the parent object. For an iDialogue event, confirm `CONTENT_VERSION_INSERT` and the object API name. |
| The agent receives the wrong record. | For an iDialogue event, map `rooms__RelatedRecordID__c` to **Record ID**. Do not use `rooms__RecordId__c`. |
| Run Agent does not accept the request. | Check the iDialogue connection, package access, usage capacity, selected agent, and background model. |
| File processing does not finish. | Open **iDialogue Admin**. Select **iDialogue Events**. Filter **Event Type** to `ERROR`. Review **Subject** and **Body**. |
| You need help from iDialogue 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 a legacy OCR Flow and the new Run Agent Flow do not process the same file. |
| An Experience Cloud upload causes a Flow error. | Confirm that the uploader has access to the platform event. |