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.

Understand Run Context scope

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

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.

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, iDialogue 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 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.

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).

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 iDialogue Platform Event reference for the field schema. See iDialogue Platform Event types 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.

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. 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.

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

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 create the folder membership after the upload transaction. ContentVersionInsertEventQueue is a Queueable Apex job. The job checks the folder after the transaction commits. The job can make one retry after a minimum delay of one minute. A blank folder after the retry means that Salesforce did not supply a user-visible child folder. A Flow that requires Business Cards must not run for that fallback event.

A FutureHandler entry for ContentVersionTriggerHandler is the existing remote file synchronization process. The entry does not show that the folder Queueable ran. Look for ContentVersionInsertEventQueue in the Queueable Apex job or debug-log details.

The Run Agent action starts the server-side file-processing sequence. Server-side Ops logs start only after the Flow invokes the action and the API receives the request. Use the Content Version ID and orchestration ID to follow the request in Ops logs.

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