Configure the Lightning record-page component
Add the Record Health Check component to a Salesforce Lightning record page and control how its card behaves: whether Checks run when the page opens or when the user selects Run, what the card shows, and when it publishes Platform Events. The component shows the results of one Check Set for the open record.
You make two kinds of choices. In Lightning App Builder, you place the component and select the Check Set. On the Check Set record in Setup, you choose how the card runs and displays results. The Check Set is the only place those display settings live, so every page that uses the same Check Set behaves the same way.
Before you start
Section titled “Before you start”- The Check Set exists, is active, and its Object matches the record page’s object exactly, such
as
Account. - To edit the page, you need permission to edit Lightning pages and one of the Record Health Check Card User, User, or Admin Permission Sets, which provide the Check Set list in Lightning App Builder.
- People who use the card need Record Health Check Card User, or Record Health Check User if they also run Checks from Flow or Apex. They also need normal access to the records and fields the Checks read.
Add the component to a record page
Section titled “Add the component to a record page”- Open a record of the object, select the gear icon, and select Edit Page.
- In the Components panel, search for
Record Health Check, and drag the component onto the page. - Set Check Set (the component’s only property,
checkSetName). The list shows each active Check Set for this object as its label followed by its API name, such as Account Readiness (Account_Readiness). When only one Check Set matches, Lightning App Builder selects it for you. - Select Save.
- Select Activation, and assign the page as the Org Default, an App Default, or to specific apps, record types, and profiles. Saving a page that is not assigned to a user does not change what that user sees.
- Open a matching record as a user who has Record Health Check Card User, and confirm that the card appears.
The component works only on Lightning record pages in Lightning Experience, because it needs the open record. Lightning App Builder does not offer it on App or Home pages.
Choose how the card runs
Section titled “Choose how the card runs”Set When Checks Run on the Check Set.
| When Checks Run | What happens | Use it when |
|---|---|---|
| When the page opens | The card waits until the page is idle, for at most one second, then runs the Checks. It then offers Rerun. | People should see guidance every time they open the record. |
| When the user clicks Run | The card shows Run and runs nothing until the user selects it. This is the default. | Reviewing the record is a deliberate step, or the card publishes events. |
Two combinations are invalid, because the user would have no way to start the Checks:
- When the user clicks Run with Run Button Display set to Hide.
- When the user clicks Run with Card Heading Display set to Hide, because the heading holds the Run button.
For either one, the card shows “This Record Health Check has a configuration problem.” Correct the Check Set, then select Try Again on the card; you do not need to reload the page.
Choose what the card shows
Section titled “Choose what the card shows”All of these are fields on the Check Set. None of them changes a result.
| Field | Choices | Effect |
|---|---|---|
| Card Heading Display | Show title and subtitle (default), Show title only, Hide | Hide removes the title, subtitle, and Run/Rerun button. It requires When the page opens. |
| Run Button Display | Show label and icon (default), Show label only, Show icon only, Hide | Show icon only keeps the button’s name for screen readers. Hide requires When the page opens. |
| Run Button Label, Rerun Button Label | Up to 80 characters | Blank shows Run and Rerun. |
| Run Button Icon | A Salesforce icon name such as utility:refresh | Blank, or a name that is not a valid icon, shows the play icon. |
| Reveal Mode | One by one (default), All at once | One by one adds each row as its Check finishes. All at once lists every row first, then fills in each result. |
| Passed Checks | Show each passed check (default), Show passed count only | Count only removes passed rows; the summary still counts them, and hovering the count lists their names. |
| Skipped Checks | Show each skipped check (default), Show skipped count only | The same choice for skipped Checks. |
| Found/Expected Display | Show on demand (default), Show for failed checks, Show for every check | On demand shows Found and Expected on failed rows and lets users open a passing row to see them. |
| Summary Display | Show below checks (default), Show above checks, Hide | Where the result counts appear. When any Check has a Category, the card shows one group of counts per category instead of one total. |
Each Check can also limit what its own row shows with Show Found and Expected: Automatic, Show found only, Show expected only, or Hide. Hiding a value changes only the card; it is not a security control, and Flow and Apex results still contain the value.
How the card runs Checks
Section titled “How the card runs Checks”- The card evaluates each Check in its own server request and shows rows as they finish. Up to eight Checks are in progress at once across the page.
- When Stop after a system error is selected on the Check Set, the card runs one Check at a time. After a Check returns System Error, the remaining Checks show Skipped with the message “This check was skipped because an earlier check encountered an error.”
- When a Check has a Prerequisite Check, the card runs the prerequisite first, whatever their order on the card.
- Every Run and Rerun reads the Check Set and its Checks again, so changes saved in Setup apply without reloading the page.
- A Check Set with more than 25 active Checks runs no Checks, and the card says “No Checks were run.”
Refresh after a record save
Section titled “Refresh after a record save”When a user saves the record with the standard Salesforce edit form, Salesforce notifies the page, and the card runs its Checks again:
- A card set to When the page opens always runs again.
- A card set to When the user clicks Run runs again only after it has completed a run, so a save never starts the first run.
The card waits briefly after several notifications and runs once. A newer run replaces an older one that is still in progress, so older results never overwrite newer ones. A custom component that saves the record without the standard Salesforce refresh notification does not trigger this; the user selects Rerun instead.
When the card publishes Platform Events
Section titled “When the card publishes Platform Events”The card publishes events only after a user selects Run or Rerun, and only when the Check Set and Checks enable them:
| What happened | Check Set Run event | Check Result events |
|---|---|---|
| The page opened and the card ran | Never | Never |
| The card ran again after a record save | Never | Never |
| The user selected Run or Rerun | One, when the Check Set’s Publish User Run Event is selected | One for each Check whose Publish User Result Event is selected, whatever its result |
After the last row finishes, the card sends all of the run’s results to the server in one request,
and the server publishes the enabled events together after that request commits. The events’
Source is USER_INITIATED.
The results in these events come from the browser. The server confirms that each Check belongs to the selected Check Set, but it does not evaluate the Checks again. Before a process takes an action that must not be based on a mistaken result, have it run the Check Set itself from Flow or Apex.
Publish Error Log Event on the Check Set is separate. When it is selected, an Unable to Check or System Error result from any card run, including a run when the page opens, publishes a Record Health Check Log event, provided the user has the Record Health Check Error Log Publisher Permission Set.
If publishing fails, the card still shows its results and a notice that the run could not be completed. A delivered event does not prove that a subscriber processed it; monitor subscribers separately. See Decide when to use Platform Events.
Data access
Section titled “Data access”The card reads data with the access of the user who views it. A query counts only the records that user can see, so an empty result means no visible matching records, not that none exist. If the user cannot read an object or field that a Check needs, that Check shows Unable to Check.
Diagnostic details appear only when the Check Set has Show Diagnostics selected and the user is directly assigned Record Health Check Admin or Record Health Check Diagnostics Viewer. See Troubleshoot with the browser console.
Messages the card shows instead of results
Section titled “Messages the card shows instead of results”| Message | Cause and fix |
|---|---|
| This Record Health Check hasn’t been configured for this page. | No Check Set is selected. Edit the page and select one. |
| Record Health Check has Check Sets for this record type, but none are active. | No Check Set is selected, and every Check Set for this object is inactive. Activate one, then select it on the page. |
| No Record Health Check has been created for this record type. | No Check Set is selected, and none exists for this object. Create and activate one, then select it on the page. |
| This component only works on a supported record page. | The component has no record to check. Place it on a Lightning record page. |
| The selected Record Health Check is no longer available. | The selected Check Set was deleted or renamed. Select another. |
| This Record Health Check is currently inactive. | Activate the Check Set, or select an active one. |
| This Record Health Check isn’t configured for this type of record. | The Check Set’s Object does not match the page. Select a Check Set for this object. |
| This Record Health Check doesn’t contain any active Checks. | Activate at least one Check in the Check Set. |
| No Checks were run. | The Check Set has more than 25 active Checks. Deactivate some or move them to another Check Set. |
| This Record Health Check has a configuration problem. | Run the validation Flow and correct the Check Set. A hidden heading or button with When the user clicks Run is a common cause. |
| You don’t have access to view or run Record Health Check. | Assign Record Health Check Card User to the user. |
| Record Health Check can’t access the current record. | The user cannot read the record. Check the user’s record access. |
| The current record is no longer available. | The record was deleted or can no longer be read. Refresh the page or return to the list. |
| We couldn’t verify this Record Health Check’s setup. | The card could not look up the Check Sets for this object. Select Try Again; if it continues, check the browser console. |
| We couldn’t load Record Health Check. | The card could not load. Select Try Again; if it continues, check the browser console. |
| Record Health Check returned an unexpected response. | The server’s answer could not be read. Select Try Again; if it continues, check the browser console. |