Build Checks

Draft Check configuration with AI

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

Pick one Evaluation Type prompt, paste it into an approved AI assistant with your business requirement, then verify every suggested Salesforce API name before entering anything in Setup.

Use this folder as the single place to draft Record Health Check configuration with an AI assistant. An assistant can organize a requirement and suggest fields. It cannot know your org’s fields, sharing, or approved rules unless you provide them. Treat every answer as a draft.

The self-contained prompts are reviewed against the Record Health Check metadata and runtime contract. The offline release gate checks all 63 configurable fields, 21 restricted picklists, the shared prompt block, and one provider-neutral reference draft for each Evaluation Type.

Guide scope and required approvals

Review and approve every AI suggestion before entering it in a production org.
Verify object, field, relationship, Check Set, Check, report, and Apex class API names in the target Salesforce org.
Use approved, non-sensitive inputs that exclude customer data, credentials, Salesforce session details, and other restricted information.
Activate a Check after an administrator has tested pass, fail, skipped, access-restricted, and unable-to-evaluate cases in a sandbox.

Follow your organization’s AI, privacy, security, and change-management policies. Use only an AI product your organization approves. This guide does not require or endorse a particular vendor.

How to use this folder

Fill in the requirement template. The Before you ask section identifies the information the AI needs.
Give this README link to an AI that can open linked pages, together with the filled requirement. Tell it to follow this guide, ask rather than guess, and return a proposal for human review.
The assistant chooses the simplest Evaluation Type that safely expresses the requirement. It must then open the chosen Evaluation Type prompt from the table below and follow that page’s complete prompt block. The assistant should explain why it selected that type and show a materially different alternative only when the requirement leaves a real design choice.
If the assistant cannot open links, use the table to choose the likely Evaluation Type, open its prompt page yourself, and copy the single system-prompt block followed by the filled requirement. Each prompt is self-contained: it carries the shared rules, every Check Set field, and every Check field.
Review the draft against the field references and examples linked from the selected prompt page.
Keep the proposed Check Set and Check inactive. Enter approved values in a sandbox, then follow Test the human-approved draft.
For an unsaved Check, use Validate and preview an AI draft before activation when the Preview component is installed.
Choose and test the complete entry and exit path. A valid evaluation rule is incomplete until its actual caller, execution principal, result destination, consumer, and failure recovery are known.
When the caller or consumer does not exist yet, use the execution workflow generator to draft the Flow, synchronous Apex caller, Queueable, Batch, Scheduled adapter, persistence service, or event receiver. Keep generated source under normal test-first, security-review, and deployment controls.

Capabilities the prompts cover

Capability	What the assistant must decide
Card presentation	Heading, summary placement or hiding, reveal mode, Found/Expected placement, and Run/Rerun controls are independent choices.
Dependencies	Evaluation Order controls presentation; prerequisite dependency order controls execution and may point to a later-displayed Check.
Query-row values	Zero-based row tokens, outer-field selection, business `ORDER BY`, single-row proofs, child-subquery boundaries, and per-record `LIMIT` behavior.
Inline links	Safe `{!link label="..." href="..."}` links in message and display fields, with readable text fallback.
Whole-set limits	More than 25 active Checks rejects the complete Check Set instead of returning a partial result.
Apex extensions	Typed parameter definitions, typed outcomes, evidence, per-record recovery, and optional display-only overrides.
Draft verification	Inactive metadata, detached validation/Preview, representative records, permissions, limits, namespaces, and relevant runtime variations.
Operational boundary	Lightning, Flow, synchronous Apex, Queueable, Batch, or Scheduled entry; direct, event, readiness, diagnostic, or subscriber-owned result exit.

Choose a prompt by Evaluation Type

Where the answer comes from	Evaluation Type	Copy this prompt	Confirm against
Fields on the current record or a formula-reachable parent	Verify with a formula	Formula prompt	Formula examples, Check fields
Records or a value from one SOQL query	Verify with a query	Query prompt	Query examples, Query reference
Two separate SOQL query results	Compare two queries	Compare two queries prompt	Compare two queries examples
Logic that formula and query settings cannot express safely	Verify with Apex	Apex prompt	Apex Check contract, Apex examples

If the requirement must prevent Salesforce from saving a record, use a Validation Rule, record-triggered Flow custom error, or Apex trigger instead. Record Health Check never blocks a save.

Shared authoring rules

Every prompt repeats the merge-token, Check Set, Check, and safety rules from Shared rules word for word. Change that page when product behavior changes, then regenerate the four prompts from it. npm run check:ai-prompts fails when a prompt drifts from the shared block, names a field or stored value the Check metadata does not declare, or stops offering a configurable field to the assistant.

These examples are representative, not the complete token reference:

Record value in SOQL, always unquoted: WHERE AccountId = {!record.Id}
Formatted record value in display text: {!record.Amount format="CURRENCY" fallback="Not available"}
Check and Check Set values in display text: {!rhcCheck.checkTitle} and {!rhcSet.cardTitle}
Result and run values in messages or Display Found/Expected Text: Found {!rhcResult.foundValue}; expected {!rhcResult.expectedValue}. Run {!rhcRun.runId} returned {!rhcResult.status}. {!rhcResult.failedRecordCount} of {!rhcResult.totalRecordCount} contacts are incomplete.
Zero-based query-row value after selecting and deterministically ordering the outer field: SELECT Name FROM Opportunity WHERE AccountId = {!record.Id} ORDER BY CreatedDate ASC LIMIT 1 with Oldest deal: {!rhcQuery.sourceRows[0].Name fallback="none"}.
Query row counts: {!rhcQuery.sourceRowCount} and {!rhcQuery.comparisonRowCount}.
Inline link inside a supported message or display field: {!link label="Open record" href="/lightning/r/Account/{!record.Id}/view"}
Action URL: /lightning/r/Account/{!record.Id}/related/Contacts/view

rhcResult properties are status, foundValue, foundValuePluralSuffix, expectedValue, failedRecordCount, totalRecordCount, and reasonCode. Do not put rhcResult tokens in SOQL or Action URL. rhcQuery is available only to Query and Compare Two Queries Checks after the addressed query runs; row indexes start at zero, child-subquery fields are opaque, and a multi-row query needs an explicit business ORDER BY. Do not use Flow/API names such as evaluation.found or actualValue as merge tokens.

Full token list: Merge syntax.

Before you ask an AI assistant

Question	Example answer
Which Salesforce object is checked?	Account (`Account`)
What must be true?	The Account has at least one Contact.
Where does the answer come from?	Contact records related through `Contact.AccountId`.
What should happen when no Contact exists?	Fail.
What should users see?	Add at least one verified Contact before handoff.
Does the Check apply to every record?	Yes.
Should it block a save?	No. It is guidance during an Account handoff.
Which users will run it?	Account managers with access to the Contacts they manage.

Copy API names from Setup → Object Manager → [Object] → Fields & Relationships. Open the field and copy Field Name. Do not provide a label such as “Customer Tier” and expect the assistant to guess whether the API name is Customer_Tier__c.

Review the proposed Check Set and Check

Confirm Check Set values against Check Set fields. Confirm Check values against Check fields and a matching page in the examples library.

Do not approve a draft unless it explains PASS, FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR. Sharing matters: a hidden related record is not counted, and missing object or field access can produce UNABLE_TO_EVALUATE.

For Apex drafts, a developer must review, test, and deploy the class before anyone enters the class name in Check metadata. See the Apex prompt and Apex Check contract.

Human review ownership

Review	Required human decision
Business owner	What passes, fails, and skips; severity; wording; and whether the result is useful enough to activate.
Salesforce administrator	Exact API names, Setup values, Check Set membership, sharing behavior, permission assignments, page placement, and sandbox evidence.
Apex and security reviewer	Every custom class, user-mode data access, bulk behavior, parameter definition, evidence disclosure, display-only behavior, and prohibited actions.
Integration owner	Platform Event publication, receiving automation, retention, retry behavior, and monitoring.

AI output never completes these approvals. A person must reread the final configuration after the last edit; an earlier review does not cover a changed formula, query, JSON value, message, or link.

Test the human-approved draft

In sandbox Setup, open Custom Metadata Types → Record Health Check Set → Manage Records → New, then enter the approved Check Set with Active unchecked.
Open Custom Metadata Types → Record Health Check → Manage Records → New, then enter the approved Check with Active unchecked.
Review the saved values in Setup; do not rely on the AI response as the source of truth.
Run detached Validate and Preview first when available. Activate the Check and Check Set only for controlled sandbox testing.
Test a record that should pass.
Test a record that should fail.
Test every intended skip condition, including prerequisites and zero-row choices.
Test as a user with restricted sharing.
In a sandbox-only test, remove access to a required field and confirm UNABLE_TO_EVALUATE. Restore access afterward.
Confirm messages and action links remain useful without diagnostics.
Obtain the business owner’s approval before moving the configuration to production.

Review checklist

Correct an AI draft

Problem	Correct response
It invents an API name	Stop and copy the exact API name from Salesforce Setup.
It prefixes a new Check Set or Check with `rhc__`	Remove the invented namespace. Administrator-owned metadata normally has no managed-package prefix.
It chooses a Check included with the package when you need your own rule	Create an administrator-owned Check with a name that normally has no `rhc__` prefix.
It uses `{!record.id}`, `{!Id}`, `{!$Record.Id}`, `:recordId`, or quoted `'{!record.Id}'`	Replace with Record Health Check merge tokens only. In SOQL use `{!record.Id}` unquoted; copy field API names from Setup.
It puts merge tokens in Pass Condition	Rewrite as a Salesforce formula (`NOT(ISBLANK(BillingCity))`). Merge tokens belong in queries, messages, and Action URLs.
It assumes zero query rows should pass or fail	Ask the business owner; then configure If Query Finds No Records where the Evaluation Type uses it.
It omits Evaluation Type	Every Check needs `EvaluationType__c`. There is no default.
It stores a Setup label instead of the stored value	Enter the stored value: Skip is `SKIP`, and When a count query matches is `WHEN_COUNT_QUERY_MATCHES`. Confirm each one in Check fields.
It proposes `N/A` for Formula Result Type or another metadata field	Use the field’s deployable stored value, or omit an unused field from metadata. Use `AUTO` for Formula Result Type unless a Query Check’s Expected Value or Value-to-find operand formula has a verified exact type.
It recommends Record Health Check to prevent a save	Use a Validation Rule, Flow custom error, or Apex trigger.
It recommends an Apex example class that is not installed	Create, test, and deploy the class, or choose a metadata-only Evaluation Type.
It says a hidden related record is clean data	Correct the wording: the Check evaluates only records visible to the running user.
It omits `UNABLE_TO_EVALUATE` and `ERROR` testing	Add access, configuration, and unexpected-error test cases before approval.