Skip to content
Suggest a correction

Configure Check Sets and Checks

Guide14 min read

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.

The steps build an Account handoff review as their example:

RecordLabelAPI nameRequirement
Check SetAccount Handoff ReviewAccount_Handoff_ReviewDefines the card on Account record pages
CheckBilling Country Is CompleteBilling_Country_Is_CompleteBilling Country has a value
CheckAccount Has a ContactAccount_Has_A_ContactThe 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.

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

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:

QuestionAnswer 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 TypeUse it whenExample
Verify with a formulaA Salesforce formula on the record, or on a parent record, can answer it.Billing Country has a value.
Verify with a queryOne SOQL query on related records can answer it.The Account has at least one Contact.
Compare two queriesThe answer compares the results of two separate SOQL queries.Every open Opportunity has a Contact Role.
Verify with ApexA 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.

  1. In Setup, enter Custom Metadata Types in Quick Find, then select Custom Metadata Types.
  2. Next to Record Health Check Set, select Manage Records, then select New.
  3. Enter these values, and select Save.
FieldValueWhat it controls
LabelAccount Handoff ReviewThe name administrators see in Setup and in the Lightning App Builder list.
Record Health Check Set NameAccount_Handoff_ReviewThe API name that Flow, Apex, and the component use.
ObjectAccountThe object the Check Set runs on. It must match the record page’s object exactly.
ActiveClearedKeeps the Check Set out of Lightning App Builder until it is ready.
Card Heading DisplayShow title and subtitleWhether the card shows its title, subtitle, and Run button.
Card TitleAccount Handoff ReviewThe title users see on the card. Required.
Card SubtitleComplete these checks before changing ownership.One line that explains the review.
When Checks RunWhen the user clicks RunUsers select Run when they are ready.
Run Button DisplayShow label and iconHow the Run and Rerun button looks.
Reveal ModeOne by oneEach row appears as its Check finishes. All at once lists every row first.
Passed ChecksShow each passed checkLists passed Checks. Show passed count only shows only the count.
Skipped ChecksShow each skipped checkLists skipped Checks. Show skipped count only shows only the count.
Found/Expected DisplayShow on demandFailed rows show Found and Expected; users open a passing row to see them.
Summary DisplayShow below checksWhere the result counts appear: above, below, or hidden.
Show DiagnosticsClearedKeeps 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.

  1. Return to Custom Metadata Types.
  2. Next to Record Health Check, select Manage Records, then select New.
  3. Enter these values, and select Save.
FieldValue
LabelBilling Country Is Complete
Check SetAccount Handoff Review
Evaluation TypeVerify with a formula
Record Health Check NameBilling_Country_Is_Complete
Evaluation Order10
ActiveCleared
Pass ConditionNOT(ISBLANK(BillingCountry))
Check TitleBilling Country is complete
Message When FailedEnter the verified Billing Country before handing off {!record.Name fallback="this Account"}.
Fix MessageEdit the Account and confirm the country with a reliable source.
Failure SeverityWarning
Action LabelEdit Account
Action URL/lightning/r/Account/{!record.Id}/edit
Applies ToAll records

Pass Condition is a Salesforce formula that must return true or false:

  • true produces PASS, shown as Pass.
  • false produces FAIL, 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.

Create a second Check in the same Check Set:

FieldValue
LabelAccount Has a Contact
Check SetAccount Handoff Review
Evaluation TypeVerify with a query
Record Health Check NameAccount_Has_A_Contact
Evaluation Order20
ActiveCleared
Source QuerySELECT COUNT() FROM Contact WHERE AccountId = {!record.Id}
Source Query FieldLeave blank
How To Read Query ResultsOne row or aggregate
Comparison OperatorGreater than
Expected Value Comes FromFixed value
Expected Value (Fixed)0
Check TitleAccount has at least one Contact
Message When FailedAdd at least one verified Contact before handing off this Account.
Failure SeverityWarning
Applies ToAll 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.

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:

FieldValue
Applies ToWhen 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.

Keep the Check Set and its Checks inactive until validation succeeds.

  1. Run the Validate Record Health Check Configuration Flow action. See Validate configuration before activation for how to build and run the Flow.
  2. Confirm that Configuration Is Valid is true and Error Count is 0.
  3. Correct every error, and decide on every warning.
  4. Edit each Check, select Active, and save.
  5. 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.

  1. Open an Account record, select the gear icon, and select Edit Page.
  2. In the Components panel, search for Record Health Check, and drag the component onto the page.
  3. Set Check Set to Account Handoff Review (Account_Handoff_Review).
  4. 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.

Test in a sandbox, as the user you identified in Before you start.

  1. Open an Account that meets both requirements, select Run, and confirm two Pass rows.
  2. Clear the Billing Country on a test Account, save, and confirm Billing Country is complete shows Warning.
  3. Test an Account with no Contacts and confirm Account has at least one Contact shows Warning.
  4. If you added Applies To or a Prerequisite Check, test a record that should be skipped and confirm Skipped with the expected message.
  5. Select each action link and confirm that it opens the intended page without changing data.
  6. 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.
  7. 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.
Card labelStatusMeaningWhat to do
PassPASSThe record meets the requirement.Nothing.
Failed, Warning, or InfoFAILThe record does not meet the requirement. Failure Severity sets the label.Follow the message and fix instructions.
SkippedSKIPPEDThe 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 CheckUNABLE_TO_EVALUATEConfiguration, access, missing data, or a limit prevented a reliable answer.Check the user’s access and the Check configuration.
System ErrorERRORAn 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.

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

What you seeWhat to check
The Check Set is not in the Lightning App Builder listThe 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 unexpectedlyApplies To, Prerequisite Check, Evaluation Order, and If Query Finds No Records.
Unable to CheckThe running user’s access to every object and field the Check reads, and the formula or query.
Results do not change after an editSelect Rerun. A save in a custom component that does not send a standard refresh does not rerun the card.
  • 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.