Architecture
Apex classes that coordinate a health-check request (L4)
Use this page when tracing request orchestration. This class-level reference is not a Setup or Flow walkthrough. Administrators should use the Flow, configuration, and evaluation guides; subscriber developers should use the public Apex API or Apex Check contract.
Use this page to understand the internal classes that select the Checks, load the Salesforce
records, run each Evaluation Type, and assemble the response. Custom Apex should start with
rhc.RecordHealthCheck.evaluate(...), not call these classes directly.
Use the Apex class reference to place these orchestration classes in the full package structure. For the architecture story, see Architecture § How one Check is evaluated.
Request coordination (L4)
Section titled “Request coordination (L4)”RecordHealthCheckScopePipeline
Section titled “RecordHealthCheckScopePipeline”Role: Coordinate one request from its Qualified API Name through its final response.
Type: Service class · public with sharing
RecordHealthCheck.evaluate, the installed Flow actions, and the Lightning card use this class.
The card reaches it through evaluateCheckJson, which delegates to evaluateCheck.
It validates the request, loads the requested Salesforce records with user
access enforced, runs the applicable Checks in order, optionally adds display content, publishes the
requested Platform Events, and returns RecordHealthCheckResponse. The Lightning card’s
completeRun method publishes already-completed results and does not run this class again.
Key members:
| Member | Purpose |
|---|---|
evaluate(...) | Run the requested Check or Check Set for the supplied record IDs |
Notable behavior:
- Important: the card evaluates one Check per Apex transaction; Apex and Flow may evaluate a whole Check Set in one transaction. The same Check Set can therefore use more transaction limits in Apex or Flow than it does on the card.
- Important: use the exact Check or Check Set Qualified API Name copied from Setup. Do not use
its label or add or remove
rhc__.
See also: Entry points, Evaluators
RecordHealthCheckScopePlanner
Section titled “RecordHealthCheckScopePlanner”Role: Decide which Checks and records can run before evaluation begins.
Type: Service class · public with sharing
Loads the selected Check or Check Set, confirms that it is active and matches the record IDs’ object, and enforces the 25-Check and 200-record limits. It also checks the planned Formula Evaluation and custom Apex Check limits before any Check runs. For each Check, it determines which records are applicable and whether a prerequisite result requires the Check to be skipped.
Notable behavior:
- Important: an applicability miss returns
SKIPPEDwith a Reason Code; it is not a Fail. - Transaction planning reserves the scope record load, applicability queries, every evaluator
query, both sides of Compare Two Queries, and the second query used when a Query Check selects
COMPARISON_QUERYas its expected-value source.
RecordHealthCheckEvaluatorRegistry
Section titled “RecordHealthCheckEvaluatorRegistry”Role: Send each Check to the class that runs its Evaluation Type.
Type: Service class · public with sharing
Maps the Custom Metadata values FORMULA, QUERY, COMPARE_TWO_QUERIES, and APEX to the matching
evaluator class.
See also: Evaluators
RecordHealthCheckFieldPlanner
Section titled “RecordHealthCheckFieldPlanner”Role: Identify which fields must be loaded from each Salesforce record.
Type: Service class · public with sharing
Reads the Check’s formulas, merge tokens, and other settings to identify the record fields it needs.
The pipeline then loads those fields for all requested records in one user-mode query. Custom Apex
uses RecordHealthCheck.evaluate(request) and does not call this class directly.
Key members:
| Member | Purpose |
|---|---|
collectRecordFields(...) | Identify the record fields referenced by a Check |
Notable behavior:
- Before a field enters dynamic SOQL, the class confirms through Salesforce describe information that the field path exists and is readable. An invalid or inaccessible field is not added to the record query; the affected Check later returns the appropriate configuration or access result.
RecordHealthCheckFormulaFieldScanner
Section titled “RecordHealthCheckFormulaFieldScanner”Role: Extract selectable record paths from a Salesforce formula expression.
Type: Formula parsing service · public with sharing
Masks formula string literals and global references, preserves complete relationship paths, and
normalizes validated polymorphic colon references such as Owner:User.IsActive into the dot path
the record query can select. RecordHealthCheckFieldPlanner calls this class while expanding
formula dependencies; custom Apex does not call it directly.
Key members:
| Member | Purpose |
|---|---|
scan(...) | Return described record-field paths in document order with duplicates removed |
RecordHealthCheckBulkQuerySupport
Section titled “RecordHealthCheckBulkQuerySupport”Role: Run a supported Query Check SOQL template once for all requested records.
Type: Service class · public with sharing
Replaces the record-specific condition with one query that covers all requested record IDs, then
assigns the returned rows to the matching record. This prevents one SOQL query per record.
Classification masks string literals and considers only depth-zero correlation, ordering, and limit
clauses. A record token found only in a nested query or literal is rejected as
UNSUPPORTED_BULK_QUERY_SHAPE; it is never used to rewrite the outer query accidentally.
See also: Query Evaluation Type
RecordHealthCheckBulkQueryRewriter
Section titled “RecordHealthCheckBulkQueryRewriter”Role: Convert a record-specific SOQL template into one bulk query.
Type: Service class · public with sharing
Changes a validated SOQL template so one query can serve all requested record IDs without changing the condition configured by the Check author. An unsupported query shape is rejected instead of falling back to a query inside a record loop.
RecordHealthCheckBulkQueryShape
Section titled “RecordHealthCheckBulkQueryShape”Role: Recognize the one record-token equality that can safely drive a scope-wide query rewrite.
Type: Parsing service · public with sharing
Masks quoted values, isolates the outer WHERE expression, and accepts the correlation only when it
is a direct AND conjunct. Tokens under OR, NOT, a subquery, or a second executable occurrence
leave the query unclassified so execution fails before dynamic SOQL runs.
RecordHealthCheckResourcePlan
Section titled “RecordHealthCheckResourcePlan”Role: Calculate formula-call sizing and check savepoint capacity before work starts.
Type: Admission service · public with sharing
Computes conservative Formula Evaluation calls for a record scope, selects the largest safe default
Batch scope, and verifies that a plugin hook has capacity for its savepoint, possible rollback, and
release. A shortage raises TRANSACTION_BUDGET_EXCEEDED before the hook is invoked.
RecordHealthCheckPrerequisiteEligibility
Section titled “RecordHealthCheckPrerequisiteEligibility”Role: Select the records allowed to reach a Check’s applicability phase.
Type: Coordination service · public with sharing
Keeps inaccessible records and records blocked by a failed prerequisite out of formula and query applicability work. It returns the eligible IDs, their authorized record map, and the already-decided results so the pipeline can reassemble output in the original request order.
RecordHealthCheckScopeResultSupport
Section titled “RecordHealthCheckScopeResultSupport”Role: Convert each internal result into the response returned to Apex, Flow, or Lightning.
Type: Service class · public with sharing
Converts evaluation and display results and delegates display finalization to
RecordHealthCheckScopeDisplayFinalizer. Scope callers pass the authorized record map explicitly;
standalone callers retain current-record provenance only.
RecordHealthCheckScopeDisplayFinalizer
Section titled “RecordHealthCheckScopeDisplayFinalizer”Role: Resolve legacy display text, apply plugin presentation, and attach authorized evidence.
Type: Service class · public with sharing
Keeps message resolution, FAIL-only fixes and safe Action URLs, diagnostics redaction, and structured content in their existing order. It forwards the scope loader’s user-mode record map to evidence projection so another authorized record in that scope can supply provenance. It does not query or expand that map. Evaluation-only responses omit display and evidence.
Planning failures carry a transient internal flag. Display finalization preserves their diagnostic and reason-code behavior without resolving authored templates against fields the Check did not plan or load. Plain unavailable messages remain; messages containing unresolved token syntax use the standard unavailable fallback. This applies equally to a Check run alone and in a Check Set.
See also: Security and data access, Results and plugins
RecordHealthCheckResponseDisplayBudget
Section titled “RecordHealthCheckResponseDisplayBudget”Role: Allocate structured fields and authorized evidence within one optional-presentation budget.
Type: Coordination service · public with sharing
Response finalization applies the budget before lifecycle publication and diagnostic attachment. Allocation follows selected Check order and normalized record order. Within a result, message, fix, Found and Expected precede evidence. Fields are retained whole; evidence retains whole leading rows with corrected completeness and counts. Original plugin plain-value fallbacks remain transient and are restored when the corresponding optional field is omitted. Machine evaluation facts are unchanged.