Configure and Use Image Scanner in Salesforce

Use Image Scanner when a Salesforce user must intentionally submit one image, or an ordered Front and Back pair, from a record page. The component can also collect optional notes for the agent.

Image Scanner uploads each image as a private Salesforce File. When the user selects Submit, it attaches the selected Front and optional Back to the current record and publishes one IMAGE_SCAN_SUBMITTED event. The provided Flow sends those images, notes, and related record to one background iDialogue agent run.

Choose the correct file-processing method

Keep existing file-processing Flows

Existing CONTENT_VERSION_INSERT handlers can remain active. For a handler that processes files on a business record, use the event fields below. Select All Conditions Are Met (AND) and replace Account with the intended object API name. No Get Records step is needed for these conditions.

The scanner's private upload still creates a CONTENT_VERSION_INSERT event. Its related business-record fields are blank, so it does not match these conditions. Its Origin remains apex; only the later IMAGE_SCAN_SUBMITTED event has Origin imageScanner. Adding the record link at Submit does not insert another ContentVersion. Use the original event fields even if the Flow receives the event after Submit. Later links do not change those fields. Do not query the file's current record links to replace this event context.

Blank related-record fields do not identify the scanner. Other private uploads and Library-only uploads can also have blank fields. Keep explicit Library and folder conditions for handlers that process Library files.

Salesforce File Attach handlers are separate. They can run when Submit attaches the selected images to the record. Review their conditions so they do not process the same images again. This feature does not add a scanner-source field to native File Attach events.

Before you start

Complete these requirements:

• Install an iDialogue package version that includes Image Scanner, the Image Scanner Event Handler Flow template, and the Supporting Content Version ID input on Run Agent Action (AI).
• The package must include private upload followed by attachment at Submit. Earlier scanner versions attach files during upload; the blank-related-record filter does not exclude those uploads. Upgrade before using this procedure.
• Configure an active iDialogue connection with available usage capacity.
• Configure the intended agent with a Background Model and the required All or Background instructions and tools.
• Give the administrator permission to edit Lightning record pages and create or activate Flows.
• Assign end users the iDialogue User permission set, or equivalent access to ImageScannerController, RunAgentAction, and the iDialogue Platform Event.
• Give end users permission to read the current record, upload and read Salesforce Files, and attach them to that record.
• Give the Salesforce connection user the permissions required for the agent's downstream record actions.

Use a sandbox or test record first. Use an agent whose expected actions are safe and visible.

Add Image Scanner to a Lightning record page

Image Scanner is a Lightning Record Page component. It is not a component for a traditional Salesforce page layout.

1. Open a record for the object that needs image capture.
2. Select Setup, and then select Edit Page.
3. Find Image Scanner in the custom components list.
4. Drag the component to the intended region of the Lightning record page.
5. Configure the component properties.
6. Select Save.
7. Select Activation and assign the page to the intended org default, Lightning apps, record types, and profiles.

For more information about page assignments, see Activate Lightning Record or Home Pages.

Add Image Scanner to a Lightning record page and configure the labels and capture options.

Configure the component properties

Blank text properties use the installed localized labels. These properties change only the component display. They are not included in the platform event and cannot route submissions to different agents.

For a business card, a typical configuration is:

For a receipt or photograph, clear Capture 2-Sided Content and give the Front image a use-specific label.

Configure the Image Scanner Event Handler Flow

The provided Image Scanner Event Handler is a platform event-triggered Flow template. Its path is:

iDialogue Platform Event
  -> IMAGE_SCAN_SUBMITTED Event?
      -> Run Card Scanner Agent

The Yes path handles IMAGE_SCAN_SUBMITTED; all other iDialogue event types end without running the agent.

Create the configured Flow

1. In Salesforce Setup, enter Flows in Quick Find, and then select Flows.
2. Open Image Scanner Event Handler and create an editable Flow from the template. Depending on your Salesforce release, select the template from New Flow or open it and select Save As.
3. Give the editable Flow an org-specific label and API name.
4. Keep the Start event set to iDialogue Platform Event.
5. Open IMAGE_SCAN_SUBMITTED Event? and keep this condition:

6. Open Run Card Scanner Agent.
7. Replace the packaged Business Card OCR Agent placeholder with the exact name of the intended Agent Studio agent. If agent names are not unique, clear Agent Name and use the intended Agent ID instead.
8. Preserve the file, record, notes, and background mappings.
9. Save the Flow.
10. Before activation, review all active platform event-triggered Flows. Leave exactly one active handler for each scanner submission.
11. Activate the configured Flow and test it with a safe record and safe agent.

The packaged template can be installed as Active. Before you activate an editable copy, deactivate the packaged handler or another handler that would also match the same event. Salesforce documents installed Flow status in Considerations for Flows Installed from Packages.

Preserve the Run Agent mappings

The Front image supplies the primary Content Document and Content Version. The Back image supplies the optional Supporting Content Version. The user's notes become the initial User Prompt. The related Account, Contact, Opportunity, or other record remains separate from both file IDs.

For the complete action contract, see Run Agent Action (AI) Flow Reference.

Route submissions carefully

The provided Decision matches every IMAGE_SCAN_SUBMITTED event. If different agents handle different Salesforce objects, add Related Record Type (rooms__RelatedRecordType__c) conditions, such as Account or Contact, and make the routes mutually exclusive.

Component labels are not event fields. Two Image Scanner components on the same object cannot be routed by their Label, Front Side Label, or Backside Label. Use one compatible agent or another explicit routing design for that case.

Submit a scan

1. Open the Salesforce record that contains Image Scanner.
2. Under the Front label, upload a .jpg, .jpeg, .png, .heic, or .heif image.
3. If a Back slot is shown, optionally upload a Back image. It must be different from the Front image.
4. Select Preview to review either Salesforce File.
5. Select Replace or Retake when the wrong image is selected, and then upload the replacement.
6. Enter optional notes or instructions for the agent. The limit is 4,000 Unicode characters.
7. If the microphone is shown, select it, speak, and review or edit the recognized text. Select the microphone again to stop. The component does not store audio.
8. Select Submit.
9. Read the submission receipt. Processing continues in the background, so you can leave the page or select Scan Another.

Review both images and the optional notes before selecting Submit.

The microphone appears only when the browser or Salesforce mobile environment supplies a compatible speech-recognition service. Type the notes when the microphone is not available or microphone permission is denied.

Understand uploaded Files

Each upload creates a private Salesforce File. It appears on the current record only after a successful Submit. Preview is available before Submit. The Front and optional Back keep their existing file IDs when they are attached.

Replace or Retake clears that image from the current scanner form. The replaced upload remains in your private Salesforce Files. An upload that you abandon without Submit also remains private. No automatic cleanup deletes these Files. Remove unwanted Files separately when your Salesforce permissions and retention rules allow it.

Scan Another resets the component after submission. It does not cancel background processing or delete the submitted Files from the record.

If a Back image is supplied, it must be a different Salesforce File from the Front. Each selected File must be readable and either already linked to this record or your own private upload. Submit validates the selected Files and adds the required record links before it publishes the event. Two-sided mode can submit Front without Back. One-sided mode ignores Back. The Account or other business record remains separate from both file IDs.

Verify the result

The submission receipt confirms that Salesforce accepted the Image Scanner platform event. It does not confirm that the Flow ran, OCR completed, the agent finished, or a Salesforce record changed. If the agent creates a completion Task, configure it to create that Task after successful processing. The receipt does not create a completion Task or confirm delivery of a mobile notification.

Use a test record and verify each stage:

1. Before Submit, confirm that the images can be previewed and do not appear in Files on the business record. Confirm that the business-record CONTENT_VERSION_INSERT handler does not process these private uploads.
2. After Submit, confirm that the selected images appear in Files on the correct record and exactly one active Flow matches IMAGE_SCAN_SUBMITTED.
3. Confirm that the Flow reaches Run Card Scanner Agent.
4. Confirm that the agent receives the correct primary image, supporting image, notes, and business record.
5. Confirm that the agent uses only the expected All or Background tools.
6. Review the expected dialogue, record update, task, file, or other business result.
7. In iDialogue Admin, review iDialogue Events with Event Type equal to ERROR when processing fails.

The absence of an error event does not prove completion. Verify the intended business result before retrying a submission.

Troubleshooting

For general file-processing errors, follow the monitoring guidance in File OCR with Run Agent. If you need help, submit a support request.