Merge syntax
Insert values from the Salesforce record, the Check, the Check Set, the result, the run, or the
Check’s query rows into a Record Health Check message, Action Label, Action URL, or SOQL query with
merge tokens such as {!record.Name}. This page lists every supported token, where each one can
be used, how fallbacks work, and what happens when a token is invalid or empty. For Action URL
patterns, see Add a fix link.
A merge token is a placeholder in a failure message, Fix Message, Action Label, Action URL, Found or Expected display text, or SOQL template. An inline-link token adds one safe link inside supported display text. When the Check runs, Record Health Check replaces the placeholders with live values from the current record, Check, Check Set, result, or run.
Every merge token has two parts separated by a period:
{!record.Name}| Part | Meaning |
|---|---|
| Namespace | The first part, which says where the value comes from: record, rhcCheck, rhcSet, rhcResult, rhcRun, or rhcQuery |
| Property | Which field or metadata value to insert, such as Name or checkTitle |
Record-field tokens can also contain quoted format and fallback settings:
{!record.Amount format="CURRENCY" fallback="Not available"}format controls how the value is written, and fallback supplies text for an empty value. Both are
described below: Format a field value and Fallbacks. The two
settings may appear in either order. Their names are lowercase, their values must use double quotes,
and a repeated, unknown, or unquoted setting is a configuration error (MALFORMED_TOKEN).
Curly braces are reserved for merge tokens. A { or } anywhere else in a template, even in plain
wording, is a configuration error (MALFORMED_TOKEN), and there is no escape sequence for a literal
brace. The older pipe form, {!record.Name|this record}, is also rejected; write
fallback="this record" instead.
Use a fallback when the value might be blank and empty wording would confuse the reader. A bare
token is enough when no substitute is needed or the value is always present, such as
{!record.Id}.
For example:
Review {!record.Name fallback="this record"} before approval.Live Name | Completed text |
|---|---|
Acme | Review Acme before approval. |
| blank | Review this record before approval. |
The same token without a fallback ({!record.Name}) still becomes Acme when Name has a value.
When Name is blank, it inserts nothing, so the sentence reads Review before approval.
Examples by value source
Section titled “Examples by value source”Most messages and queries use the current record:
{!record.Name}{!record.Owner.Name}{!record.BillingCountry}After the Check finishes, use result and run values in the completed message:
{!rhcResult.foundValue}{!rhcResult.expectedValue}{!rhcRun.runId}Use Check and Check Set tokens when the message should name the check or card:
{!rhcCheck.checkTitle}{!rhcSet.cardTitle}An unknown first part or property is a configuration error. Every token must include one of the
documented value sources; {!Id} is therefore rejected.
Empty tokens behave differently in display text (including Action Label), Action URLs, and SOQL. See Fallbacks.
When a Check cannot be prepared, for example because its configuration is invalid or the running user cannot read a field it uses, tokens cannot be filled in. A Message When Unable To Evaluate that contains any token is then replaced by the standard message, “This check could not be evaluated. Contact your administrator.”
Where merge tokens can be used
Section titled “Where merge tokens can be used”| Location | Where it appears | Allowed value sources |
|---|---|---|
| Display text | Message When Failed, Message When Unable To Evaluate, Message When Not Applicable, Fix Message, Action Label (80 saved characters; defaults to Fix this when blank and Action URL is valid), Display: Found Text, and Display: Expected Text | record, rhcCheck, rhcSet, rhcResult, and rhcRun when that value is available at that point in the run. rhcQuery everywhere except Message When Not Applicable, where the Check’s queries never ran |
| Action URL | Action URL on a Check | record, rhcCheck, rhcSet, rhcRun, rhcQuery (result tokens are not allowed); each inserted value is URL-encoded before the URL safety check |
| SOQL | Source Query, Comparison Query, and applicability count queries | record only |
Inline links inside display text
Section titled “Inline links inside display text”Record Health Check can place a link inside Message When Failed, Message When Unable To
Evaluate, Message When Not Applicable, Fix Message, Display: Found Text, and Display:
Expected Text. Use the exact link token with both required attributes:
Review {!record.Name fallback="this record"}. {!link label="Open record" href="/lightning/r/Account/{!record.Id}/view"}label and href may appear in either order. A normal value token can appear inside either quoted
attribute. Escape a literal double quote as \" and a literal backslash as \\. Do not nest one
inline link inside another.
Inline links are not accepted in Action Label, Action URL, SOQL, or formula fields. Use Action Label and Action URL for one primary failure action. Use an inline link when the link belongs inside explanatory text or when a display value needs more than one contextual destination.
The destination must be either:
- a same-org path beginning with
/; or - an absolute
https://URL with a fixed host.
A merge token can supply a path segment, query value, or fragment, but it cannot supply the URL’s
scheme, host, or port (INLINE_LINK_DYNAMIC_AUTHORITY). Each value a token inserts is URL-encoded,
so it cannot add another path segment or parameter. Tokens in href follow the Action URL rules:
rhcResult tokens are not allowed, and an empty token without a fallback removes the link.
Protocol-relative URLs, credentials in the authority, ports other than 443, malformed percent
encoding, control characters, and non-HTTPS external schemes are rejected. If a destination is
unsafe or a required value is missing, the card keeps the readable label as plain text and omits the
link.
The href can also be a single token and nothing else, such as href="{!record.Website}". The
inserted value must then be a complete same-org path or https:// URL by itself; any other value,
such as www.example.com or an http:// address, leaves the label as plain text. A whole-URL token
cannot use format or fallback (INLINE_LINK_WHOLE_URL_TOKEN_ATTRIBUTES).
One field supports at most 100 inline links. A label and the completed URL may each contain at most 2,000 characters. The complete structured display is also subject to the 1,000-node, 20,000-visible- character and 64 KiB per Check field limits. Structured display and evidence also share a 256 KiB serialized JSON projection budget per response, including envelope overhead. Original plain-text fallbacks and machine evaluation facts remain available outside that optional-presentation budget. See response allocation and limits. Resolved record values remain text; Record Health Check never reparses them as new link markup.
Value sources and properties
Section titled “Value sources and properties”| First part | Value source | Allowed property after the period |
|---|---|---|
record | Current Salesforce record | Any readable field API path, such as Name, AnnualRevenue, or Owner. |
rhcCheck | Current Check metadata | developerName, masterLabel, checkTitle, checkDescription, category, evaluationType, failureSeverity, evaluationOrder |
rhcSet | Current Check Set metadata | developerName, masterLabel, cardTitle, cardSubtitle, objectApiName |
rhcResult | Completed Check result; available after the Evaluation Type finishes | status, foundValue, foundValuePluralSuffix, expectedValue, failedRecordCount, totalRecordCount, reasonCode |
rhcRun | Current run context | runId, source, startedAt, completedAt, durationMs |
rhcQuery | Rows this Check’s own queries returned; Query and Compare Two Queries Checks only | sourceRows[n]., comparisonRows[n]., sourceRowCount, comparisonRowCount |
A record path may cross at most five relationships, such as Account.Owner.Manager.Name.
A longer path is rejected as UNKNOWN_TOKEN_PROPERTY. A path that is shaped correctly but names a
field that does not exist, such as {!record.DoesNotExist__c}, is rejected when the Check’s fields
are planned.
What each property inserts
Section titled “What each property inserts”Check tokens (rhcCheck) read the Check that is running:
| Token | Inserts |
|---|---|
{!rhcCheck. | Record Health Check Name (Developer Name), without a namespace prefix |
{!rhcCheck. | Label |
{!rhcCheck. | Check Title, the title shown on the card |
{!rhcCheck. | Check Description |
{!rhcCheck. | The Category value in words, such as Relationship Coverage; blank when no Category is set |
{!rhcCheck. | Formula, Query, Compare Two Queries, or Apex. These are the stored values in words, not the Setup labels |
{!rhcCheck. | Critical, Warning, or Info |
{!rhcCheck. | The Evaluation Order number, such as 100 |
Check Set tokens (rhcSet) read the Check Set that owns the Check:
| Token | Inserts |
|---|---|
{!rhcSet. | Record Health Check Set Name (Developer Name), without a prefix |
{!rhcSet. | Label |
{!rhcSet. | Card Title |
{!rhcSet. | Card Subtitle |
{!rhcSet. | Object, such as Account |
Result tokens (rhcResult) read the finished result, so they are available only in display text,
after the Evaluation Type has run:
| Token | Inserts |
|---|---|
{!rhcResult. | The status API name: PASS, FAIL, SKIPPED, UNABLE_, or ERROR. It is not the card label, so Message When Failed always reads FAIL |
{!rhcResult. | The Found value the framework computed, written with the Check’s Display: Value Format. It ignores Display: Found Text |
{!rhcResult. | The Expected wording the framework computed. On a Query or Compare two queries Check it includes the comparison, such as to equal Manufacturing, at least 3, or to be blank. It ignores Display: Expected Text |
{!rhcResult. | s, or nothing when the count is exactly 1, so {!rhcResult. reads 1 Contact or 3 Contacts |
{!rhcResult. | The number of returned rows that failed. It has a value only in Display: Found Text and Display: Expected Text on a Query Check whose How To Read Query Results is Every record passes; elsewhere it is blank |
{!rhcResult. | The number of rows the query returned, with the same availability as failedRecordCount |
{!rhcResult. | The result’s Reason Code, or blank when there is none. It is read before access codes are made neutral, so when Salesforce access blocks a running Check it shows FIELD_ or RECORD_ rather than CANNOT_; keep it out of messages users see |
On a Verify with a formula Check that has no Display: Expected Formula,
{!rhcResult.expectedValue} is the text of the Pass Condition formula, such as
NOT(ISBLANK(BillingCity)). The card hides that formula from users without diagnostics access,
but a token in a message does not. Add a Display: Expected Formula before you use the token in a
Formula Check’s message.
Run tokens (rhcRun) read the current run:
| Token | Inserts |
|---|---|
{!rhcRun. | The run ID, the same value Platform Events carry in Run ID. Treat it as text; do not parse it |
{!rhcRun. | How the run started: USER_ (Run or Rerun on the card), RUN_ (the card’s automatic run), FLOW, APEX_ (Apex and Preview), QUEUEABLE, BATCH, SCHEDULED, or AGENT (Agentforce actions and the REST resource) |
{!rhcRun. | When this Check started, as UTC in ISO 8601 form, such as 2026-10-20T14:03:07.. Run tokens do not accept format |
{!rhcRun. | Accepted, but always blank in this release |
{!rhcRun. | Accepted, but always blank in this release |
Because completedAt and durationMs are always blank, an Action URL that uses either one without
a fallback never shows its link, and display text that uses either one shows nothing in its place.
Format a field value
Section titled “Format a field value”A token that names a Salesforce field, either a record field or an rhcQuery row field, can carry
format. format is accepted in display text, including Action Label. It is not accepted in an
Action URL or SOQL, which need the stored value, and it is not accepted on rhcCheck, rhcSet,
rhcResult, or rhcRun tokens, which have no field type to work from. Using it there returns
TOKEN_FORMAT_NOT_ALLOWED.
Without format, a field token in display text inserts the stored value with only light
conversion:
| Field type | Inserted without format |
|---|---|
| Date | The date in the running user’s locale, such as 7/4/2026 for English (United States) |
| Date/Time | UTC in ISO 8601 form, such as 2026-07-04T17:30:00. |
| Number, Currency, Percent | The stored number, with no grouping separators, currency symbol, or percent sign |
| Checkbox | true or false |
| Picklist and multi-select | The stored API value, such as Prospect or North;South, not the translated label |
| Text, Id, and other field types | The stored value |
Add format to write the value for a reader. The value is the official, case-sensitive API name:
CURRENCY is valid; currency and the Setup label Currency return UNKNOWN_TOKEN_FORMAT.
format value | Setup label in Display: Value Format | Writes the value as | Example |
|---|---|---|---|
AUTO | Automatic | Chosen from the field’s definition: a Currency field reads as money, a picklist as its label, a Date/Time in the user’s time zone | {!record. → $70,000. |
NUMBER | Number | Digits grouped for the running user’s locale | 2500 → 2,500 |
CURRENCY | Currency | Money, in the record’s currency when it has one, otherwise the user’s currency | 70000 → $70,000. |
PERCENT | Percent | The number followed by a percent sign; use it for a Percent field, which already stores 12. for 12.5% | 12. → 12. |
RATIO_ | Ratio as percent | The number multiplied by 100, followed by a percent sign | 0. → 75% |
BOOLEAN | Checkbox | Yes or No | true → Yes |
DATE | Date | The running user’s locale date | 2026-07-04 → 7/4/2026 |
DATETIME | Date/Time | The running user’s locale date and time, in the user’s time zone | 2026-07-04T17:30:00Z → 7/4/2026, 12:30 PM for an English (United States) user in Central Time |
TEXT | Text | The stored value unchanged | true → true |
RAW | Raw | The stored value unchanged | 0012345 → 0012345 |
A format that does not fit the value, such as CURRENCY on a text field, leaves the value unchanged
instead of failing the Check. Formatting changes only the inserted text, never a comparison. The
Found and Expected display reference describes
the same formats in detail, including multi-currency and locale rules.
Query row values
Section titled “Query row values”A Query or Compare Two Queries Check can read the rows its own query returned:
{!rhcQuery.sourceRows[0].Name}{!rhcQuery.sourceRows[1].Email}{!rhcQuery.sourceRows[0].Account.Name}{!rhcQuery.sourceRowCount}{!rhcQuery.comparisonRows[0].Id}{!rhcQuery.comparisonRowCount}Row indexes start at 0, matching Apex and JavaScript collections. Index 0 is the first returned
row, index 1 is the second, and so on.
Reaching a related record
Section titled “Reaching a related record”To show something about a related record, query that object, not its parent. sourceRows is
whatever the Check’s own query returned, so querying Contact makes the contacts the rows:
Source Query: SELECT Id, LastName, Email, Account.Name FROM Contact WHERE AccountId = {!record.Id} ORDER BY CreatedDate DESCMessage: Second contact is {!rhcQuery.sourceRows[1].Email fallback="not listed"}A child subquery is opaque to row tokens, but it does not hide scalar fields selected beside it.
For example, SELECT Id, Website, (SELECT Email FROM Contacts) FROM Account permits a token for
Website; it does not permit a token for the child Email values.
What a Check must satisfy
Section titled “What a Check must satisfy”Record Health Check reports each of these when the metadata validator audits the Check, and again
when the Check runs: an unmet requirement returns UNABLE_TO_EVALUATE naming the problem instead of
a blank value. Custom Metadata has no save-time hook, so saving a Check does not report them.
| Requirement | Why |
|---|---|
| The Check runs a query | Formula and Apex Checks have no rows |
The field is in the SELECT list | Selecting Id does not authorize Name, and selecting Owner. does not authorize Owner. |
A multi-row query has an explicit ORDER BY | The author chooses what “first” means, such as newest by CreatedDate DESC; tied rows follow Salesforce’s native tie behavior |
| The row index is within reach | It must be lower than the query’s own LIMIT, the Check’s Max Query Rows, or the single row a One Result Check returns |
A comparisonRows token has a Comparison Query | Otherwise the Check produces no comparison rows |
| A currency-formatted amount has its currency | In a multi-currency org, select CurrencyIsoCode beside the amount |
Three shapes need less. An ungrouped aggregate such as SELECT COUNT(Id) total FROM Contact
returns exactly one row, and WHERE Id = {!record.Id} can return at most one record, so index 0 is
addressable without ORDER BY. A row count reads no column and no order, so it needs neither.
SELECT COUNT() is the exception in the other direction: it returns one row holding the total, so
sourceRowCount there would always be 1. Use {!rhcResult.foundValue} for the number counted, or
alias the aggregate as SELECT COUNT(Id) total and read {!rhcQuery.sourceRows[0].total}.
Provide a fallback for an empty value
Section titled “Provide a fallback for an empty value”A row the query never returned, and a selected field that is null, are both empty and use the fallback. In an Action URL an empty value with no fallback removes the link rather than building a broken one. Values are always inserted as text: a row value cannot add a parameter or a path segment to a URL, and never becomes a link inside a message.
What it costs
Section titled “What it costs”Correlated queries with an explicit ORDER BY and numeric LIMIT keep their per-record meaning in
list views and batch runs. Record Health Check executes one scope query, preserves the authored
multi-key order, and keeps up to that many rows for each record. The existing scope row budget
still applies to the raw combined result.
The raw query rows and unused columns stay transient on the server and are never serialized on the result or published in an event. A field selected by a token is intentionally copied into the completed message, label, or URL, so that the completed text follows its normal destination: it can reach the browser or API caller and, when diagnostics are enabled, diagnostic logs. Treat every row field referenced by a token as user-visible and choose fields appropriate for everyone who can receive the result. No token causes an extra query.
Four names for Found, and which one you are reading
Section titled “Four names for Found, and which one you are reading”The same English idea appears under different names depending on where you read the result. They are not interchangeable, and the differences are the whole reason a Check can look right and report something else.
| Name | Where it appears | What it holds |
|---|---|---|
found / expected | The evaluation result a Flow, Apex, or REST caller receives | The value that was compared, with no comparison wording. Empty when the operator compares against nothing, such as Is Not Blank |
comparisonOperator | The same evaluation result | The operator, in its own field, so it is never mixed into the value |
{!rhcResult. / {!rhcResult. | Merge tokens in messages, labels, and display text | What the framework computed, written for a reader. Expected includes the comparison wording. Unaffected by Display: Found Text or Display: Expected Text |
foundDisplayValue / expectedDisplayValue | The display half of a result, and the card | Exactly what the card reads, including Display: Found Text, Display: Expected Text, and the comparison wording |
So for a Check comparing Industry to Manufacturing:
evaluation.found Technologyevaluation.expected Manufacturingevaluation.comparisonOperator EQUALS{!rhcResult.expectedValue} to equal Manufacturingcard / expectedDisplayValue to equal ManufacturingThe token and the card read the same here because the Check has no Display: Expected Text. With
Display: Expected Text set to a manufacturing account, the card reads a manufacturing account
while the token still reads to equal Manufacturing.
If you are building an automation, read found, expected, and comparisonOperator. If you are
writing a message, use the merge tokens, and write the sentence around them so the comparison wording
reads naturally: Found {!rhcResult.foundValue}; expected {!rhcResult.expectedValue}. becomes
Found Technology; expected to equal Manufacturing. The card’s wording is never the value.
Display: Found Text and Display: Expected Text
Section titled “Display: Found Text and Display: Expected Text”These two fields change what the card reads. They do not change what the Check found.
Check found: 003AB000001XyZaQAKDisplay: Found Text A primary Contact is assigned
Card shows: A primary Contact is assigned{!rhcResult.foundValue} 003AB000001XyZaQAKFlow, Apex, savedresults, events 003AB000001XyZaQAKSo a Check whose Found value is a record Id still reports that Id everywhere a value is asked for, while the card reads the sentence you wrote. Wording is presentation; it never becomes the answer the Check gives.
Inside the two templates, {!rhcResult.foundValue} and {!rhcResult.expectedValue} read the values
the framework computed. Each template can quote the original, and the Expected template never sees
the Found template’s replacement, so the two cannot chain into one another:
Framework computed: Found "3", Expected "to equal 0"Display: Found Text {!rhcResult.foundValue} contacts without emailDisplay: Expected Text none; Found was {!rhcResult.foundValue}
Card shows: Found "3 contacts without email" Expected "none; Found was 3"Setting Display: Expected Text also clears the framework’s own caption for that value, because the caption described the value that is no longer displayed.
Display: Found Text and Display: Expected Text are ignored on Apex Checks, which supply their own
values; configuration validation reports that as
APEX_DISPLAY_TEXT_IGNORED.
Fallbacks
Section titled “Fallbacks”What happens when a token’s Salesforce value is empty depends on where the token is used:
| Location | Empty token without a fallback | Empty token with a fallback |
|---|---|---|
| Display text | Inserts blank text | Inserts the fallback text |
| Action URL | Suppresses the link (MISSING_) | Uses the fallback text in the URL |
| SOQL | Uses an empty query value; a value that cannot be converted to the field’s data type can return MISSING_ | Converts the fallback to the field’s data type and uses it in the query |
Use a fallback when an empty value would produce unclear wording or an unsafe SOQL value. These fields are often blank, so a substitute helps:
{!record.Parent.Name fallback="Independent account"}{!record.Owner.Manager.Name fallback="No manager assigned"}In SOQL, use a fallback only when the record field can be empty and an empty query value would be
wrong. When a Check evaluates a record, {!record.Id} already has a value, so SOQL and Action URLs
use the bare token:
SELECT COUNT() FROM Contact WHERE AccountId = {!record.Id}/lightning/r/Account/{!record.Id}/viewAn optional parent lookup can be blank, so a fallback of the same data type keeps the query valid:
SELECT AnnualRevenue FROM Account WHERE Id = {!record.ParentId fallback="001000000000000AAA"}Fallback text is literal. It is not parsed as another merge token. A pipe inside the quoted
fallback is ordinary text. Invalid number, date, date/time, time, or Boolean
fallbacks in SOQL return MISSING_BIND_VALUE instead of running a misleading query.
Tokens in SOQL
Section titled “Tokens in SOQL”- Only
record.*tokens are valid in SOQL templates. - Strings are quoted and escaped automatically; numbers, dates, and Booleans are unquoted.
- A multi-select picklist token expands differently when quoted versus unquoted: quoted keeps
'A;B;C', unquoted expands to anINCLUDES (...)list. - The same field may appear both quoted and unquoted in one template; each form is substituted independently.
- Record Health Check evaluates up to 200 records with one query, so write each query with exactly
one unquoted record token that connects it to the record. A query with two or more unquoted
record tokens returns
UNSUPPORTED_BULK_QUERY_SHAPE; see Bulk query grammar. - The running user must be able to read every token field, or the Check returns
UNABLE_TO_EVALUATE.
Related Reason Codes
Section titled “Related Reason Codes”Configuration validation reports token and inline-link
problems before a Check runs. A Check that runs with a token problem returns UNABLE_TO_EVALUATE
with the code, except where the table says otherwise.
| Reason code | Typical cause |
|---|---|
TOKEN_ | Token such as {!Id} omits the required first part |
UNSUPPORTED_ | First part is not one of record, rhcCheck, rhcSet, rhcResult, rhcRun, or rhcQuery |
UNKNOWN_ | Property is not on the list for its value source, a path is not shaped like a field path, or a record path crosses more than five relationships |
MALFORMED_ | A brace outside a complete token, a pipe fallback, or a repeated, unknown, or unquoted format or fallback setting |
TOKEN_ | Value source not allowed in that field, such as rhcResult in an Action URL or rhcQuery in Message When Not Applicable |
TOKEN_ | format in an Action URL or SOQL, or on a token that does not name a field |
UNKNOWN_ | format value is not an uppercase API name from Format a field value |
TOKEN_ | Row index is not a whole number starting at 0, is above 1999, or is beyond what the query can return |
QUERY_ | A row token names a field the query’s SELECT list does not include |
QUERY_ | A row token reads a multi-row query that has no explicit ORDER BY |
QUERY_ | The token’s field cannot be proven from the query’s outer SELECT list, such as a field inside a child subquery |
QUERY_ | A comparisonRows token on a Check without a Comparison Query, or a row count on a SELECT COUNT() query |
TOKEN_ | A value source has no value at that point, such as rhcResult before the Check finishes or record when no record is loaded |
TOKEN_ | More than 100 tokens in one template |
RESOLVED_ | Completed text exceeded 20,000 characters |
MISSING_ | An Action URL token resolved blank with no fallback. The link is removed; the Check result is unchanged |
MISSING_ | A SOQL fallback could not be converted to the field’s data type, or a SOQL token’s field could not be read from the record |
INLINE_ | An inline link in Action Label, Action URL, or SOQL |
INLINE_ | The link has no label or no href |
INLINE_ | An attribute other than label or href |
INLINE_ | label or href appears twice |
INLINE_ | Missing closing quote or brace, or an attribute that is not lowercase name="value" |
INLINE_ | A backslash in an attribute that does not begin \" (a quote) or \\ (a backslash) |
INLINE_ | A link inside a link, or a brace in an attribute that is not part of one complete value token |
INLINE_ | More than 100 inline links in one field |
INLINE_ | A token placed where it would supply the scheme, host, user information, or port |
INLINE_ | The destination is not a same-org path beginning with / or an https:// URL, or it fails the URL safety rules |
INLINE_ | An href that is a single token also sets format or fallback |
When Action URL resolves to more than 2,000 characters, the link is suppressed and Fix Message can still render. URL scheme and path checks live in Configure action links.
Full outcome list lives in Reason Codes.