Skip to content

Apex entry points (L5)

Reference11 min read

Find the internal Record Health Check class behind each supported way to start a health check or publish its results: the Apex API, Flow actions, the record-page card, background jobs, Agentforce actions, and the REST endpoint. For setup steps and examples, follow the linked task guides.

Use the Apex class reference to place these entry points in the full package structure. For the architecture story, see Architecture.

Role: Run a Check or Check Set from Apex and return its results.

Type: Service class · global with sharing

Pass a RecordHealthCheckRequest containing the exact Check or Check Set Qualified API Name, the record IDs to check, the type of response needed, whether to publish Platform Events, and an optional run ID. The method returns one RecordHealthCheckResponse containing the results.

Key members:

MemberPurpose
evaluate(RecordHealthCheckRequest)Run the requested Check or Check Set and return a RecordHealthCheckResponse

Notable behavior:

  • When to use it: any Apex process that needs typed results for one Check or every active Check in one Check Set.
  • Important: use the Check or Check Set’s exact Qualified API Name (how to find it). An item created by an administrator in your org might be My_Account_Checks. An item included with the installed package can begin with rhc__. Do not use its label and do not add or remove rhc__.

See also: Reference: Apex API

Role: Load and run Checks for the Record Health Check Lightning card.

Type: Service class · public with sharing

Adapts card operations to the package services. It cleans up the card’s inputs, identifies whether the run came from page load or a button click, and passes the work to the package classes that load and run the Checks.

Key members:

MemberPurpose
getCheckSetAvailabilityForRecord(recordId)Active/inactive Check Sets for the record’s object (setup banner)
getCheckSetShellConfig(checkSetQualifiedApiName)Lightweight active Check Set run mode, card text, active Check count, and Run-button presentation used before definitions load
getCheckDefinitions(checkSetQualifiedApiName, recordId, runId)Display settings and ordered Check definitions for the card
evaluateCheckJson(checkSetQualifiedApiName, checkQualifiedApiName, recordId, runId, source)JSON transport for one card Check; preserves null cells that Aura omits from nested lists
evaluateCheck(checkSetQualifiedApiName, checkQualifiedApiName, recordId, runId, source)Typed evaluation used by the JSON adapter and existing Apex callers
completeRun(checkSetQualifiedApiName, runId, source, recordId, resultsJson)After a user-initiated run: filters completed card results, calculates the summary, and publishes the Set completion event

Notable behavior:

  • Source behavior: the browser may request only Lightning-allowed source values. Unknown values are rejected. Accepted values are USER_INITIATED and RUN_ON_LOAD; only an explicit user-initiated run can publish the configured health-result Platform Events.
  • Important: getCheckDefinitions distinguishes a caught ConfigException (logged at DEBUG, reason code passed through as-is) from any other exception (logged at ERROR and returned as LOAD_FAILED). The card can therefore distinguish an invalid setup from an unexpected Apex failure. completeRun does not run the Checks again. It accepts only the current record, one result for each Check in the selected Check Set, and a USER_INITIATED source before calculating the summary and publishing the configured events.

See also: Configure the Lightning record-page component

RecordHealthCheckPreviewService and RecordHealthCheckPreviewController

Section titled “RecordHealthCheckPreviewService and RecordHealthCheckPreviewController”

Role: Validate or execute one detached Check against an existing server-owned Check Set.

Type: Global Apex service · global with sharing; Lightning adapter · public with sharing

The Preview service returns versioned findings, capabilities, resolved fields, optional execution results, and optional private readiness evidence. The controller serializes that response for the administrator-only Preview component and exposes bounded expired-receipt cleanup.

Notable behavior:

  • Important: Preview requires administrator and run authorization. It publishes no user-result, user-run, or error-log events, and it does not save or activate the detached Check.

See also: Validate and preview an AI draft

Role: Run one Check for each input record in Flow.

Type: Invocable Flow action · global with sharing

This class provides the installed Run Record Health Check Flow action. Each input supplies a Check Qualified API Name, one record ID, and NONE, ACTIONABLE, or ALL for Platform Event publication. Each output contains success or error details, Status, Reason Code, and the complete result as JSON.

Notable behavior:

  • Important: the action groups its inputs by Check and Event Publication. One call accepts up to 10 groups, and each group accepts up to 200 records; a group over the limit returns Error Type VALIDATION for its inputs without running its Checks.

Role: Run every active Check in one Check Set for each input record in Flow.

Type: Invocable Flow action · global with sharing

This class provides the installed Run Record Health Check Set Flow action. Each output contains success or error details, an overall Status, the PASS/FAIL/SKIPPED/UNABLE_TO_EVALUATE/ERROR counts, and the complete response as JSON.

Notable behavior:

  • Important: the action groups its inputs by Check Set and Event Publication, with the same limits of 10 groups per call and 200 records per group. It checks a group’s inputs before running any of its Checks, so invalid input never leaves a partly completed group.

See also: Flow actions

Role: Run one Check Set asynchronously for a bounded list of known record IDs.

Type: Global Queueable and Finalizer · global with sharing

enqueue(...) returns an AsyncApexJob ID. The packaged job discards the typed response after optional lifecycle publication; its finalizer publishes terminal job state when requested and logs an unhandled job failure.

Notable behavior:

  • The job ID reports platform execution, not health outcomes. With publication NONE, the health results are transient unless subscriber-owned code uses a custom Queueable to save them.
  • Equivalent pending requests use a duplicate signature instead of consuming another Queueable slot.

See also: Queueable Apex

Role: Run one Check Set asynchronously across a bounded known population in several transactions.

Type: Global Batch Apex adapter · global with sharing

The two run(...) overloads return an AsyncApexJob ID. The three-argument overload automatically chooses a scope from 1 through 100 and lowers it for the selected Check Set’s FormulaEval budget. The four-argument overload accepts a scope from 1 through 200 and rejects a size that does not fit the remaining formula budget. The Batch can publish per-result, per-record summary, and terminal job events according to the caller’s publication choice.

Notable behavior:

  • The packaged Batch does not persist ordinary results. Use events or a reviewed custom Batch that consumes and saves the typed response in each execute transaction.

See also: Batch Apex

Role: Schedule a fixed record population for recurring Check Set Batch execution.

Type: Global Scheduled Apex adapter · global with sharing

scheduleDaily(...) returns a CronTrigger ID and runs at 2:00 AM in the scheduling user’s time zone. Each scheduled execution delegates the captured IDs to RecordHealthCheckBatch with SCHEDULED lifecycle attribution.

Notable behavior:

  • The schedule captures record IDs when it is created. It does not query for records that later enter or leave a business population.
  • The schedule ID and later Batch job describe platform state, not the individual health outcomes.

See also: Scheduled Apex

Role: Validate Record Health Check configuration from an administrator Flow.

Type: Invocable Flow action · global with sharing

The installed Validate Record Health Check Configuration action audits every Check Set and Check, including inactive drafts. It returns whether the configuration is valid, error and warning counts, and a JSON report that identifies each component, field, reason code, and message.

Notable behavior:

  • The action uses the same query-shape, required-field, and dependency validators as runtime.
  • Add it to an administrator-only Flow and correct every error before activation.

Role: Run one exact Check for one record as a native Agentforce action.

Type: Invocable Agentforce action · global with sharing

This class provides Run Record Health Check for Agentforce. It accepts exactly one record ID, one exact Check Qualified API Name, and an optional safe correlation ID. It fixes event publication to NONE, attributes execution to AGENT, and returns versioned structured fields without display or diagnostic data.

Notable behavior:

  • Important: FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR remain completed health results. Authorization, request, limit, and execution problems use a separate safe error channel.

Role: Run one exact Check Set for one record as a native Agentforce action.

Type: Invocable Agentforce action · global with sharing

This class provides Run Record Health Check Set for Agentforce. It returns the strongest Set status and explicit PASS, FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR counts under agent tool contract version 1.0.

Notable behavior:

  • Important: the action accepts one input only. It never exposes event-publication choice, raw serialized results, display values, or administrator diagnostics to the model.

See also: Agentforce actions

Role: Expose the two approved agent tool operations to a separately authenticated service.

Type: Apex REST resource · global with sharing

This class accepts one strict JSON request at the versioned agent tool route. It fixes publication to NONE, attributes execution to AGENT, and returns contract version 1.0. Completed health results use HTTP 200; adapter authorization, validation, limit, and execution failures use separate safe HTTP and JSON responses.

Notable behavior:

  • Important: unknown JSON fields, generic operations, multi-record input, unsafe correlation IDs, and alternate configuration identities are rejected before evaluation. Response objects exclude display data and diagnostics.

See also: Agent tool REST API

Role: Publish optional Check Result and Check Set Run Platform Events.

Type: Service class · public with sharing

Publishes events for deliberately started runs and records the run’s origin in Source__c, such as APEX_API, FLOW, USER_INITIATED, SCHEDULED, BATCH, or QUEUEABLE. The card’s page-open runs (RUN_ON_LOAD) and the packaged Agentforce actions and REST API (AGENT) never publish. Apex in your org can set any origin with withExecutionOrigin, such as FUTURE, so set only the origin that describes the caller. For Apex, Flow, Batch, and other programmatic runs, the request’s NONE, ACTIONABLE, or ALL value controls publication. For a person clicking Run or Rerun on the Lightning card, the Check Set’s PublishUserRunEvent__c and each Check’s PublishUserResultEvent__c settings control publication. The class publishes up to 100 events in each EventBus call and logs a publication failure without failing the health check itself.

Key members:

MemberPurpose
CONTRACT_VERSION, FRAMEWORK_VERSION, SOURCE_*, PUBLISH_CHUNK_SIZEEvent contract version, package version reported by the event, source values, and the 100-event publish group size
publishResponse(...)Publish Check and optional Set events for a deliberate programmatic run
publishInteractiveResponse(...)Publish filtered outcomes for an explicit Lightning Run / Rerun
isRunPublicationEnabled(...)Whether the Check Set’s PublishUserRunEvent__c allows Set publication
enterSubscriberContext()Package-internal loop guard; custom Apex in an org that installs the package cannot call this public method through the rhc namespace

Notable behavior:

  • Important: RecordHealthCheckEventId.newId builds a unique key from the run id and a suffix so a caller-supplied run id cannot exceed the platform event’s EventId__c field. An internal setting prevents the package’s own event-handling code from publishing the same event again. A Flow or Apex trigger that receives these events must also avoid starting the same health check again, or it can create a loop.

See also: Decide when to use Platform Events

Role: Hold the request rules every Agentforce surface shares, in one place.

Type: Utility class · public with sharing

The two native actions and the REST tool resource accept the same request shape, so validateRequest(recordId, qualifiedApiName, correlationId, identityLabel) states the Record ID, identity-format, length, and correlation-ID rules once. identityLabel names the identity in every rejection message, which is the only wording that differs between a Check and a Check Set. safeCorrelationId(value) returns a caller value that passes isValidCorrelationId(value), and otherwise generates one with a full 128-bit random suffix for collision resistance across concurrent requests.

Notable behavior:

  • A correlation ID is at most 120 letters, numbers, periods, underscores, colons, or hyphens.
  • A rejected or missing correlation ID is replaced, never echoed back into an operational log.

Role: Generate unique, bounded application identifiers for lifecycle-event publications.

Type: Utility class · public with sharing

newId(runId) keeps as much of the caller-owned Run ID as fits as an operational prefix, then appends a transaction-local sequence number and a 32-character random hexadecimal value. With a one-digit sequence number, the first 45 characters of the Run ID are kept. The sequence separates publications inside one transaction and the random value separates concurrent transactions, so separate publications have different EventId__c values even when a caller deliberately reuses the same Run ID. A replay of the same Platform Event retains its original ID, so subscriber deduplication remains safe.

Notable behavior:

  • Important: RunId__c remains the correlation key; it is not an event-uniqueness key.
  • Generated IDs are at most 80 characters, the size of the event contract’s Text(80) field.

See also: Check Result events

Role: Store the run ID, source, and elapsed time for one health-check request.

Type: Data holder · public (no sharing keyword)

Holds runId, source, startedAt, completedAt, and durationMs. Created at the start of an evaluation path. Exposed to merge tokens (rhcRun.*) and used when building lifecycle events.

Notable behavior:

  • Important: no package code calls complete() in 2.0.11, so completedAt and durationMs stay blank and the {!rhcRun.completedAt} and {!rhcRun.durationMs} merge tokens resolve blank. When it is called, complete() sets both values only the first time, so a later call cannot replace the original completion time.

Role: Provide the Check Set list shown in Lightning App Builder.

Type: Service class · public with sharing, extends VisualEditor.DynamicPickList

Lists active Check Sets that match the Lightning record page’s Salesforce object. App Builder shows each one as Label (Qualified API Name) and stores its exact Qualified API Name. When exactly one active Check Set matches, the component selects it automatically.

Notable behavior:

  • Why it exists: the list avoids mistakes caused by typing a Check Set name manually. The label helps the administrator recognize the Check Set, while the stored Qualified API Name keeps an administrator-created item such as My_Account_Checks distinct from an installed-package item such as rhc__Example_Account_Check_Builder_Guide. When App Builder does not provide an object name, the list is empty.