Developer guides
Run Record Health Check from Apex, background jobs, AI agents, and external systems, and extend it with your own Apex Checks. Record Health Check is the open-source Salesforce package that shows on a Lightning record page whether a record meets requirements an administrator configures; these guides cover everything beyond the card and the Flow actions.
Every guide runs Check Sets and Checks that already exist as Custom Metadata. Create and test them on the record-page card first: see Configure Check Sets and Checks.
Choose a guide
Section titled “Choose a guide”| Need | Guide |
|---|---|
| Compare every way to run Record Health Check | Choose a developer integration |
| Use the result in Apex before the transaction continues | Run Record Health Check from Apex |
| Check up to 200 known records in a later transaction | Run Record Health Check from Queueable Apex |
| Check many records in groups | Check many records with Batch Apex |
| Check records on a schedule | Run Record Health Check from Scheduled Apex |
Move existing @future code | Replace a Future method with Queueable Apex |
| Write a Check that a formula or query cannot express | Write a custom Apex Check |
| Test a custom Apex Check before activating it | Verify a custom Apex Check |
| See complete, tested Apex Check classes | Apex Check examples |
| Let an Agentforce agent or an MCP client use results | Agentforce and MCP |
| Receive Platform Events outside Salesforce | Receive events with Pub/Sub API |
To branch on a result without code, use the Flow actions instead.
Names in your code
Section titled “Names in your code”Record Health Check is a namespaced unlocked package with the namespace rhc. Two prefixes come
from it:
| Prefix | Where it appears | Example |
|---|---|---|
rhc. | Before every package Apex type in your code | rhc. |
rhc_ | In the API names of package objects and fields, and of Check Sets and Checks that install with the package | rhc_, rhc_ |
A Check Set or Check that your organization creates has no prefix, such as Account_Data_Quality.
Use the exact Qualified API Name; Names and API identities shows where to find it. Never
add or remove rhc__ yourself.
Permissions
Section titled “Permissions”Every way of running Checks requires the Record Health Check Run custom permission
(rhc__Record_Health_Check_Run). Assign the permission set that matches how the user runs Checks:
| Permission set | Use it for |
|---|---|
| Record Health Check Card User | The record-page card only. |
| Record Health Check User | The card, Flow, Apex, background jobs, and Agentforce actions. |
| Record Health Check MCP Integration | The REST endpoint that the MCP server calls. |
| Record Health Check Admin | Everything in User, plus configuration validation and diagnostics. |
The user also needs normal access to the records and fields the Checks read. See Permission sets.
Results and statuses
Section titled “Results and statuses”Every option returns one result per Check per record, with one of five statuses:
| Status | Meaning |
|---|---|
PASS | The record meets the requirement. |
FAIL | The record does not meet the requirement. This is a normal result, not an error. |
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. |
Problems with the request itself, such as a missing permission, an unknown Check Set, or more than
200 records, stop the request: Apex throws an exception, and the Flow actions return Success
false.
Record Health Check does not store results. To keep them, save them from your code, or publish Platform Events and save them in the receiving automation; see Save or send results after a run.