Configure Check Sets and Checks
Turn a business review of one Salesforce object into a Record Health Check card. You create a Check Set for the card, add Checks for each requirement, validate the configuration, place the card on a Lightning record page, and test it with the access real users have.
Record Health Check stores this configuration as Custom Metadata. A Record Health Check Set record, or Check Set, defines one card for one object. A Record Health Check record, or Check, defines one requirement on that card. Running a Check never changes the record or blocks a save.
What you will build
Section titled “What you will build”The steps build an Account handoff review as their example:
| Record | Label | API name | Requirement |
|---|---|---|---|
| Check Set | Account Handoff Review | Account_ | Defines the card on Account record pages |
| Check | Billing Country Is Complete | Billing_ | Billing Country has a value |
| Check | Account Has a Contact | Account_ | The Account has at least one related Contact |
Use the same steps for another object or review. Replace each example name, message, and rule with values your organization approves.
Before you start
Section titled “Before you start”- Install Record Health Check. See Install Record Health Check in a sandbox.
- Assign yourself Record Health Check Admin, and confirm that you have the Salesforce Customize Application permission. You need both to create and validate Custom Metadata records; Record Health Check Admin does not include Customize Application.
- To place the card, you need permission to edit Lightning record 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.
- Write the review in plain language: what must be true, what a user should do when it is not, and which records it does not apply to.
- Identify a user who represents the people who will use the card, with the Record Health Check Card User Permission Set and their normal record and field access. You test as that user.
The Record Health Check Permission Sets grant no access to business data. Users need their normal access to the objects, fields, and records that each Check reads.
Step 1: Plan one review
Section titled “Step 1: Plan one review”A Check Set should represent one review on one object, such as:
- Account handoff readiness
- Opportunity approval readiness
- Case escalation review
Keep unrelated processes in separate Check Sets, even when they use the same object. A focused card is easier to understand and test. A Check Set can run at most 25 active Checks.
For each Check, write down:
| Question | Answer for Billing Country Is Complete |
|---|---|
| What must be true? | Billing Country has a value. |
| Where is the answer? | A field on the Account. |
| What does the user see when it fails? | Billing Country is required before handoff. |
| What should the user do next? | Edit the Account and enter the verified country. |
| Does it apply to every Account? | Yes. |
Copy field and relationship API names from Object Manager in the target org. If a field belongs
to an installed package, keep its namespace prefix in formulas, queries, Source Query Field, and
{!record...} merge tokens. For example, use SBQQ__AssetQuantitiesCombined__c, not
AssetQuantitiesCombined__c. Record Health Check does not guess which package an unprefixed name
belongs to.
Step 2: Choose an Evaluation Type for each Check
Section titled “Step 2: Choose an Evaluation Type for each Check”Choose the simplest Evaluation Type that can answer the question.
| Evaluation Type | Use it when | Example |
|---|---|---|
| Verify with a formula | A Salesforce formula on the record, or on a parent record, can answer it. | Billing Country has a value. |
| Verify with a query | One SOQL query on related records can answer it. | The Account has at least one Contact. |
| Compare two queries | The answer compares the results of two separate SOQL queries. | Every open Opportunity has a Contact Role. |
| Verify with Apex | A formula or query cannot express the rule. A developer writes and deploys an Apex class. | A scoring rule across several objects. |
The examples library has complete, tested configuration for each type.
Step 3: Create the Check Set
Section titled “Step 3: Create the Check Set”- In Setup, enter
Custom Metadata Typesin Quick Find, then select Custom Metadata Types. - Next to Record Health Check Set, select Manage Records, then select New.
- Enter these values, and select Save.
| Field | Value | What it controls |
|---|---|---|
| Label | Account Handoff Review | The name administrators see in Setup and in the Lightning App Builder list. |
| Record Health Check Set Name | Account_ | The API name that Flow, Apex, and the component use. |
| Object | Account | The object the Check Set runs on. It must match the record page’s object exactly. |
| Active | Cleared | Keeps the Check Set out of Lightning App Builder until it is ready. |
| Card Heading Display | Show title and subtitle | Whether the card shows its title, subtitle, and Run button. |
| Card Title | Account Handoff Review | The title users see on the card. Required. |
| Card Subtitle | Complete these checks before changing ownership. | One line that explains the review. |
| When Checks Run | When the user clicks Run | Users select Run when they are ready. |
| Run Button Display | Show label and icon | How the Run and Rerun button looks. |
| Reveal Mode | One by one | Each row appears as its Check finishes. All at once lists every row first. |
| Passed Checks | Show each passed check | Lists passed Checks. Show passed count only shows only the count. |
| Skipped Checks | Show each skipped check | Lists skipped Checks. Show skipped count only shows only the count. |
| Found/Expected Display | Show on demand | Failed rows show Found and Expected; users open a passing row to see them. |
| Summary Display | Show below checks | Where the result counts appear: above, below, or hidden. |
| Show Diagnostics | Cleared | Keeps troubleshooting details hidden during normal use. |
Leave the button label, icon, and advanced settings blank or at their defaults. The Check Set field reference describes every field.
Record Health Check Set Name becomes the record’s Developer Name. When Flow or Apex asks for
the Check Set’s Qualified API Name, use that name exactly. A Check Set your organization creates
has no namespace prefix, such as Account_Handoff_Review. A Check Set installed with the package has
the rhc__ prefix, such as rhc__Example_Account_Check_Builder_Guide. Never add or remove the
prefix yourself.
Two combinations are invalid, because users would have no way to start the Checks: When the user clicks Run with Run Button Display set to Hide, and When the user clicks Run with Card Heading Display set to Hide. The card shows a setup error for either one.
Step 4: Create a formula Check
Section titled “Step 4: Create a formula Check”- Return to Custom Metadata Types.
- Next to Record Health Check, select Manage Records, then select New.
- Enter these values, and select Save.
| Field | Value |
|---|---|
| Label | Billing Country Is Complete |
| Check Set | Account Handoff Review |
| Evaluation Type | Verify with a formula |
| Record Health Check Name | Billing_ |
| Evaluation Order | 10 |
| Active | Cleared |
| Pass Condition | NOT(ISBLANK(BillingCountry)) |
| Check Title | Billing Country is complete |
| Message When Failed | Enter the verified Billing Country before handing off {!record. |
| Fix Message | Edit the Account and confirm the country with a reliable source. |
| Failure Severity | Warning |
| Action Label | Edit Account |
| Action URL | /lightning/r/Account/{!record. |
| Applies To | All records |
Pass Condition is a Salesforce formula that must return true or false:
trueproducesPASS, shown as Pass.falseproducesFAIL, shown as Warning because Failure Severity is Warning.- A formula that cannot return a value, for example because it reads a field the user cannot
access, produces
UNABLE_TO_EVALUATE, shown as Unable to Check.
The action link appears only when the Check fails. It opens the Account’s edit page and saves nothing; the user reviews and saves the change. See Add a fix link for other destinations.
Step 5: Create a related-record Check
Section titled “Step 5: Create a related-record Check”Create a second Check in the same Check Set:
| Field | Value |
|---|---|
| Label | Account Has a Contact |
| Check Set | Account Handoff Review |
| Evaluation Type | Verify with a query |
| Record Health Check Name | Account_ |
| Evaluation Order | 20 |
| Active | Cleared |
| Source Query | SELECT COUNT() FROM Contact WHERE AccountId = {!record. |
| Source Query Field | Leave blank |
| How To Read Query Results | One row or aggregate |
| Comparison Operator | Greater than |
| Expected Value Comes From | Fixed value |
| Expected Value (Fixed) | 0 |
| Check Title | Account has at least one Contact |
| Message When Failed | Add at least one verified Contact before handing off this Account. |
| Failure Severity | Warning |
| Applies To | All records |
The query counts the Account’s Contacts, and the Check passes when the count is greater than 0.
{!record.Id} inserts the ID of the open Account. Leave Source Query Field blank because a
bare COUNT() returns the number directly. For an aggregate with an alias, such as
SELECT SUM(Amount) total FROM Opportunity WHERE AccountId = {!record.Id}, enter the alias,
total, in Source Query Field.
The query runs with the running user’s access. A Contact the user cannot see is not counted. If the user cannot read Contact at all, the Check shows Unable to Check, not a failure.
The Query reference explains every query setting, including the If Query Finds No Records and If Field Value Is Empty choices that other query modes require.
Step 6: Limit when a Check applies
Section titled “Step 6: Limit when a Check applies”Use Applies To when a Check is relevant only to some records. For example, to run a Check only on Accounts whose Type is Customer - Channel:
| Field | Value |
|---|---|
| Applies To | When a formula is true |
| Applies When (Formula) | ISPICKVAL(Type, "Customer - Channel") |
On any other Account, the Check produces SKIPPED, shown as Skipped, not a failure. Add a
Message When Not Applicable to tell users why.
Use Prerequisite Check when a Check only makes sense after another Check passes. For example, a
Check that every Contact has an email address could name Account_Has_A_Contact as its
prerequisite. Enter the prerequisite’s Record Health Check Name, not its title.
- The prerequisite must be an active Check in the same Check Set.
- Record Health Check runs the prerequisite first, whatever the two Checks’ Evaluation Order values are. Giving the prerequisite a lower value shows it above the dependent Check, which is easier to read. The field’s help text in Setup says a lower value is required; it is not. The help text also says validation finds inactive and later-ordered prerequisites; validation reports only a prerequisite that does not exist and a circular dependency.
- When the prerequisite does not pass, or is missing or inactive, the dependent Check shows Skipped with a message that names the prerequisite.
- Two Checks cannot be prerequisites of each other, directly or through other Checks.
Prerequisites apply when a whole Check Set runs. A Flow, Apex, or agent request for a single Check evaluates that Check without its prerequisite.
Step 7: Validate, then activate
Section titled “Step 7: Validate, then activate”Keep the Check Set and its Checks inactive until validation succeeds.
- Run the Validate Record Health Check Configuration Flow action. See Validate configuration before activation for how to build and run the Flow.
- Confirm that Configuration Is Valid is
trueand Error Count is0. - Correct every error, and decide on every warning.
- Edit each Check, select Active, and save.
- Edit the Check Set, select Active, and save it last.
Activating the Check Set last keeps a partly built card out of Lightning App Builder. When you change a live configuration later, validate the change in a sandbox before deploying it to production.
Step 8: Place the card on the record page
Section titled “Step 8: Place the card on the record page”- Open an Account record, 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 to Account Handoff Review (Account_Handoff_Review).
- Select Save. If the page is not yet active for the intended users, select Activate and assign it as the Org Default, an App Default, or to specific apps, record types, and profiles.
The Check Set list shows only active Check Sets whose Object matches the page. When exactly one Check Set matches, Lightning App Builder selects it automatically. The component works only on Lightning record pages.
Step 9: Test with real access
Section titled “Step 9: Test with real access”Test in a sandbox, as the user you identified in Before you start.
- Open an Account that meets both requirements, select Run, and confirm two Pass rows.
- Clear the Billing Country on a test Account, save, and confirm Billing Country is complete shows Warning.
- Test an Account with no Contacts and confirm Account has at least one Contact shows Warning.
- If you added Applies To or a Prerequisite Check, test a record that should be skipped and confirm Skipped with the expected message.
- Select each action link and confirm that it opens the intended page without changing data.
- Correct a failing record, save it, and confirm the result changes to Pass. A card set to When the user clicks Run runs again by itself after a save once it has completed a run.
- In a sandbox only, remove the test user’s access to a field a Check reads, run the card, and confirm Unable to Check. Restore the access.
Step 10: Interpret the results
Section titled “Step 10: Interpret the results”| Card label | Status | Meaning | What to do |
|---|---|---|---|
| Pass | PASS | The record meets the requirement. | Nothing. |
| Failed, Warning, or Info | FAIL | The record does not meet the requirement. Failure Severity sets the label. | Follow the message and fix instructions. |
| Skipped | SKIPPED | The Check does not apply, its prerequisite did not pass, or no records means skip. | Review Applies To, Prerequisite Check, or If Query Finds No Records if the skip is unexpected. |
| Unable to Check | UNABLE_ | Configuration, access, missing data, or a limit prevented a reliable answer. | Check the user’s access and the Check configuration. |
| System Error | ERROR | An unexpected failure, often in custom Apex. | Investigate with diagnostics and debug logs. |
The reason code that explains an Unable to Check or System Error result is available in Flow and Apex results, and on the card to users with diagnostic access. See Troubleshoot with the browser console.
Know the limits
Section titled “Know the limits”- A Check Set can run at most 25 active Checks. With more, none run, and the card shows a setup message.
- A query returns at most the Check’s Max Query Rows (1-2000) value, which defaults to 200.
- The card checks one record at a time. To check many records, use Flow or Apex. A Flow or Apex request can include up to 200 records.
- Record Health Check allows at most 95 Salesforce formula evaluations in one transaction. A Formula Check uses one evaluation per record, and each Display: Found Formula or Display: Expected Formula on it adds one per record plus seven. An Applies When (Formula) adds one per record on any Check, and a Query Check’s formula operands add one per record, plus seven when Formula Result Type is Automatic. For example, a Check Set with two Formula Checks and no display formulas can check up to 47 records in one request. A request that would exceed the budget is rejected before any Check runs.
The platform limitations reference lists every limit.
Resolve common problems
Section titled “Resolve common problems”| What you see | What to check |
|---|---|
| The Check Set is not in the Lightning App Builder list | The Check Set is active, and its Object matches the page’s object. |
| “This Record Health Check doesn’t contain any active Checks.” | At least one Check in the Check Set is active. |
| “This Record Health Check isn’t configured for this type of record.” | The selected Check Set’s Object matches the record page. |
| “This Record Health Check has a configuration problem.” | Run the validation Flow and correct each error. A common cause is a hidden heading with When the user clicks Run. |
| “No Checks were run.” | The Check Set has more than 25 active Checks. Deactivate Checks or move some to another Check Set. |
| A Check is skipped unexpectedly | Applies To, Prerequisite Check, Evaluation Order, and If Query Finds No Records. |
| Unable to Check | The running user’s access to every object and field the Check reads, and the formula or query. |
| Results do not change after an edit | Select Rerun. A save in a custom component that does not send a standard refresh does not rerun the card. |
Review before rollout
Section titled “Review before rollout”- The Check Set represents one review, and its title and subtitle say what it is.
- The Check Set Object matches the Lightning record page.
- Each Check uses the simplest Evaluation Type that works.
- Each failure message explains the problem in words users understand.
- Each fix message gives a specific next step.
- Skipped appears only where intended.
- The validation Flow reported no errors before activation.
- Every Check was tested as a user with real access, not only as an administrator.
- Show Diagnostics and event publication are off unless a process needs them.