Upgrade an installation
Upgrade an existing Record Health Check installation to the latest version and prove that the cards, Checks, access, and automation your organization relies on still work. Upgrade a sandbox that represents production first, compare results before and after, and upgrade production only when every check passes.
The latest version is 2.0.11. Whatever version you upgrade from, complete Check Check Sets for 2.0.11 before upgrading first, or some cards stop running after the upgrade. The table below lists what changed since 2.0.10.1. If the org runs an earlier version, the upgrade also includes every change in the release notes for the versions you skip; review those too.
What changes in 2.0.11
Section titled “What changes in 2.0.11”| Change | What to do |
|---|---|
| A Check Set with Card Heading Display set to Hide and When Checks Run set to When the user clicks Run is invalid. The card shows a setup error instead of running. | Find and correct these Check Sets before upgrading. |
| The card no longer shows evidence summaries, Show details, Show all, evidence tables, or evidence downloads. Messages, Found and Expected, fix text, and links remain. | Tell users who relied on evidence tables. Apex requests that use the EVALUATION_ result mode still receive evidence. |
| The comparison headings on the card always read Found and Expected, including for Formula and Apex Checks. | Review any message that refers to a different heading. |
| A Display: Value Format other than Automatic now takes precedence over a format returned by an Apex Check. An Apex Check’s currency code is still used. | Review Apex Checks that set a value format and confirm the card shows the values you expect. |
| Cards set to run when the page opens start sooner: they wait at most one second for the page to become idle. Up to eight Checks run at once on a page, up from five. | No action is needed. |
| The installed example Checks no longer have categories, so example cards show one summary instead of one per category. | No action is needed unless you copied example categories. |
Before you start
Section titled “Before you start”Collect the following, so that you can compare results and restore the current setup if needed:
- A verified backup of the Check Sets and Checks your organization created. See Back up and restore configuration. Open the backup and confirm that every Check Set and Check you expect is present.
- The installed version, from Setup → Installed Packages → Record Health Check → Version Number.
- Each Lightning record page that contains the card, the Check Set selected on it, and the page’s activation assignment.
- The users assigned to each Record Health Check Permission Set.
- Each Flow, Apex class, scheduled job, or integration that runs Checks or receives Record Health Check Platform Events.
- For each important Check Set, one record that passes and one record that fails.
You need the Salesforce Download AppExchange Packages permission to upgrade.
Check Check Sets for 2.0.11 before upgrading
Section titled “Check Check Sets for 2.0.11 before upgrading”Version 2.0.11 rejects a Check Set that hides its heading but waits for the user to select Run, because the heading contains the Run button. Find these Check Sets in the org you are about to upgrade, active or inactive, so that none can cause a problem when it is activated later.
-
Open the Developer Console, then select the Query Editor tab.
-
Run this query:
SELECT DeveloperName, MasterLabel, rhc__CardHeadingDisplay__c, rhc__CardRunMode__c, rhc__IsActive__cFROM rhc__Record_Health_Check_Set__mdtWHERE rhc__CardHeadingDisplay__c = 'HIDE' AND rhc__CardRunMode__c = 'RUN_ON_REQUEST'With the Salesforce CLI, run the same query with
sf data query --target-org ORG_ALIAS --query "<query>". -
For each Check Set the query returns, open Setup → Custom Metadata Types → Record Health Check Set → Manage Records, edit the record, and make one of these changes:
- Set Card Heading Display to Show title and subtitle or Show title only. Users keep the Run button.
- Set When Checks Run to When the page opens. The heading stays hidden, and the Checks run when the record opens.
-
Run the query again. Continue only when it returns no rows.
If you work from the Record Health Check source repository, npm run audit:upgrade-2.0.11 -- --target-org ORG_ALIAS runs the same check and exits with an error while any finding remains.
Step 1: Record the current results
Section titled “Step 1: Record the current results”- As a user with normal access, open each passing and failing record you selected and run its card.
- Record each Check’s result label, Found, Expected, message, and action link.
- Confirm that diagnostic details are hidden for that user.
These results give you a before-and-after comparison, so you can tell a package change from a change in data, access, or configuration.
Step 2: Upgrade the sandbox
Section titled “Step 2: Upgrade the sandbox”- Sign in to the sandbox.
- Open Install in Sandbox. Salesforce shows that Record Health Check is already installed and names the version you are upgrading to.
- Select Install for Admins Only, then select Upgrade.
- Wait for the confirmation email if Salesforce completes the upgrade in the background.
To upgrade with the Salesforce CLI, use the 04t ID from stable.subscriberPackageVersionId in the
release registry:
sf org display --target-org ORG_ALIASsf package install --package PACKAGE_VERSION_ID --target-org ORG_ALIAS --security-type AdminsOnly --upgrade-type Mixed --wait 30 --publish-wait 10 --no-prompt--upgrade-type Mixed is the Salesforce default for unlocked packages: it deletes some components
that the new version removed and marks the others as deprecated.
Result: Installed Packages shows the new version number.
Step 3: Verify the upgraded sandbox
Section titled “Step 3: Verify the upgraded sandbox”| What to verify | Expected result |
|---|---|
| Your Check Sets and Checks | They match the backup. An upgrade does not change records your organization created. |
| Lightning record pages | Each page still shows the card with the same Check Set. |
| Passing records | The same Checks pass. |
| Failing records | The same Checks fail, with the same labels, messages, Found and Expected values, and links. |
| A user with normal access | The user can run the card and sees no diagnostic details. |
| Validation | The Validate Record Health Check Configuration Flow action returns Configuration Is Valid as true. |
| Flow and Apex callers | Each still receives results and follows the right path. A FAIL result follows the business path, not a fault path. |
| Platform Event subscribers | Each receives events when expected and does not repeat work. |
To test a Flow, open it in Flow Builder, select Debug, and run it with a record you selected before the upgrade.
If a result differs, find the cause before you continue. Compare the record’s data and the user’s access with what you recorded, then compare the Check with the backup.
Step 4: Upgrade production
Section titled “Step 4: Upgrade production”Upgrade production only when every row in Step 3 passes. Repeat the compatibility query in production first, because production can contain Check Sets that the sandbox does not. After the production upgrade, repeat Step 3 in production.
Resolve upgrade problems
Section titled “Resolve upgrade problems”| What you see | What to check |
|---|---|
| The upgrade fails | The first error on the installation page or in the email. It names the component or org feature that blocked the upgrade. |
| A card shows “This Record Health Check has a configuration problem” | The Check Set probably hides its heading and waits for Run. Correct it as described in the compatibility check, then select Try Again on the card. |
| A Check Set or Check is missing or changed | Compare it with the backup. Restore it from the backup if needed. |
| A Check’s result changed | The record’s data, the running user’s access, and the Check’s configuration. |
| A user lost access | The user’s Permission Set assignments and their access to the objects and fields that Checks read. |
| A Flow or Apex caller fails | The error the caller received and the caller’s Permission Set assignments. |
| A Platform Event subscriber stops working or repeats work | The Event Publication value the caller uses and the subscriber’s error handling. |
If the sandbox upgrade cannot be approved
Section titled “If the sandbox upgrade cannot be approved”You cannot install an earlier version over a later one. If the upgraded sandbox does not pass:
- Keep production on its current version.
- Stop any automation in the sandbox that acts on results you have not verified.
- Record the installation error, the changed results, both version numbers, and the affected configuration.
- Find whether the cause is the package, configuration, access, or test data, and correct it.
- Repeat the upgrade test in a sandbox that represents production.
Uninstalling and reinstalling is not a downgrade. It deletes the package’s components and any data that depends on them. Use it only with a verified backup and an approved plan, as described in Uninstall Record Health Check.