Install Record Health Check in a sandbox
Install the Record Health Check package in a Salesforce sandbox, give users access, add the card to a record page, and confirm that it works for a user who is not an administrator. Record Health Check is an open-source package that shows whether a record meets configured requirements without changing the record.
Start in a sandbox so you can decide where the card belongs, who should see it, and which Checks are useful before you install in production. The same steps work in production and in Developer Edition orgs.
To try Record Health Check in a separate org with prepared records and known results instead, see Install the demo in a scratch org. That path does not touch your existing orgs.
Before you start
Section titled “Before you start”You need:
- the Salesforce Download AppExchange Packages permission, which the System Administrator profile includes;
- permission to edit Lightning record pages; and
- at least one Account in the sandbox that you can edit.
You do not need the Salesforce CLI, Apex, or Flow for these steps.
What the package adds
Section titled “What the package adds”| Component | What it is |
|---|---|
| Record Health Check component | The Lightning component that shows the card on record pages |
| Two Custom Metadata Types | Record Health Check Set and Record Health Check, which store Check Sets and Checks |
| Seven Permission Sets | Access for card users, automation, administrators, diagnostics, integrations, error logs, and receipt review |
| Apex, Flow, and agent actions | Ways to run Checks from Flow, Apex, Agentforce, and REST |
| Three Platform Events | Optional messages about runs, results, and errors |
| Four example Check Sets | 50 example Checks for Account, Contact, and Opportunity records |
The example Check Sets are active and read the records already in your org. They do not create or change data. Explore the installed example Check Sets describes each one.
Step 1: Install the package
Section titled “Step 1: Install the package”-
Sign in to the sandbox in your browser.
-
Open the installation link for your org type. Both links install the latest released version.
Org type Installation link Sandbox Install in Sandbox Production or Developer Edition Install in Production -
On the Salesforce installation page, confirm that the package name is Record Health Check and that the org shown is the one you intend to change.
-
Select Install for Admins Only.
-
Select Install.
Install for Admins Only installs the complete package but grants its access only to administrators. You give everyone else access with Permission Sets in the next step, which keeps access visible and easy to remove. Install for All Users does not make the package change data, but it grants package access to every profile, including people who do not need the card.
Installation can take several minutes. If Salesforce says the installation continues in the background, wait for the confirmation email.
Result: Setup → Installed Packages lists Record Health Check with its version number.
Step 2: Give users access
Section titled “Step 2: Give users access”The package includes seven Permission Sets so each user receives only the access they need. None of them grants access to business data; users still need normal Salesforce access to the records and fields that Checks read.
| Permission Set | Assign it to | What it grants |
|---|---|---|
| Record Health Check Card User | People who use only the record-page card | Running the card, and the Check Set list in Lightning App Builder |
| Record Health Check User | People or integration users that run Checks from Flow, Apex, Agentforce, or REST | Every way to run Checks. Do not assign it only to show the card. |
| Record Health Check Admin | People who configure Check Sets and Checks | Every way to run Checks, configuration validation, draft preview, and diagnostic details |
| Record Health Check Diagnostics Viewer | A Card User or User who must reproduce a problem | Diagnostic details only. Assign it temporarily, together with Card User or User. |
| Record Health Check MCP Integration | A dedicated integration user for the Record Health Check MCP server | The Apex REST resource only |
| Record Health Check Error Log Publisher | The running user of a Check Set that publishes error log events | Publishing the restricted Record Health Check Log Platform Event. Assign it together with a runner set. |
| Record Health Check Readiness Auditor | A reviewer of draft verification receipts | Read-only access to Record Health Check Readiness records |
To assign Record Health Check Card User to the user who will test the card:
- In Setup, enter
Permission Setsin Quick Find, then select Permission Sets. - Select Record Health Check Card User.
- Select Manage Assignments, then Add Assignment.
- Select the user, then select Next and Assign.
Repeat the steps with Record Health Check Admin for each person who will configure Checks. To create or edit Check Sets and Checks in Setup, those people also need the Salesforce Customize Application permission, which Record Health Check Admin does not include.
Diagnostic details appear only for a user who is assigned Record Health Check Admin or Record Health Check Diagnostics Viewer directly, and only on a Check Set that has Show Diagnostics selected. An assignment through a Permission Set Group does not authorize diagnostics.
Step 3: Add the card to an Account record page
Section titled “Step 3: Add the card to an Account record page”Use the example Check Set Example: Account Check Builder Guide for the first test. Its 25 Checks use all four Evaluation Types.
- Open an Account record.
- Select the gear icon, then select Edit Page. Lightning App Builder opens.
- In the Components panel, search for
Record Health Check, and drag the component onto the page. - In the component properties, set Check Set to Example: Account Check Builder Guide (rhc__Example_Account_Check_Builder_Guide). The list shows each Check Set’s label followed by its API name.
- Select Save.
- If Salesforce asks you to activate the page, select Activate. Choose Org Default, App Default, or App, Record Type, and Profile, so that the page is assigned to the app and profile of the user who will test it. Note which assignment you chose.
- Select the back arrow to return to the Account, and refresh the browser.
Edit Page opens the page currently assigned to you. If your org has several Account pages for different apps, record types, or profiles, confirm in Activation that the page you edit is the one assigned to the test user.
The component is supported on Lightning record pages in Lightning Experience. It is not available for App pages, Home pages, or Salesforce Classic.
Result: The card shows the title Example: Account Check Builder Guide and a Run button.
Step 4: Verify the card as a user
Section titled “Step 4: Verify the card as a user”Test as the user who has Record Health Check Card User, not as an administrator. An administrator can read data that other users cannot, so a successful administrator test does not prove that users will see the same results.
- Open the Account as the test user.
- Select Run.
- Confirm that each row shows a result label: Pass, Failed, Warning, Info, Skipped, Unable to Check, or System Error.
- Change a field that one of the Checks reads. For example, clear the Account’s Type and save.
- Confirm that Account Type is set now shows Warning. The card runs again by itself after the save because it has already completed a run. Select Rerun if the row does not change.
- Restore the original value.
Failed, Warning, and Info mean the record does not meet a requirement. Unable to Check and System Error mean the Check could not give a reliable answer for this user.
Confirm the installation
Section titled “Confirm the installation”The installation is complete when:
- Setup → Installed Packages lists Record Health Check;
- the test user sees the card on the Account page and can run it;
- each row shows a result label; and
- a saved change to the record changes the related result.
The example Check Sets demonstrate the product; they are not your organization’s requirements. Next, create your first Check in a Check Set your organization owns.
Resolve installation problems
Section titled “Resolve installation problems”| What you see | What to do |
|---|---|
| The installation page does not open or you cannot select Install | Confirm that you are signed in to the intended org and have the Download AppExchange Packages permission. |
| The installation stays in progress | Wait for the confirmation email, then refresh Setup → Installed Packages. If it stays pending, contact Salesforce Support with the package version and your Org ID. |
Salesforce reports a conflict with the rhc namespace | The org already has a package with the rhc namespace. Install into a different org; do not rename package components. |
Salesforce reports a conflict with RecordHealthCheckController | The org already contains Record Health Check source that was deployed without the package. Install into an org without that source. |
| Record Health Check is not in Lightning App Builder | Confirm that the package is listed in Installed Packages, and that you are editing a record page, not an App or Home page. |
| The Check Set list is empty | The list shows only active Check Sets for the page’s object. Use an Account Check Set on an Account page. |
| The card says you don’t have access | Assign Record Health Check Card User to the user. |
| A row shows Unable to Check | Confirm that the user can read the objects and fields the Check uses. |
| A row shows System Error | Follow Troubleshoot with the browser console. |
Install with the Salesforce CLI
Section titled “Install with the Salesforce CLI”To automate the installation, use the Salesforce CLI. The commands work on Windows, macOS, and Linux.
-
Find the package version ID. It begins with
04t. Copy the current ID from the table in Choose a package version, or the value ofstable.subscriberPackageVersionIdfrom the release registry in the Record Health Check repository. -
Run these commands, replacing
PACKAGE_VERSION_IDwith that value:Terminal window sf org login web --instance-url https://test.salesforce.com --alias rhc-sandboxsf org display --target-org rhc-sandboxsf package install --package PACKAGE_VERSION_ID --target-org rhc-sandbox --security-type AdminsOnly --wait 30 --publish-wait 10 --no-promptsf org assign permset --name rhc__Record_Health_Check_Card_User --target-org rhc-sandbox
sf org display shows which org the alias points to, so you can confirm it before installing.
--security-type AdminsOnly matches Install for Admins Only. The permission set name includes the
package namespace prefix rhc__; keep it. Then continue with
Step 3.