Reference
Feature catalog
Detailed page. Use “On this page” to jump directly to the section you need.
Use this catalog to find setup instructions and supported behavior. It describes this checkout; version availability identifies additions that are not yet in the published package.
Record Health Check is a read-only evaluation framework. It explains record health; it does not change business records, block saves, or keep a permanent result history by itself.
Configure Check Sets and Checks
Section titled “Configure Check Sets and Checks”| Capability | Supported behavior | Detailed guide |
|---|---|---|
| Custom Metadata configuration | Check Sets define one record-page review; Checks define the questions in that review. Configuration can move through normal Salesforce metadata processes. | Configure Check Sets and Checks |
| Record-object matching | A Check Set names one Salesforce object. The App Builder picker shows active Check Sets matching the record page’s object. | Configure the component |
| Automatic and Manual runs | Automatic (RUN_ON_LOAD) cards evaluate after loading. Manual (RUN_ON_REQUEST) cards wait for Run and preserve that boundary until the first completed run. | Choose how Checks run |
| Card presentation | Configure title, subtitle, summary, all-at-once or one-by-one reveal, passed and skipped visibility, Found/Expected disclosure, and Run/Rerun button labels, icon, and visibility. | Check Set fields |
| Ordered Checks and categories | Evaluation Order controls presentation order. Prerequisite references control dependency scheduling. Category groups summaries without changing the outcome. | Check fields |
| Applicability | A Formula, count Query, both, or neither can decide whether a Check applies. A non-applicable Check is SKIPPED, not PASS. | Configure Checks |
| Prerequisites | A Check can wait for another Check and skip when the required result does not permit evaluation. Dependency cycles are rejected. | Check fields: Prerequisite Check |
| Stop after a system error | A Check Set can stop launching later Checks after a system error while preserving results already completed. | Check Set fields |
| Configuration validation action | Validate Record Health Check Configuration audits Check and Check Set metadata and returns error, warning, and JSON report outputs. | Flow action inputs and outputs |
Evaluate record health
Section titled “Evaluate record health”| Evaluation Type | Supported behavior | Detailed guide |
|---|---|---|
Formula (FORMULA) | Evaluate current-record and supported relationship fields with Salesforce FormulaEval. Declare the result type, decide the Pass condition, and optionally calculate separate display values. | Formula reference |
Query (QUERY) | Run user-mode SOQL within the configured row limit for one value, any-row, all-rows, list membership, or list comparison behavior. Configure no-row, empty-value, and maximum-row outcomes explicitly. | Query reference |
Compare two queries (COMPARE_TWO_QUERIES) | Compare two counts, individual values, or lists, including overlap, contains-all, and exact-list behavior. | Compare two queries |
Apex plugin (APEX) | Run reviewed bulk Apex implementing RecordHealthCheckPlugin, returning exactly one typed outcome for every requested record ID. | Write an Apex Check |
| Typed plugin definitions | Optional definitions declare integer, choice, string, and Boolean parameters, defaults, bounds, help, nullability, and scope capacity. | Plugin definitions |
| Typed outcome builders and per-record recovery | Equality/list builders reject contradictory values, while bounded per-record recovery isolates ordinary record failures. | typed outcomes |
| Typed plugin evidence | Plugins can attach bounded evidence rows with synthetic or permission-checked field provenance. | plugin evidence |
| Apex presentation overrides | Optional display plugins add rich values, guidance, safe actions, labels, and formats without changing evaluation. | Apex presentation |
| Plugin contract verification | Extend the packaged contract-test support class to verify bulk query growth, complete scope coverage, permission behavior, and prohibited side effects. | Verify an Apex Check |
| Bulk query planning | Formula, Query, and Apex load and evaluate as many as 200 requested records together. | Bulk-query grammar |
Explain and display results
Section titled “Explain and display results”| Capability | Supported behavior | Detailed guide |
|---|---|---|
| Honest outcomes | Results distinguish PASS, FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR. Failed, Warning, and Info are severity presentations of FAIL. | Statuses and labels |
| Stable Reason Codes | Programmatic reasons distinguish business outcomes from access, configuration, data, and framework problems. | Reason Codes |
| Found and Expected values | Show raw evaluation evidence or administrator-authored display formulas/text without changing the verdict. | Display Found and Expected |
| Display formats | Automatic, Number, Currency, Percent, Ratio as percent, Checkbox, Date, Date/Time, Text, and Raw formats follow the running user’s locale where applicable. | Display formats |
| Lists and multiple currencies | List previews show no more than the documented limit. Each value retains its own available currency identity; formatting does not convert currencies. | List previews |
| Guidance and actions | Failure, unable, applicability, and fix messages support safe merge tokens. Optional Action Label and Action URL provide a read-only next step. | Configure action links |
| Merge tokens | Record, result, Check, Check Set, and run values can be inserted into messages and safe links with typed formatting and explicit fallbacks. | Merge syntax |
| Inline links and grouped display | Explicit link nodes, record links, line breaks, and ordered groups render through bounded same-org/HTTPS URL policy with plain-text fallback. | structured presentation |
| Diagnostics | Authorized viewers can see restricted diagnostic evidence and produce a redacted support report. Ordinary users receive safe guidance without internal details. | Browser diagnostics |
| Diagnostic contract 2.0 | Opt-in Apex diagnostics expose bounded, value-free incident coordinates and lifecycle traces with sanitized compiler categories. | Authorized diagnostics |
| Detached draft preview | Administrators can validate or execute one unsaved Check against its saved Check Set without publishing events. | Validate and preview a draft |
| Readiness receipts | Explicit, private, 30-day receipts bind verification to the exact actor, org, definition, capabilities, and record scope. | Readiness receipts |
| Localization and accessibility | Labels can use Salesforce translations; values follow locale and timezone rules. The card supports keyboard use, responsive layout, SLDS 1, SLDS 2, and the active Salesforce theme. | Languages and locales, theme and accessibility |
Run from Salesforce and integrations
Section titled “Run from Salesforce and integrations”| Entry point | Supported behavior | Detailed guide |
|---|---|---|
| Lightning record page | One component runs the selected Check Set for the current record. It is intentionally unavailable on App and Home pages because those pages have no record context. | Lightning record page |
| Record Health Check Preview | A separate administrator component validates and previews a detached Check from a Lightning App page, Home page, or tab. It does not save or activate metadata. | Validate and preview a draft |
Save and RefreshView refresh | Automatic cards refresh after a standard record save or refresh notification. Manual cards refresh only after their first completed Run. Stale and overlapping runs cannot replace newer results. | Record-save refresh |
| Flow | Separate actions run one Check or one Check Set and return stable status, count, reason, and JSON outputs. A third action validates configuration. | Flow guides |
| Synchronous Apex | RecordHealthCheck.evaluate accepts a typed request for one Check or Check Set. Result modes provide complete evaluation (EVALUATION), evaluation with display (EVALUATION_WITH_DISPLAY), or summary plus actionable results (SUMMARY). | Run from Apex |
| Queueable Apex | Submit up to 200 known record IDs for later execution and monitor the Apex job ID. | Queueable |
| Batch Apex | Evaluate larger record selections in limited groups, with query and explicit-ID submission options. | Batch |
| Scheduled Apex | Start reviewed Queueable or Batch work on a Salesforce schedule. There is no direct Future-method API; existing Future callers should move to Queueable. | Scheduled, replace Future |
| Agentforce | Packaged agent actions run one Check or Check Set and return the versioned diagnostic contract without exposing restricted record details. | Agentforce actions |
| REST agent tool | A versioned REST adapter exposes Check and Check Set operations for authorized integration users. | Agent tool REST API |
| MCP service | The companion Node service maps MCP tools to the versioned REST contract, with documented authorization, timeouts, and deployment checks. | Deploy the MCP service |
| Versioning and correlation | Contract versions protect long-lived consumers. Run IDs, correlation IDs, and execution origins connect work and diagnostics across transaction boundaries. | Contracts, integration options |
Publish and receive results
Section titled “Publish and receive results”| Capability | Supported behavior | Detailed guide |
|---|---|---|
| Event publication modes | NONE, ACTIONABLE, and ALL decide whether no Check Result events, only results needing attention, or every result is published. | Choose where results go |
Check Result event (Record_Health_Check_Result__e) | Publishes one selected Check outcome with versioned identity, status, evidence, and diagnostic fields. | Check Result metadata |
Check Set Run event (Record_Health_Check_Set_Run__e) | Publishes run lifecycle and summary counts, including the completion heartbeat used with actionable-only publication. | Check Set Run metadata |
Error Log event (Record_Health_Check_Log__e) | Publishes restricted operational incidents only when enabled and authorized. | Error Log metadata |
| Flow, Apex, and Pub/Sub consumers | Subscribers can route events to approved storage, automation, or external systems. Events are not permanent storage themselves. | Save results, Pub/Sub |
Security and safety
Section titled “Security and safety”Choose the narrow Permission Set for the task instead of treating these as a progression of access:
| Permission Set |
|---|
| Record Health Check Admin |
| Record Health Check Card User |
| Record Health Check User |
| Record Health Check Diagnostics Viewer |
| Record Health Check MCP Integration |
| Record Health Check Error Log Publisher |
| Record Health Check Readiness Auditor |
| Capability | Supported behavior | Detailed guide |
|---|---|---|
| User-context access | Business-record reads use user mode, and Apex plugins run with sharing. The package does not grant access to subscriber business objects or fields. | Security and data access |
| Purpose-specific access | Seven Permission Sets separate card, automation, administration, integration, diagnostic viewing, restricted logging, and read-only readiness review. | Permission Sets |
| Run and diagnostic permissions | Record Health Check Run authorizes execution. A direct Record Health Check Admin or Record Health Check Diagnostics Viewer Permission Set assignment authorizes restricted diagnostic detail when the Check Set also enables it. | Custom Permissions |
| Plugin side-effect protection | Plugin dispatch rejects detected record writes, callouts, email, Queueable, and Future work. Platform Event, Batch, and Scheduled prohibitions also require contract tests, static analysis, and review because Apex exposes no complete transaction counter for them. | Verify an Apex Check |
| Safe templates and links | Query templates, merge tokens, and Action URLs are validated and checked against their documented limits. Unsupported or inaccessible inputs return an unable-to-evaluate result instead of a guessed verdict. | Merge syntax, bulk-query grammar |
| Namespaced configuration | Qualified API names and foreign-package field namespaces are preserved exactly across package and subscriber metadata. | Names and API identities |
| Request and field limits | Record, Check, query-row, FormulaEval, token, field-size, and output limits are documented and enforced. | Field limits |
Package, examples, and operations
Section titled “Package, examples, and operations”| Capability | Supported behavior | Detailed guide |
|---|---|---|
| Immutable 2GP package versions | Install a specific 04t version and test that same version in a sandbox before upgrading production. | Choose a package version |
| Install, upgrade, and uninstall | Guides cover sandbox-first installation, permission assignment, configuration backup, N-1 upgrade rehearsal, and safe uninstall preparation. | Install |
| Packaged examples | Four active Example Check Sets contain 50 Checks across Account, Contact, and Opportunity. Matching docs explain Formula, Query, Compare two queries, Apex, applicability, display, and remediation patterns. | Explore installed examples, examples library |
| Production operations | Back up subscriber-owned Custom Metadata, monitor events and jobs, test least-privilege users, and preserve evidence for support. | Production operations |
Explicit boundaries and non-features
Section titled “Explicit boundaries and non-features”| Boundary | Current behavior | Detailed guide |
|---|---|---|
| No record mutation or enforcement | The framework advises. Use Validation Rules, Flow, or Apex when Salesforce must block or perform an action. | When to use Record Health Check |
| No automatic history store | API responses and optional Platform Events are transient until an approved subscriber saves them. | When to use Platform Events |
| No generic freshness evaluator | Express freshness through Formula, Query, Compare two queries, or reviewed Apex using explicit timestamps or provenance. | Derived values and freshness |
| Formula globals | $User, $Profile, $Setup, $Permission, and $CustomMetadata are not treated as checked-record fields and are not supported in a Pass Condition. | Formula limitations |
| Polymorphic owners | User-only owner formulas cannot reliably evaluate Queue or Group owners and return unable instead of guessing. | Polymorphic relationships |
| Account activity example | The packaged Apex example counts only completed Tasks and Events whose WhatId is the Account. It does not count Contact WhoId activity or shared relations. | Activity limitations |
| Person Accounts | Generic Contact-count examples can count the underlying PersonContact. Use explicit Person Account applicability and fields. | Person Accounts |
| Currency conversion | Display preserves available currency identity but does not perform corporate, dated, or Advanced Currency Management conversion. | Currency limitations |
| Save refresh events | Browser save refresh uses the non-publishing lifecycle; it does not publish Check Result or Check Set Run events unless a normal configured run requests publication. | Record-save refresh |
| Unsupported query shapes | Unsafe or unsupported SOQL shapes, inaccessible schema, row-cap overflow, and unprovable values return unable rather than a partial verdict. | Platform limitations |