Skip to content

Developer guides

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

NeedGuide
Compare every way to run Record Health CheckChoose a developer integration
Use the result in Apex before the transaction continuesRun Record Health Check from Apex
Check up to 200 known records in a later transactionRun Record Health Check from Queueable Apex
Check many records in groupsCheck many records with Batch Apex
Check records on a scheduleRun Record Health Check from Scheduled Apex
Move existing @future codeReplace a Future method with Queueable Apex
Write a Check that a formula or query cannot expressWrite a custom Apex Check
Test a custom Apex Check before activating itVerify a custom Apex Check
See complete, tested Apex Check classesApex Check examples
Let an Agentforce agent or an MCP client use resultsAgentforce and MCP
Receive Platform Events outside SalesforceReceive events with Pub/Sub API

To branch on a result without code, use the Flow actions instead.

Record Health Check is a namespaced unlocked package with the namespace rhc. Two prefixes come from it:

PrefixWhere it appearsExample
rhc.Before every package Apex type in your coderhc.RecordHealthCheck.evaluate(request)
rhc__In the API names of package objects and fields, and of Check Sets and Checks that install with the packagerhc__Record_Health_Check_Set_Run__e, rhc__Example_Account_Check_Builder_Guide

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.

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 setUse it for
Record Health Check Card UserThe record-page card only.
Record Health Check UserThe card, Flow, Apex, background jobs, and Agentforce actions.
Record Health Check MCP IntegrationThe REST endpoint that the MCP server calls.
Record Health Check AdminEverything in User, plus configuration validation and diagnostics.

The user also needs normal access to the records and fields the Checks read. See Permission sets.

Every option returns one result per Check per record, with one of five statuses:

StatusMeaning
PASSThe record meets the requirement.
FAILThe record does not meet the requirement. This is a normal result, not an error.
SKIPPEDThe Check did not apply, or its prerequisite did not pass.
UNABLE_TO_EVALUATEAccess, configuration, or data prevented a reliable answer.
ERRORAn 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.