Choose a developer integration
Decide how Record Health Check should run and where its results should go: on a Lightning record page, in a Flow or Apex process, in a background job, in an AI agent, or in a separate process that receives Platform Events. Every option runs the same Check Sets and Checks, configured once as Custom Metadata, and returns the same statuses.
Choose by who needs the result
Section titled “Choose by who needs the result”| Who or what needs the result | Use | Permission set the runner needs |
|---|---|---|
| A person looking at a record | The record-page card | Record Health Check Card User |
| A Flow that branches on the result | Flow actions | Record Health Check User |
| Apex code that needs the result before it continues | The Apex API | Record Health Check User |
| A background job for many records or on a schedule | Queueable, Batch, or Scheduled Apex | Record Health Check User |
| An Agentforce agent answering questions about a record | Agentforce actions | Record Health Check User |
| An external AI tool through the Model Context Protocol (MCP) | The MCP service and its REST API | Record Health Check MCP Integration |
| A separate Flow, Apex trigger, or external system after a run | Platform Events | Depends on what starts the run |
Every option also needs the running user’s normal access to the records and fields the Checks read. Record Health Check never runs with more access than that user.
flowchart TB
start(["Who needs the result?"])
person{"A person on a record page?"}
now{"Must a Flow or Apex process decide now?"}
many{"Many records, or on a schedule?"}
separate{"Must a separate process receive it?"}
card["Record-page card"]
sync["Flow action or Apex API"]
async["Queueable, Batch, or Scheduled Apex"]
events["Platform Events and receiving automation"]
start --> person
person -->|"Yes"| card
person -->|"No"| now
now -->|"Yes"| sync
now -->|"No"| many
many -->|"Yes"| async
many -->|"No"| separate
separate -->|"Yes"| eventsPlatform Events add to the other options: a card run, Flow, Apex call, or background job can also publish events for a separate process.
What each option returns
Section titled “What each option returns”| Option | Result | Can publish Platform Events |
|---|---|---|
| Record-page card | Rows and summary counts on the page | Yes, on Run or Rerun, when the card checkboxes are selected |
| Flow actions | Status, counts, Reason Code, and Result JSON outputs | Yes, with Event Publication ACTIONABLE or ALL |
| Apex API | rhc. with typed results and counts | Yes, with withEventPublication(. |
| Queueable, Batch, Scheduled | A job ID only; the packaged classes do not return results | Yes, with ACTIONABLE or ALL |
| Agentforce actions | Structured status, counts, and diagnostic fields for the agent | No |
| MCP service and REST API | Versioned JSON with status, counts, and diagnostic fields | No |
Statuses
Section titled “Statuses”Every option uses the same five statuses:
| Status | Meaning |
|---|---|
PASS | The record meets the requirement. |
FAIL | The record does not meet the requirement. |
SKIPPED | The Check did not apply, or its prerequisite did not pass. |
UNABLE_ | Access, configuration, or data prevented a reliable answer. |
ERROR | An unexpected problem stopped the Check. |
For a whole Check Set, the most serious status wins, in this order: ERROR, UNABLE_TO_EVALUATE,
FAIL, PASS, SKIPPED. Automation should decide from statuses, Reason Codes, and Qualified API
Names, never from message text that an administrator can change. See
Result labels and statuses.
Some problems, such as a missing permission or an unknown Check Set, stop the request before any
result exists. Flow returns them as Success false with an Error Type; Apex throws an
exception.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Records per Apex request or Flow group | 200 |
| Active Checks in a Check Set | 25 |
| Records in a packaged Queueable job | 200 |
| Records in a packaged Batch or Scheduled job | 2,000 |
| Formula evaluations per transaction | 95 |
| Check evaluations the card runs at once on one page | 8, shared by every card on the page |
Platform limitations states what happens when each limit is exceeded.
Versions
Section titled “Versions”Each output reports its own contract version, which changes only when that output’s shape changes, independently of the package version:
| Output | Contract version in 2.0.11 |
|---|---|
| Flow action Contract Version output | 2. |
| Agentforce action Contract Version | 1. |
REST API contractVersion | 1. |
| Platform Event Contract Version field | 1. |
Read the version from the output you process, and send an unexpected version to review.
Pair it with other Salesforce features
Section titled “Pair it with other Salesforce features”Record Health Check reports on records. These needs are met with other features:
| Need | How |
|---|---|
| Keep a result history | Record Health Check stores no results. Save them from Flow, Apex, or receiving automation in an object your team creates. |
| Block a record save | Record Health Check never blocks a save. Use a validation rule. |
| Fix records | Record Health Check never changes records. Link to the fix with the Check’s Action URL, or build automation that acts on a FAIL. |
| Run when a record changes | Record Health Check runs only when something starts it. Start it from a record-triggered Flow, Apex, or a job. |
| Rely on events | Salesforce can deliver an event more than once. Skip Event IDs you already saved, and monitor failures. |
| Give users access | Record Health Check never grants access. Give the running user access to the records and fields the Checks read. |