Skip to content

Write a custom Apex Check

Guide11 min read

Write an Apex class that decides whether records pass a requirement that a Formula or Query Check cannot express, such as a weighted score or a rule that combines several related records. The class implements rhc.RecordHealthCheckPlugin. A Check uses it when its Evaluation Type is Verify with Apex and its Apex Class names the class.

Record Health Check calls the class once for up to 200 records and expects one result for every record. Use a Formula or Query Check whenever either one can express the rule: they need no code, tests, or deployment.

global interface RecordHealthCheckPlugin {
Map<Id, RecordHealthCheckOutcome> evaluate(RecordHealthCheckScope scope);
}

This is the interface declared inside the installed package. A class created in your org uses the rhc. prefix, as shown in the complete example below.

Three optional interfaces add more: rhc.RecordHealthCheckPluginDefinitionSource declares the Check’s parameters, rhc.RecordHealthCheckRecordEvaluator with rhc.RecordHealthCheckOutcome.tryEvaluate isolates per-record failures, and rhc.RecordHealthCheckDisplayPlugin adds card presentation. The public contract lists every builder, limit, failure rule, and fallback.

Declare the class global with sharing so the installed package can call it. Run every SOQL query with the intended user access; the example uses WITH USER_MODE. Record Health Check validates the returned record IDs, Statuses, Reason Codes, and prohibited actions, but your class remains responsible for object, field, and record access in its own queries.

Treat deployment of a custom Apex Check like any other security-sensitive Apex deployment. with sharing enforces record sharing, but it does not by itself enforce object and field access. Record Health Check can detect prohibited changes; it cannot prove whether every custom query used user mode. A code review is therefore required even when the contract test passes.

The Scope contains the information supplied to the custom Apex Check.

rhc.RecordHealthCheckScope provides:

PropertyMeaning
objectApiNameObject shared by the requested IDs
recordIdsCopy of all requested record IDs in order
recordIdAt(index)One ID at a numbered position, without creating another list copy
parametersParsed Check parameter JSON
checkDeveloperNameUnqualified Check Developer Name
checkQualifiedApiNameSelected Check identity
checkSetDeveloperNameUnqualified parent Check Set Developer Name
checkSetQualifiedApiNameParent Check Set identity
runIdID that connects results, logs, and events from the same run

The class cannot change the package’s original request. Read recordIds into a local variable once, query for all IDs together, organize the query results in a map, and then build one outcome per record. Each access to scope.recordIds returns another list copy. For a numbered loop, use scope.size() and scope.recordIdAt(index) instead.

Use the qualified properties when identity must remain unique across namespaces. The Developer Name properties are convenient when the unqualified metadata name is specifically required, but two namespaces can publish the same Developer Name.

Return one Outcome for every requested record ID.

Build outcomes with the factories on rhc.RecordHealthCheckOutcome:

rhc.RecordHealthCheckOutcome.pass('RECENT_ACTIVITY_FOUND')
.withFound(rhc.RecordHealthCheckValue.ofCount(3))
.withComparison(
'GREATER_THAN',
rhc.RecordHealthCheckValue.ofCount(0)
);
FactoryStatusUse it when
pass(reasonCode)PASSThe record meets the requirement.
fail(reasonCode)FAILThe record does not meet the requirement.
skipped(reasonCode)SKIPPEDThe requirement does not apply to the record.
unableToEvaluate(reasonCode)UNABLE_TO_EVALUATEThe class cannot reach a reliable answer, for example because data is missing or not accessible.
passEquals(reasonCode, found, expected)PASSFound equals Expected. Sets both values and the EQUALS operator, and throws if they differ.
failEquals(reasonCode, found, expected)FAILFound does not equal Expected. Throws if they are equal.
noneFound(reasonCode)PASSA list of problems is empty. Found and Expected are empty lists.
itemsFound(reasonCode, items)FAILA list of problems is not empty. Found is the list; Expected is empty.

Do not return error(...): Record Health Check sets ERROR itself when a class breaks this contract. Return unableToEvaluate(...) when the class cannot reach an answer.

Found and Expected use the rhc.RecordHealthCheckValue factories ofString, ofBoolean, ofNumber, ofDate, ofDateTime, ofId, ofCount, and ofList. withComparison(operator, expected) takes one of the Check operators, such as EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, or NOT_EQUALS; the card uses it to word the Expected value, for example “more than 0”.

Record Health Check checks every returned outcome:

The classResult for the record
Returns PASS or FAIL without a nonblank Found and ExpectedERROR with PLUGIN_VALUES_MISSING
Returns a reason code longer than 80 charactersERROR with PLUGIN_REASON_CODE_INVALID
Returns no outcome for a requested record, or a null mapERROR with PLUGIN_RESULT_MISSING for that record, or for every record
Returns an outcome for a record it was not givenERROR with PLUGIN_RESULT_UNKNOWN_KEY for every record in the request
Throws an exceptionERROR with PLUGIN_THREW for every record in the request

An empty list counts as a value, so noneFound and itemsFound always satisfy the rule.

RecordHealthCheckValue carries a typed value, not a currency unit. The package cannot inspect or repair arithmetic already performed inside a subscriber plugin, so custom Apex owns its currency correctness. If a plugin compares monetary values, query and retain their ISO units explicitly and refuse or deliberately normalize them according to the plugin’s documented contract. The core framework performs no currency conversion and does not infer plugin-internal units from display labels.

The custom class does not set record identity, Check identity, Severity, applicability, publication, or diagnostics. Check metadata owns those values. An optional display plugin can add presentation only; it cannot change evaluation.

Implement rhc.RecordHealthCheckPluginDefinitionSource when a Check accepts JSON parameters. The definition can declare integer, choice, string, and Boolean inputs; defaults; bounds; required and nullable behavior; administrator labels/help; and scope capacity. The engine rejects unknown keys, duplicate keys, wrong JSON types, invalid choices, and out-of-range values before evaluation. This gives administrators a stable contract and removes type guessing from plugin code.

global with sharing class AccountDataQualityCheck implements rhc.RecordHealthCheckPlugin, rhc.RecordHealthCheckPluginDefinitionSource {
global rhc.RecordHealthCheckPluginDefinition getDefinition() {
return new rhc.RecordHealthCheckPluginDefinition()
.integerParameter('daysBack', 30, 1, 3650)
.describe('daysBack', 'Look-back days', 'Count activity on or after this many days ago.')
.choiceParameter('tier', 'STANDARD', new List<String>{ 'STANDARD', 'STRATEGIC' })
.capacity(200, true, 'LOW');
}
global Map<Id, rhc.RecordHealthCheckOutcome> evaluate(rhc.RecordHealthCheckScope scope) {
Integer daysBack = (Integer) scope.parameters.get('daysBack');
String tier = (String) scope.parameters.get('tier');
Map<Id, rhc.RecordHealthCheckOutcome> outcomes = new Map<Id, rhc.RecordHealthCheckOutcome>();
// Query once for scope.recordIds, then put one outcome for each ID in outcomes.
return outcomes;
}
}

With a definition, scope.parameters holds every declared key: the value from Apex Parameters (JSON), or the default when the JSON omits it, already converted to the declared type. An administrator who enters {"daysBack": 0} gets UNABLE_TO_EVALUATE with INVALID_APEX_PARAMETERS before evaluate runs. Without a definition, scope.parameters is the JSON object exactly as entered, and the class must validate each value itself. The plugin definition contract lists every builder and limit.

Use rhc.RecordHealthCheckEvidence when Found and Expected alone do not explain the decision. Declare typed columns, add rows in the same order, and attach the snapshot with .withEvidence(). Synthetic cells use RecordHealthCheckEvidenceCell.value; cells derived from a business-record field use .field(recordId, fieldPath, value) so the framework can enforce field access. Evidence is bounded and explanatory. See evidence limits and permission behavior.

When data is already loaded in bulk, RecordHealthCheckOutcome.tryEvaluate(recordId, evaluator) can turn one ordinary record exception into RECORD_EVALUATION_FAILED and a null record result into RECORD_RESULT_MISSING. Permission failures, fatal failures, and side-effect violations still escape to the engine. Never use this helper to place SOQL or DML inside the per-record loop.

An Apex Check must return Found and Expected values with their Salesforce data types for every PASS or FAIL outcome. The Check fields Display: Found Text and Display: Expected Text do not wrap or replace those custom Apex values. If either field is populated on an Apex Check, metadata validation reports the non-blocking APEX_DISPLAY_TEXT_IGNORED warning. Put the values in the custom class with .withFound(), .withExpected(), or .withComparison(); use the Check failure message when administrators need configurable explanatory wording.

For a request using EVALUATION_WITH_DISPLAY, a custom Check may also implement rhc.RecordHealthCheckDisplayPlugin. The callback runs once on the same instance after evaluation, so it must reuse data already loaded by evaluate; it cannot query or perform side effects.

The optional override can provide rich message, remediation, Found and Expected content; one atomic action label and destination; an Expected label; and independent Found/Expected formats with an optional currency ISO code. A missing or invalid field falls back to Check configuration. Status, typed values, severity, identity, order, category, applicability, visibility and publication policy remain framework or administrator owned.

Let the plugin decide which records belong to each business group, then let the display API own label/item separators and line breaks. The default item separator is comma-space, and every saved record receives its own canonical Lightning record link.

List<SObject> stepOneRecords = new List<SObject>();
stepOneRecords.addAll(stepOneUsers);
List<SObject> stepTwoRecords = new List<SObject>();
stepTwoRecords.addAll(stepTwoUsers);
List<SObject> stepThreeRecords = new List<SObject>();
stepThreeRecords.addAll(stepThreeUsers);
List<rhc.RecordHealthCheckDisplayGroup> groups =
new List<rhc.RecordHealthCheckDisplayGroup>{
new rhc.RecordHealthCheckDisplayGroup('step-1')
.withLabel(new rhc.RecordHealthCheckDisplayText().link('Step 1', stepOneUrl))
.withItems(new rhc.RecordHealthCheckDisplayText().recordLinks(stepOneRecords, User.Name)),
new rhc.RecordHealthCheckDisplayGroup('step-2')
.withLabel(new rhc.RecordHealthCheckDisplayText().link('Step 2', stepTwoUrl))
.withItems(new rhc.RecordHealthCheckDisplayText().recordLinks(stepTwoRecords, User.Name)),
new rhc.RecordHealthCheckDisplayGroup('step-3')
.withLabel(new rhc.RecordHealthCheckDisplayText().link('Step 3', stepThreeUrl))
.withItems(new rhc.RecordHealthCheckDisplayText().recordLinks(stepThreeRecords, User.Name))
};
rhc.RecordHealthCheckDisplayText found =
new rhc.RecordHealthCheckDisplayText().groups(groups);
return new rhc.RecordHealthCheckDisplayOverride()
.withFound(found)
.withMessage(new rhc.RecordHealthCheckDisplayText().text('Approval review is required.'))
.withFix(new rhc.RecordHealthCheckDisplayText().text('Complete each approval step.'))
.withAction(new rhc.RecordHealthCheckDisplayAction('Open approvals', '/lightning/page/home'))
.withExpectedLabel('Required state');

The input lists may have different sizes, for example one, two, and three Users. The resulting groups render on separate lines, and both each Step label and each saved User are independently clickable. Group keys must be unique and nonblank. Group and item order are preserved, including duplicates. Empty groups are hidden by default; add .withEmptyState(new rhc.RecordHealthCheckDisplayText().text('No users')) to show one. Use .withSeparator(' -> ') to replace the default colon-space between the label and items. Null records and records with blank labels are skipped. Records without an Id render as plain text because Salesforce has no record page to open.

This example checks whether each Account has at least one Contact. It first creates a FAIL outcome with a count of zero for every Account. One grouped query finds Accounts that have Contacts, and the code replaces only those outcomes with PASS. Accounts with no query row still have a result.

global with sharing class ContactPresenceCheck implements rhc.RecordHealthCheckPlugin {
global Map<Id, rhc.RecordHealthCheckOutcome> evaluate(
rhc.RecordHealthCheckScope scope
) {
// Read the property once because it returns a new list copy each time.
List<Id> accountIds = scope.recordIds;
Map<Id, rhc.RecordHealthCheckOutcome> outcomes = new Map<Id, rhc.RecordHealthCheckOutcome>();
for (Id accountId : accountIds) {
outcomes.put(
accountId,
rhc.RecordHealthCheckOutcome.fail('NO_CONTACTS')
.withFound(rhc.RecordHealthCheckValue.ofCount(0))
.withComparison('GREATER_THAN', rhc.RecordHealthCheckValue.ofCount(0))
);
}
// One query checks every Account. Do not put SOQL inside the Account loop.
for (AggregateResult row : [
SELECT AccountId parentId, COUNT(Id) total
FROM Contact
WHERE AccountId IN :accountIds
WITH USER_MODE
GROUP BY AccountId
]) {
Id recordId = (Id) row.get('parentId');
Integer total = (Integer) row.get('total');
outcomes.put(
recordId,
rhc.RecordHealthCheckOutcome.pass('CONTACTS_FOUND')
.withFound(rhc.RecordHealthCheckValue.ofCount(total))
.withComparison('GREATER_THAN', rhc.RecordHealthCheckValue.ofCount(0))
);
}
return outcomes;
}
}

Keep custom Apex Checks within these boundaries

Section titled “Keep custom Apex Checks within these boundaries”

A custom Apex Check must not create, update, or delete records; publish events; enqueue work; send email; make callouts; or start asynchronous Apex. Record Health Check uses a savepoint and governor counters to reject observable prohibited actions. Apex exposes no reliable counter proving that a plugin did not call EventBus.publish, start Batch Apex, or schedule Apex, so contract tests, static analysis, and human code review must enforce those prohibitions. Runtime detection is not a complete sandbox.

Catch a problem that affects only one record inside the record loop and return UNABLE_TO_EVALUATE for that record so one problem does not erase the results for every other record in the request.

Extend rhc.RecordHealthCheckContractTest, return a new instance of the class from newCheck(), return test data from testData(), and call verifyContract() from a test method. The contract test runs the class with 1, 10, 50, and 200 records, and fails when:

  • a record has no outcome, or an outcome is not valid;
  • the number of queries grows with the number of records;
  • the class saves records, makes callouts, sends email, or starts Queueable or future work.
@IsTest
global with sharing class ContactPresenceCheckContractTest extends rhc.RecordHealthCheckContractTest {
global override rhc.RecordHealthCheckPlugin newCheck() {
return new ContactPresenceCheck();
}
global override rhc.RecordHealthCheckContractTestData testData() {
return new AccountData();
}
@IsTest
static void meetsTheContract() {
new ContactPresenceCheckContractTest().verifyContract();
}
global class AccountData extends rhc.RecordHealthCheckContractTestData {
global override rhc.RecordHealthCheckScope createScope(Integer size) {
List<Account> accounts = new List<Account>();
for (Integer index = 0; index < size; index++) {
accounts.add(new Account(Name = 'Contract ' + size + '-' + index));
}
insert accounts;
List<Id> accountIds = new List<Id>();
for (Account account : accounts) {
accountIds.add(account.Id);
}
return new rhc.RecordHealthCheckScope(
'Account',
accountIds,
new Map<String, Object>(),
'Contact_Presence',
'Account_Data_Quality',
'contract-' + size
);
}
}
}

The test class is global because it overrides methods of a global class from the package.

To test access behavior, create a user who genuinely cannot read a record or field used by the Check. Apex does not expose a counter that proves whether a query used user mode, so the test result and a review of the SOQL source remain separate requirements.

The framework’s configured Query row limit does not wrap SOQL issued inside a subscriber plugin. Plugin authors own their row limits: query no more than the plugin can evaluate completely, use an extra-row probe when a collection-wide result depends on completeness, and return a documented UNABLE_TO_EVALUATE outcome instead of deciding from a truncated collection. Do not disclose a true count that the running user may not be entitled to see.

The interface shown on this page is the supported custom Apex Check contract. Implement rhc.RecordHealthCheckPlugin with rhc.RecordHealthCheckScope, rhc.RecordHealthCheckOutcome, and rhc.RecordHealthCheckValue; the package does not include a second custom Apex Check interface.

The response and Platform Event contract versions are independent of this interface. Compile and run the contract test against the package version you plan to install. An event or response version does not prove that a custom Apex Check compiles with that package version.