Write a custom Apex Check
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.
Interface
Section titled “Interface”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:
| Property | Meaning |
|---|---|
objectApiName | Object shared by the requested IDs |
recordIds | Copy of all requested record IDs in order |
recordIdAt(index) | One ID at a numbered position, without creating another list copy |
parameters | Parsed Check parameter JSON |
checkDeveloperName | Unqualified Check Developer Name |
checkQualifiedApiName | Selected Check identity |
checkSetDeveloperName | Unqualified parent Check Set Developer Name |
checkSetQualifiedApiName | Parent Check Set identity |
runId | ID 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.
Outcome
Section titled “Outcome”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) );| Factory | Status | Use it when |
|---|---|---|
pass(reasonCode) | PASS | The record meets the requirement. |
fail(reasonCode) | FAIL | The record does not meet the requirement. |
skipped(reasonCode) | SKIPPED | The requirement does not apply to the record. |
unableToEvaluate(reasonCode) | UNABLE_ | The class cannot reach a reliable answer, for example because data is missing or not accessible. |
passEquals(reasonCode, found, expected) | PASS | Found equals Expected. Sets both values and the EQUALS operator, and throws if they differ. |
failEquals(reasonCode, found, expected) | FAIL | Found does not equal Expected. Throws if they are equal. |
noneFound(reasonCode) | PASS | A list of problems is empty. Found and Expected are empty lists. |
itemsFound(reasonCode, items) | FAIL | A 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 class | Result for the record |
|---|---|
Returns PASS or FAIL without a nonblank Found and Expected | ERROR with PLUGIN_ |
| Returns a reason code longer than 80 characters | ERROR with PLUGIN_ |
| Returns no outcome for a requested record, or a null map | ERROR with PLUGIN_ for that record, or for every record |
| Returns an outcome for a record it was not given | ERROR with PLUGIN_ for every record in the request |
| Throws an exception | ERROR with PLUGIN_ 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.
Declare and validate parameters
Section titled “Declare and validate parameters”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.
Attach decision evidence
Section titled “Attach decision evidence”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.
Keep per-record errors isolated
Section titled “Keep per-record errors isolated”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.
Provide Found and Expected values
Section titled “Provide Found and Expected values”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.
Add optional presentation
Section titled “Add optional presentation”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.
Bulk pattern
Section titled “Bulk pattern”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.
Verification
Section titled “Verification”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.
@IsTestglobal 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.
Supported classes
Section titled “Supported classes”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.
Version compatibility
Section titled “Version compatibility”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.