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.

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.

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.

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.

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.

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.

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

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 the Run Agent action

Use these settings for both Flow options:

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