Skip to content

Merge syntax

Reference21 min read

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}
PartMeaning
NamespaceThe first part, which says where the value comes from: record, rhcCheck, rhcSet, rhcResult, rhcRun, or rhcQuery
PropertyWhich 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 NameCompleted text
AcmeReview Acme before approval.
blankReview 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.

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.”

LocationWhere it appearsAllowed value sources
Display textMessage 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 Textrecord, 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 URLAction URL on a Checkrecord, rhcCheck, rhcSet, rhcRun, rhcQuery (result tokens are not allowed); each inserted value is URL-encoded before the URL safety check
SOQLSource Query, Comparison Query, and applicability count queriesrecord only

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.

First partValue sourceAllowed property after the period
recordCurrent Salesforce recordAny readable field API path, such as Name, AnnualRevenue, or Owner.Name
rhcCheckCurrent Check metadatadeveloperName, masterLabel, checkTitle, checkDescription, category, evaluationType, failureSeverity, evaluationOrder
rhcSetCurrent Check Set metadatadeveloperName, masterLabel, cardTitle, cardSubtitle, objectApiName
rhcResultCompleted Check result; available after the Evaluation Type finishesstatus, foundValue, foundValuePluralSuffix, expectedValue, failedRecordCount, totalRecordCount, reasonCode
rhcRunCurrent run contextrunId, source, startedAt, completedAt, durationMs
rhcQueryRows this Check’s own queries returned; Query and Compare Two Queries Checks onlysourceRows[n].Field, comparisonRows[n].Field, 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.

Check tokens (rhcCheck) read the Check that is running:

TokenInserts
{!rhcCheck.developerName}Record Health Check Name (Developer Name), without a namespace prefix
{!rhcCheck.masterLabel}Label
{!rhcCheck.checkTitle}Check Title, the title shown on the card
{!rhcCheck.checkDescription}Check Description
{!rhcCheck.category}The Category value in words, such as Relationship Coverage; blank when no Category is set
{!rhcCheck.evaluationType}Formula, Query, Compare Two Queries, or Apex. These are the stored values in words, not the Setup labels
{!rhcCheck.failureSeverity}Critical, Warning, or Info
{!rhcCheck.evaluationOrder}The Evaluation Order number, such as 100

Check Set tokens (rhcSet) read the Check Set that owns the Check:

TokenInserts
{!rhcSet.developerName}Record Health Check Set Name (Developer Name), without a prefix
{!rhcSet.masterLabel}Label
{!rhcSet.cardTitle}Card Title
{!rhcSet.cardSubtitle}Card Subtitle
{!rhcSet.objectApiName}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:

TokenInserts
{!rhcResult.status}The status API name: PASS, FAIL, SKIPPED, UNABLE_TO_EVALUATE, or ERROR. It is not the card label, so Message When Failed always reads FAIL
{!rhcResult.foundValue}The Found value the framework computed, written with the Check’s Display: Value Format. It ignores Display: Found Text
{!rhcResult.expectedValue}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.foundValuePluralSuffix}s, or nothing when the count is exactly 1, so {!rhcResult.foundValue} Contact{!rhcResult.foundValuePluralSuffix} reads 1 Contact or 3 Contacts
{!rhcResult.failedRecordCount}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.totalRecordCount}The number of rows the query returned, with the same availability as failedRecordCount
{!rhcResult.reasonCode}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_NOT_ACCESSIBLE or RECORD_NOT_ACCESSIBLE rather than CANNOT_EVALUATE; 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:

TokenInserts
{!rhcRun.runId}The run ID, the same value Platform Events carry in Run ID. Treat it as text; do not parse it
{!rhcRun.source}How the run started: USER_INITIATED (Run or Rerun on the card), RUN_ON_LOAD (the card’s automatic run), FLOW, APEX_API (Apex and Preview), QUEUEABLE, BATCH, SCHEDULED, or AGENT (Agentforce actions and the REST resource)
{!rhcRun.startedAt}When this Check started, as UTC in ISO 8601 form, such as 2026-10-20T14:03:07.412Z. Run tokens do not accept format
{!rhcRun.completedAt}Accepted, but always blank in this release
{!rhcRun.durationMs}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.

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 typeInserted without format
DateThe date in the running user’s locale, such as 7/4/2026 for English (United States)
Date/TimeUTC in ISO 8601 form, such as 2026-07-04T17:30:00.000Z
Number, Currency, PercentThe stored number, with no grouping separators, currency symbol, or percent sign
Checkboxtrue or false
Picklist and multi-selectThe stored API value, such as Prospect or North;South, not the translated label
Text, Id, and other field typesThe 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 valueSetup label in Display: Value FormatWrites the value asExample
AUTOAutomaticChosen 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.Amount format="AUTO"} → $70,000.00
NUMBERNumberDigits grouped for the running user’s locale2500 → 2,500
CURRENCYCurrencyMoney, in the record’s currency when it has one, otherwise the user’s currency70000 → $70,000.00
PERCENTPercentThe number followed by a percent sign; use it for a Percent field, which already stores 12.5 for 12.5%12.5 → 12.5%
RATIO_PERCENTRatio as percentThe number multiplied by 100, followed by a percent sign0.75 → 75%
BOOLEANCheckboxYes or Notrue → Yes
DATEDateThe running user’s locale date2026-07-04 → 7/4/2026
DATETIMEDate/TimeThe running user’s locale date and time, in the user’s time zone2026-07-04T17:30:00Z → 7/4/2026, 12:30 PM for an English (United States) user in Central Time
TEXTTextThe stored value unchangedtrue → true
RAWRawThe stored value unchanged0012345 → 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.

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.

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 DESC
Message: 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.

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.

RequirementWhy
The Check runs a queryFormula and Apex Checks have no rows
The field is in the SELECT listSelecting Id does not authorize Name, and selecting Owner.Name does not authorize Owner.Email
A multi-row query has an explicit ORDER BYThe author chooses what “first” means, such as newest by CreatedDate DESC; tied rows follow Salesforce’s native tie behavior
The row index is within reachIt 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 QueryOtherwise the Check produces no comparison rows
A currency-formatted amount has its currencyIn 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}.

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.

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.

NameWhere it appearsWhat it holds
found / expectedThe evaluation result a Flow, Apex, or REST caller receivesThe value that was compared, with no comparison wording. Empty when the operator compares against nothing, such as Is Not Blank
comparisonOperatorThe same evaluation resultThe operator, in its own field, so it is never mixed into the value
{!rhcResult.foundValue} / {!rhcResult.expectedValue}Merge tokens in messages, labels, and display textWhat the framework computed, written for a reader. Expected includes the comparison wording. Unaffected by Display: Found Text or Display: Expected Text
foundDisplayValue / expectedDisplayValueThe display half of a result, and the cardExactly 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 Technology
evaluation.expected Manufacturing
evaluation.comparisonOperator EQUALS
{!rhcResult.expectedValue} to equal Manufacturing
card / expectedDisplayValue to equal Manufacturing

The 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: 003AB000001XyZaQAK
Display: Found Text A primary Contact is assigned
Card shows: A primary Contact is assigned
{!rhcResult.foundValue} 003AB000001XyZaQAK
Flow, Apex, saved
results, events 003AB000001XyZaQAK

So 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 email
Display: 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.

What happens when a token’s Salesforce value is empty depends on where the token is used:

LocationEmpty token without a fallbackEmpty token with a fallback
Display textInserts blank textInserts the fallback text
Action URLSuppresses the link (MISSING_TOKEN_VALUE)Uses the fallback text in the URL
SOQLUses an empty query value; a value that cannot be converted to the field’s data type can return MISSING_BIND_VALUEConverts 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}/view

An 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.

  • 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 an INCLUDES (...) 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.

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 codeTypical cause
TOKEN_NAMESPACE_REQUIREDToken such as {!Id} omits the required first part
UNSUPPORTED_TOKEN_NAMESPACEFirst part is not one of record, rhcCheck, rhcSet, rhcResult, rhcRun, or rhcQuery
UNKNOWN_TOKEN_PROPERTYProperty 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_TOKENA brace outside a complete token, a pipe fallback, or a repeated, unknown, or unquoted format or fallback setting
TOKEN_NOT_ALLOWED_ON_SURFACEValue source not allowed in that field, such as rhcResult in an Action URL or rhcQuery in Message When Not Applicable
TOKEN_FORMAT_NOT_ALLOWEDformat in an Action URL or SOQL, or on a token that does not name a field
UNKNOWN_TOKEN_FORMATformat value is not an uppercase API name from Format a field value
TOKEN_ROW_INDEX_INVALIDRow index is not a whole number starting at 0, is above 1999, or is beyond what the query can return
QUERY_FIELD_NOT_SELECTEDA row token names a field the query’s SELECT list does not include
QUERY_ORDER_NOT_DETERMINISTICA row token reads a multi-row query that has no explicit ORDER BY
QUERY_PROJECTION_NOT_ANALYZABLEThe token’s field cannot be proven from the query’s outer SELECT list, such as a field inside a child subquery
QUERY_ROLE_NOT_AVAILABLEA comparisonRows token on a Check without a Comparison Query, or a row count on a SELECT COUNT() query
TOKEN_NOT_AVAILABLE_IN_PHASEA value source has no value at that point, such as rhcResult before the Check finishes or record when no record is loaded
TOKEN_LIMIT_EXCEEDEDMore than 100 tokens in one template
RESOLVED_TEMPLATE_TOO_LONGCompleted text exceeded 20,000 characters
MISSING_TOKEN_VALUEAn Action URL token resolved blank with no fallback. The link is removed; the Check result is unchanged
MISSING_BIND_VALUEA 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_LINK_NOT_ALLOWED_ON_SURFACEAn inline link in Action Label, Action URL, or SOQL
INLINE_LINK_REQUIRED_ATTRIBUTE_MISSINGThe link has no label or no href
INLINE_LINK_UNKNOWN_ATTRIBUTEAn attribute other than label or href
INLINE_LINK_DUPLICATE_ATTRIBUTElabel or href appears twice
INLINE_LINK_MALFORMEDMissing closing quote or brace, or an attribute that is not lowercase name="value"
INLINE_LINK_MALFORMED_ESCAPEA backslash in an attribute that does not begin \" (a quote) or \\ (a backslash)
INLINE_LINK_NESTING_INVALIDA link inside a link, or a brace in an attribute that is not part of one complete value token
INLINE_LINK_LIMIT_EXCEEDEDMore than 100 inline links in one field
INLINE_LINK_DYNAMIC_AUTHORITYA token placed where it would supply the scheme, host, user information, or port
INLINE_LINK_UNSAFE_URLThe destination is not a same-org path beginning with / or an https:// URL, or it fails the URL safety rules
INLINE_LINK_WHOLE_URL_TOKEN_ATTRIBUTESAn 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.