FAQs

Setup and troubleshooting FAQ

Detailed page. Use “On this page” to jump directly to the section you need.

Find short answers about setup, permissions, and unexpected results.

Use this page for package setup, permissions, data access, operations, integration, source, and platform edge cases. For purpose, fit, and rollout questions, use Using Record Health Check.

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?

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 and the alternative if Diagnostics Viewer is absent.

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?

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?

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?

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?

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?

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 Lifecycle events.

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?

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?

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?

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 packaged test record setup

Packaged test setup can fail with an Account or related-object validation, required-field, trigger, or flow error when an administrator explicitly runs packaged tests, chooses Run All Tests, or deploys package source into a customized org. The error is raised by subscriber automation reacting to packaged test data setup.

Ordinary subscriber RunLocalTests does not select the installed namespaced package tests. Confirm that the failing stack is Framework fixture DML and report unclear cases through the project support channel. Do not disable production automation merely to make the Framework test fixture pass.

Current packaged tests avoid business-object DML. Follow Upgrade and revalidate to test the latest release in a sandbox.

Why does the package contain so many Apex classes?

The current source contains 223 packaged classes, including 114 test classes. Its verification test suite covers 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?

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?

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?

Each transaction remains subject to Salesforce governor limits, query-row limits, response-size limits, and the framework’s documented record limits. Use synchronous entry points for interactive work within those limits, Queueable for background work within those limits, and Batch for explicit lists of up to 2,000 record IDs. A completed Apex job can still contain FAIL, SKIPPED, UNABLE_TO_EVALUATE, or ERROR health results. See the API overview.

Can Checks run for many records or on a schedule?

Yes. Queueable supports background execution within the configured limits. Batch accepts an explicit list of up to 2,000 record IDs and processes a configurable scope of 1–200 records per transaction, defaulting to 100. 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?

The package adds its own Apex, Lightning component, Custom Metadata Types, Permission Sets, Custom Permissions, Platform Events, and examples. 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?

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?

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?

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?

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 the Apex Check contract.

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?

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 and revalidate.

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?

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 Upgrading and Uninstall and rollback.

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?

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?

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?

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?

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.