Skip to content
Suggest a correction

Install Record Health Check in a sandbox

Getting started8 min read

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.

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.

ComponentWhat it is
Record Health Check componentThe Lightning component that shows the card on record pages
Two Custom Metadata TypesRecord Health Check Set and Record Health Check, which store Check Sets and Checks
Seven Permission SetsAccess for card users, automation, administrators, diagnostics, integrations, error logs, and receipt review
Apex, Flow, and agent actionsWays to run Checks from Flow, Apex, Agentforce, and REST
Three Platform EventsOptional messages about runs, results, and errors
Four example Check Sets50 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.

  1. Sign in to the sandbox in your browser.

  2. Open the installation link for your org type. Both links install the latest released version.

    Org typeInstallation link
    SandboxInstall in Sandbox
    Production or Developer EditionInstall in Production
  3. 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.

  4. Select Install for Admins Only.

  5. 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.

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 SetAssign it toWhat it grants
Record Health Check Card UserPeople who use only the record-page cardRunning the card, and the Check Set list in Lightning App Builder
Record Health Check UserPeople or integration users that run Checks from Flow, Apex, Agentforce, or RESTEvery way to run Checks. Do not assign it only to show the card.
Record Health Check AdminPeople who configure Check Sets and ChecksEvery way to run Checks, configuration validation, draft preview, and diagnostic details
Record Health Check Diagnostics ViewerA Card User or User who must reproduce a problemDiagnostic details only. Assign it temporarily, together with Card User or User.
Record Health Check MCP IntegrationA dedicated integration user for the Record Health Check MCP serverThe Apex REST resource only
Record Health Check Error Log PublisherThe running user of a Check Set that publishes error log eventsPublishing the restricted Record Health Check Log Platform Event. Assign it together with a runner set.
Record Health Check Readiness AuditorA reviewer of draft verification receiptsRead-only access to Record Health Check Readiness records

To assign Record Health Check Card User to the user who will test the card:

  1. In Setup, enter Permission Sets in Quick Find, then select Permission Sets.
  2. Select Record Health Check Card User.
  3. Select Manage Assignments, then Add Assignment.
  4. 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.

  1. Open an Account record.
  2. Select the gear icon, then select Edit Page. Lightning App Builder opens.
  3. In the Components panel, search for Record Health Check, and drag the component onto the page.
  4. 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.
  5. Select Save.
  6. 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.
  7. 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.

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.

  1. Open the Account as the test user.
  2. Select Run.
  3. Confirm that each row shows a result label: Pass, Failed, Warning, Info, Skipped, Unable to Check, or System Error.
  4. Change a field that one of the Checks reads. For example, clear the Account’s Type and save.
  5. 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.
  6. 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.

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.

What you seeWhat to do
The installation page does not open or you cannot select InstallConfirm that you are signed in to the intended org and have the Download AppExchange Packages permission.
The installation stays in progressWait 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 namespaceThe org already has a package with the rhc namespace. Install into a different org; do not rename package components.
Salesforce reports a conflict with RecordHealthCheckControllerThe 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 BuilderConfirm 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 emptyThe 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 accessAssign Record Health Check Card User to the user.
A row shows Unable to CheckConfirm that the user can read the objects and fields the Check uses.
A row shows System ErrorFollow Troubleshoot with the browser console.

To automate the installation, use the Salesforce CLI. The commands work on Windows, macOS, and Linux.

  1. Find the package version ID. It begins with 04t. Copy the current ID from the table in Choose a package version, or the value of stable.subscriberPackageVersionId from the release registry in the Record Health Check repository.

  2. Run these commands, replacing PACKAGE_VERSION_ID with that value:

    Terminal window
    sf org login web --instance-url https://test.salesforce.com --alias rhc-sandbox
    sf org display --target-org rhc-sandbox
    sf package install --package PACKAGE_VERSION_ID --target-org rhc-sandbox --security-type AdminsOnly --wait 30 --publish-wait 10 --no-prompt
    sf 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.