Lightning record page

Configure the Lightning record-page component

Detailed page. Use “On this page” to jump directly to the section you need.

Choose whether the Record Health Check card runs when a record page opens or waits for the user to select Run, then understand what users see and when optional Platform Events can be published.

Use this reference to choose whether a Check Set runs when the record page opens or waits for the user to select Run. The choice affects when users see results and whether the card can publish Platform Events.

The Record Health Check Lightning Web Component supports both experiences. Automatic page-load evaluation is read-only and never publishes. An explicit Run or Rerun is a deliberate user action and can publish when the Check Set and Checks enable publication. After a standard Lightning record save, the card also refreshes current results without publishing lifecycle events.

The component is available only on Lightning record pages. App and Home pages do not provide the recordId required for evaluation, so the component intentionally does not appear in their App Builder palettes.

Choose the run experience

User experience	Check Set setting	When to use it	Platform Events
Results appear after the page opens	When the page opens (`RUN_ON_LOAD`)	Users need passive readiness guidance whenever they view the record	Never publishes
The card waits for the user	When the user clicks Run (`RUN_ON_REQUEST`)	The review is deliberate, data may change first, or publication may be enabled	Run and Rerun can publish when configured

What the component is

A record-page component that displays and coordinates runs for one configured Check Set.
A view of the current run’s Check Set and Check results using the current user’s Salesforce access.
An optional event publisher only when the user explicitly clicks Run or Rerun.

Component scope

It is not a result-history store.
It does not block record save or automatically remediate failures.
Automatic page load is not consent to publish lifecycle events.
A completed card does not prove that a receiving Flow, Apex trigger, or integration processed an event.
It is not available on App Pages or Home Pages. The component evaluates one record, so it is published only for record pages and does not appear in the App Builder palette elsewhere.

New to the model? Read Integrate Record Health Check first.

Prerequisites and quick start

Assign the least-privilege Record Health Check Card User (rhc__Record_Health_Check_Card_User) Permission Set to a card-only viewer and grant access to the record and fields used by the selected Checks. Use Record Health Check User only when the same person or automation also needs Flow, Agent, REST, or Apex entry points.
In Lightning App Builder, open a record page, add Record Health Check, and select an active Check Set for that object. The component is listed only while you are editing a record page; it is not offered on App Pages or Home Pages because it has no record to evaluate there.
Configure When Checks Run, Summary Display, and the Run-button presentation on the Check Set Custom Metadata record. The Check Set is the single source of truth. Hide is valid only for an automatic page-load Check Set.
Save and activate the Lightning page as Org Default, App Default, or for the intended app, record type, and profiles. Then open a matching record as an assigned user.
Confirm the card returns rows and summary counts. Click Run or Rerun only when an explicit run is intended.

Every card query uses the viewing user’s effective access. An empty Query result means no matching rows were visible to that transaction; it is not proof of org-wide absence. Sharing, restriction rules, and scoping rules are intentional visibility controls, and the card never bypasses them to infer hidden records.

For installation details, use Create your first Check. Advanced diagnostic values additionally require Show Diagnostics and a direct Record Health Check Admin or Record Health Check Diagnostics Viewer Permission Set assignment. Assign Record Health Check Diagnostics Viewer alongside Card User or User when testing diagnostics; Admin already authorizes it. See Permission Sets for assignment guidance. When both are present, the card renders the server-provided admin-detail message; that detail remains absent for unauthorized viewers and never changes record or field access.

If the Check Set dropdown is empty, first confirm that the Check Set is active and its Object exactly matches the record-page object. The page builder needs Salesforce page-editing privileges and picker access supplied by Record Health Check Card User, User, or Admin. Refresh App Builder after permission changes and verify the package installation.

Card label	Programmatic status	Meaning
Pass	`PASS`	Requirement met
Failed, Warning, or Info	`FAIL`	Requirement not met; severity changes presentation
Skipped	`SKIPPED`	Check did not apply
Unable to Check	`UNABLE_TO_EVALUATE`	No reliable answer because of data, access, configuration, or limits
System Error	`ERROR`	Framework or custom Apex problem

When the card publishes result events

Component action	Source	Set event	Check events
Automatic page-load run	`RUN_ON_LOAD`	Never	Never
Record-save or RefreshView rerun	`RUN_ON_LOAD`	Never	Never
User clicks Run	`USER_INITIATED`	Enabled Check Set	Enabled Checks
User clicks Rerun	`USER_INITIATED`	Enabled Check Set	Enabled Checks

Leave these settings off when users only need results on the card:

PublishUserRunEvent__c enables one Set Run completion event for the Check Set.
PublishUserResultEvent__c enables a Check Result event for that Check.

Error Log events use a separate default-off Check Set setting. PublishErrorLogEvent__c publishes Record Health Check ERROR details from automatic and deliberate runs; uncheck it to opt that Check Set out. This does not disable Salesforce debug-log output.

An automatic page-load or record-refresh run never publishes lifecycle events even when both lifecycle switches are enabled.

If no event follows Run or Rerun, confirm the visible action was used, the Check Set and relevant Check checkboxes are enabled, the transaction committed, the receiver has event access, and the receiver itself did not fail. Page and record-save refreshes use the non-publishing browser lifecycle source and never publish result events. It can still publish an Error Log event when the Set explicitly opts in and the user has publisher permission.

The block is intentional. Opening or refreshing a record page is passive navigation, not a request to notify another process. If automatic runs published, ordinary browsing could consume Platform Event allocations, create repeated history, and start receiving automation repeatedly. Run and Rerun provide the deliberate boundary required before publication is eligible.

Component inputs and visible outputs

Input/context	Meaning
Check Set selected in App Builder	One active Check Set whose Object matches the record page. The dropdown shows its Label and stores its exact Qualified API Name.
Current record ID	Record evaluated
When the page opens (`RUN_ON_LOAD`)	Render a quiet local shell first. At browser idle, resolve the lightweight Check Set configuration; a later idle turn loads definitions and evaluates. Publication remains blocked.
When the user clicks Run (`RUN_ON_REQUEST`)	Render a quiet local shell first. At browser idle, resolve the lightweight Check Set configuration, then defer definitions and evaluation until the user selects Run.
Check Set Run Button Display	Show label and icon, label only, a compact icon, or hide the action on automatic Check Sets only
Run or Rerun button	Explicit user-initiated run; publication can be enabled. Custom labels fall back to Run and Rerun when blank.

When the display is Hide, the card removes the complete action area, so the title and subtitle can use that space. Show icon only uses a compact square button and retains an accessible Run or Rerun name for assistive technology. An invalid custom icon name falls back to the built-in play icon. A limit notice still reserves the space it needs in the header.

The selected Check Set is the single source of truth for scheduling. On a real record page, the component calls the lightweight getCheckSetShellConfig Apex method after the initial browser-idle boundary to obtain its run mode, title, subtitle, active Check count, and Run-button presentation. A manual Check Set combined with an effective Hide value is invalid and the card explains the configuration error instead of leaving users with no way to start the run.

An automatic Check Set continues to show Rerun after it finishes unless its action is hidden. This default preserves existing card behavior after an upgrade. A Check Set with no active Checks does not show Rerun because there is nothing to evaluate again.

Record-save refresh

A record save, browser refresh, and Rerun can all obtain current results, but only Rerun is an explicit user action that can publish lifecycle events. A standard Lightning record save sends a RefreshView notification. The component coalesces a burst of those notifications and replaces any older in-flight run so stale results cannot overwrite the saved record’s results.

An automatic Check Set refreshes after a save. A manual Check Set preserves its initial deliberate boundary: it does not run merely because a record was saved before the user selected Run. After the first manual run completes, later saves refresh those visible results automatically. Save-driven refresh never publishes lifecycle result events, including when the Run action is hidden.

The visible output is the completed row list and summary counts. Summary Display places the summary above or below the rows. If resolved Checks have categories, category summaries replace the single overall totals bar at that same position. Long Found and Expected values clamp to two lines; use the adjacent +/− control to expand or collapse the complete value. Results remain in component state; the component does not create a history record.

A definition, access, or setup failure blocks the card and appears as a component-wide error row. A failure while finalizing a completed user run is different: the evaluated results remain visible and the card shows a nonblocking completion warning because the run summary or configured event may not have been finalized.

Event outputs for Run and Rerun

USER_INITIATED completion events are client-attested advisory notifications. The server confirms that submitted Check names belong to the selected Check Set, but it does not re-evaluate their submitted statuses during completion. Use Apex or Flow to re-evaluate before a compliance-sensitive or irreversible action.

Check Set Run event

After every row resolves, a Set with publication enabled can produce Record_Health_Check_Set_Run__e with Phase__c = COMPLETED and Source__c = USER_INITIATED. See Check Set Run event fields for the complete field list.

Check Result event

Each server-finalized Check with publication enabled can produce Record_Health_Check_Result__e with Source__c = USER_INITIATED. See Check Result event fields for the complete field list.

What happens while the card runs

The component evaluates Checks through separate Salesforce requests so it can honor prerequisites, stop after system errors when configured, and show results progressively.

When Stop after a system error is unchecked, the component allows up to five evaluations at a time so the card can finish promptly without flooding the browser or Salesforce with one request per Check all at once. When it is checked, evaluation becomes sequential; the component must know whether the current Check returned ERROR before deciding whether the next Check is allowed to start.

With Reveal Mode = One by one, the card can show work in groups of up to five evaluations while it advances through the ordered Checks. That staged appearance is not a failure; wait for the run summary before troubleshooting missing rows.

For an explicit run:

Each server-finalized Check result can publish its own Check Result event after that Apex request commits.
When every row has resolved, the component makes one completion call.
That call can publish one aggregate Set Run event after its transaction commits.

Results the client determines without calling Apex, such as a dependency skip, count toward the Set totals but do not create a separate Check Result event, because no server Check evaluation finalized.

Within one request, a prerequisite shared by multiple dependent Checks is evaluated once and reused. A later Run or Rerun starts again from the current saved record data.

Best-effort behavior

Event publication never changes the card result. If the completion call or event publication fails, the user still sees the completed health-check results. The receiving Flow, Apex trigger, or integration needs its own monitoring; the card is not event-delivery confirmation.

A successful card result is not proof that requested events were published. Monitor publication warnings and receiving automation separately.

Use the lifecycle-events overview for cross-event behavior and the linked metadata references for exact field types, replay, retention, and receiving-process design.

Versioning and compatibility

The component reads the contract value included in the response returned to it. Events created by an explicit Run or Rerun carry their own independent contract value. No component run behavior is currently deprecated.

The contract numbers identify response and event fields for integrations; the Record Health Check version identifies the installed release. Keeping them separate allows compatible updates without making the Lightning component or receiving integrations treat every product release as a breaking schema change.