Setup and troubleshooting FAQ
Find short answers about setting up and operating Record Health Check: installation, permissions, data access, Platform Events, scale, integration, upgrades, and platform edge cases. For questions about purpose, fit, and rollout, see Using Record Health Check.
Should I install the package or deploy from source?
Section titled “Should I install the package or deploy from source?”Install the namespaced unlocked package (rhc) for production, sandboxes, and evaluation orgs.
Choose the current stable 04t ID from Package versions.
Deploying unpackaged source is a repository development workflow, not an installation path. Use the promoted package for an installed org. See Source development.
Which installed permission set should I assign?
Section titled “Which installed permission set should I assign?”Assign Record Health Check Card User when only the Lightning card is required. Assign Record Health Check User to automation principals that also need Flow, Agent, REST, Apex, Queueable, Batch, or Scheduled entry points. Assign Record Health Check Admin to administrators who configure the package. For troubleshooting as an existing Card User or User, add Record Health Check Diagnostics Viewer temporarily and enable Show Diagnostics on the Check Set. Admin already includes diagnostic access. See Permission Sets for the complete choices.
These permission sets do not grant access to Account, Contact, Opportunity, Case, or custom-object data. See Security and data access.
What Salesforce access does evaluation use?
Section titled “What Salesforce access does evaluation use?”The transaction runs with the access of the person or automation that starts it. Package business record queries use user mode, so Salesforce object access, field access, record sharing, restriction rules, and scoping rules apply. A zero-row result means no matching visible row was found; it does not prove that no hidden row exists elsewhere in the org.
Does evaluation require an external service or network connection?
Section titled “Does evaluation require an external service or network connection?”No. Formula, Query, Compare Two Queries, and packaged Apex evaluation run inside Salesforce. Core evaluation does not require a Named Credential, Remote Site Setting, external runtime, or outbound callout. Optional integrations created outside the core package have separate connectivity and data-handling requirements.
Does the package run in system mode?
Section titled “Does the package run in system mode?”Business-record queries run in user mode and package service classes use sharing-aware boundaries. Configuration Custom Metadata loads after run authorization because it defines the rule rather than granting business-record access. Diagnostics require a direct packaged Admin or Diagnostics Viewer Permission Set assignment. See Security and data access.
How are inaccessible records and fields reported?
Section titled “How are inaccessible records and fields reported?”The public result fails closed as UNABLE_TO_EVALUATE without revealing restricted details. When
diagnostics are enabled on the Check Set and the running user has a direct packaged Admin or
Diagnostics Viewer Permission Set assignment, the detail can distinguish record visibility, field
access, invalid metadata, and other causes.
Do not enable diagnostics broadly or leave them enabled after an investigation.
Are lifecycle events enabled by default?
Section titled “Are lifecycle events enabled by default?”No. Check Set Run, Check Result, and restricted Error Log publication are off by default. Automatic page-load runs never publish. Enable publication only after the receiving Flow, Apex trigger, or integration is ready and the appropriate event permissions are assigned. See Decide when to use Platform Events.
Is refreshing the page the same as selecting Rerun?
Section titled “Is refreshing the page the same as selecting Rerun?”No. A page refresh or a standard Lightning record save can start a non-publishing evaluation. Rerun is an explicit user action and can publish when the Check Set enables publication. A manual Check Set still waits for its first Run; after results exist, later saves refresh them. These paths can show current results, but only the explicit action is eligible to publish lifecycle result events.
I changed a Check in Setup. Do I need to refresh the record page?
Section titled “I changed a Check in Setup. Do I need to refresh the record page?”No. Run and Rerun read the Check Set configuration again before evaluating anything, so the next run reflects Setup edits made while the record tab stayed open. A Check you activated appears, a Check you deactivated disappears, and a changed threshold, label, or display setting takes effect.
This matters most in a console, where a record tab can stay open for days. Without the reread, the card would keep replaying whichever configuration happened to be current when the tab was first opened, and the results would look stale for no visible reason.
Two details worth knowing:
- The card keeps the previous results on screen while it rereads the configuration. The button shows a spinner and the rows are replaced when the new run starts. The card is not stuck.
- If the configuration reread fails, the card shows an error instead of evaluating. It will not quietly fall back to the configuration it loaded earlier, because that would report a result against rules the administrator has already changed.
A record save refreshes the card the same way when results are already on screen, which means an automatic card or a manual card after its first Run. That refresh rereads the configuration too, but it clears the rows and shows the card spinner while it runs, rather than holding the previous results the way Rerun does.
Why does a Check pass on the record page but differ in Flow or asynchronous Apex?
Section titled “Why does a Check pass on the record page but differ in Flow or asynchronous Apex?”Each Salesforce transaction uses its actual running user’s authorization and user-mode data access.
A Flow, Queueable, Batch, or scheduled transaction can therefore see a different permitted record
scope than the interactive card. Timezone-sensitive formulas can also cross their cutoff at a
different wall-clock time. Formula globals such as $User are not supported in record-context
Formula Checks and return an unable-to-evaluate result rather than changing behavior for the caller. Use the
execution-context troubleshooting guide to compare the execution
user, permissions, visible rows, timezone, job ID, Run ID, and Reason Code before changing the
Check.
Should packaged test classes or the test factory be modified?
Section titled “Should packaged test classes or the test factory be modified?”No. Subscribers must not edit packaged Apex, including RecordHealthCheckTestDataFactory and
packaged test classes. Org-specific plugins and their tests belong in the subscriber’s repository.
This product is a namespaced unlocked package. Ordinary subscriber RunLocalTests skips its
installed namespaced tests, while Setup Run All Tests, namespace-qualified explicit test runs,
and package-source deployments can execute them against subscriber validation rules, triggers, and
flows.
Package installation and upgrade also compile the packaged Apex tests.
Resolve a packaged test failure
Section titled “Resolve a packaged test failure”Packaged tests in this release create no Account, Contact, Opportunity, Case, or other business records; they give test records synthetic IDs instead. Validation rules, required fields, triggers, and Flows on those objects therefore cannot make them fail.
Ordinary subscriber RunLocalTests does not select the installed namespaced package tests. If a
packaged test fails when an administrator runs it explicitly, chooses Run All Tests, or deploys
package source, confirm that the org runs the latest release, as described in
Upgrade an installation. Then report the test name and the first stack
trace line through the project support channel. Do not disable production automation to make a
packaged test pass.
Why does the package contain so many Apex classes?
Section titled “Why does the package contain so many Apex classes?”Version 2.0.11 contains 352 packaged Apex classes, including 166 test classes. The tests cover dynamic SOQL, formulas, metadata, Salesforce access, bulk and asynchronous execution, integrations, and failure diagnostics. See the complete size breakdown.
How is configuration backed up and promoted?
Section titled “How is configuration backed up and promoted?”Check Sets and Checks are Custom Metadata. Retrieve organization-owned records into source control or move them through an approved Salesforce metadata process. Include both the Check Set and its Checks, validate references, and prove restoration in a sandbox. See Back up and restore configuration.
Are results transaction history or permanent storage?
Section titled “Are results transaction history or permanent storage?”No. A synchronous response is the result for that request, and a Platform Event is a message, not a database of record. Permanent history requires an explicitly designed receiver and storage object with retention, access, replay, and duplicate-handling rules. See Choose where results go.
Which limits affect scale?
Section titled “Which limits affect scale?”Each transaction remains subject to Salesforce governor limits, query-row limits, response-size
limits, and the framework’s documented record limits. A direct Apex or Flow request handles up to
200 records, the packaged Queueable job up to 200 known IDs, and the packaged Batch and Scheduled
jobs up to 2,000 known IDs; your own Batch class can process any number of records a query finds.
Formula Checks add one more limit: a transaction allows 95 formula evaluations, and each Formula
Check uses one per record, so a Check Set with one Formula Check fits at most 95 records in one
transaction. A completed Apex job can still contain FAIL, SKIPPED,
UNABLE_TO_EVALUATE, or ERROR health results. See the Developer guides.
Can Checks run for many records or on a schedule?
Section titled “Can Checks run for many records or on a schedule?”Yes. The packaged Queueable job checks up to 200 known record IDs in the background. The packaged Batch job accepts an explicit list of up to 2,000 record IDs and processes 1–200 records per transaction, choosing up to 100 by default. Scheduled Apex launches the packaged Batch for a saved explicit list. These entry points do not create permanent result storage by themselves; choose the result destination as part of the design. See Batch Apex and Scheduled Apex.
Does installation consume or alter existing business-object schema?
Section titled “Does installation consume or alter existing business-object schema?”The package adds its own Apex classes, two Lightning components, two Custom Metadata Types, one custom object for readiness receipts, seven Permission Sets, one Custom Permission, three Platform Events, and four example Check Sets. It does not add fields to Account, Contact, Opportunity, Case, or a custom business object. Configuration refers to existing object and field API names, so renaming a label is different from removing or changing the referenced API field.
What happens when a referenced field or installed product is removed?
Section titled “What happens when a referenced field or installed product is removed?”Metadata validation reports unresolved objects, fields, relationships, or incompatible Check configuration. Runtime evaluation returns an explicit unable-to-evaluate or error outcome rather than silently passing. Validate configuration after schema, package, sharing, currency, or feature changes and before promotion to production.
What does the rhc namespace mean?
Section titled “What does the rhc namespace mean?”rhc identifies metadata owned by the installed package. Packaged Custom Metadata records return
a QualifiedApiName prefixed with rhc__; records created by the subscriber do not. Apex, Flow,
Lightning, and event boundaries require the exact QualifiedApiName Salesforce returns. Do not
construct it by guessing whether the prefix applies. See
Configuration identity.
Which interfaces are supported for extension?
Section titled “Which interfaces are supported for extension?”Use only the documented global Apex API, Flow actions, Agentforce actions, REST resource, lifecycle
events, and RecordHealthCheckPlugin contract. Internal public package classes are not subscriber
APIs in a namespaced installation. Treat undocumented implementation classes and response details
as changeable. See the integration overview.
When should a custom Apex Check be used?
Section titled “When should a custom Apex Check be used?”Use Formula, Query, or Compare Two Queries when they can express the rule. Use a custom Apex Check only when the decision requires supported logic that those evaluation types cannot provide. The class must be bulk-safe, sharing-aware, user-mode for record access, and free of data changes, callouts, email, event publication, and asynchronous work. Run the supplied contract tests before deployment. See Write a custom Apex Check.
Can the package call an external system during a Check?
Section titled “Can the package call an external system during a Check?”Core and custom Apex Check contracts do not allow callouts during evaluation. Retrieve or synchronize external information through a separately governed integration, store the approved decision input in Salesforce, and evaluate that visible Salesforce value. This keeps runtime results within the documented limits and avoids hiding an external dependency inside a record-page check.
How are upgrades and compatibility changes tested?
Section titled “How are upgrades and compatibility changes tested?”Release validation covers namespaced and no-namespace source shapes, package installation, subscriber-style behavior, and upgrade preservation of organization-owned Custom Metadata. A production rollout still requires sandbox validation against the destination org’s licenses, schema, permissions, Checks, and integrations. See Upgrade an installation.
Does an upgrade overwrite organization-owned Check configuration?
Section titled “Does an upgrade overwrite organization-owned Check configuration?”Organization-owned Custom Metadata is separate from package-owned examples, and release validation includes an upgrade path that checks preservation of organization-owned Check Sets and Checks. Package-owned examples remain package content and can change in a later version. Back up all required configuration and prove the exact upgrade in a representative sandbox before production.
How do I recover from an unsuccessful rollout?
Section titled “How do I recover from an unsuccessful rollout?”Back up configuration before a rollout, stop promotion when sandbox results are not acceptable, and use the documented removal and recovery process when necessary. See Upgrade an installation and Uninstall Record Health Check.
Does Record Health Check support single- and multi-currency orgs?
Section titled “Does Record Health Check support single- and multi-currency orgs?”Yes, within the documented display and comparison rules. The package does not convert money between currencies. Query and Compare Two Queries Checks reject reachable mixed currency units; fixed currency thresholds require an explicit ISO basis. Cross-currency conversion requires a reviewed custom Apex Check with an explicit rate and rounding policy. See Compatibility: Multiple currencies.
Why can Person Account Checks behave differently between orgs?
Section titled “Why can Person Account Checks behave differently between orgs?”Person Account fields exist only where Person Accounts is enabled. A Check copied to an org
without those fields can return UNABLE_TO_EVALUATE or FIELD_NOT_RESOLVED. Packaged examples
avoid Person Account-only fields. Confirm the feature and required fields in the destination org.
See Compatibility: Person Accounts.
Why can an Owner formula behave differently for Queue or partner-owned records?
Section titled “Why can an Owner formula behave differently for Queue or partner-owned records?”User-only fields on polymorphic Owner relationships require an explicit path such as
Owner:User.IsActive. Even then, a Queue or Group owner is not a User and can produce
UNABLE_TO_EVALUATE. A Query that counts active Users instead returns zero and can intentionally
produce FAIL. Choose the pattern that expresses the required business meaning. See
Formula ownership checks.
Why does a Query Check ignore records in the Recycle Bin?
Section titled “Why does a Query Check ignore records in the Recycle Bin?”Record Health Check rejects ALL ROWS; soft-deleted records are not part of Query results. Restore
the record or use a purpose-built administrative process. See
Platform limitations.
Where should an unexpected result be investigated?
Section titled “Where should an unexpected result be investigated?”Start with Troubleshoot with Show Diagnostics. Confirm the exact Check identity, running user, record and field access, evaluation type, reason code, and whether the result differs by access context. Do not treat a broad-access successful result as access proof for more restricted transactions.