Conditions — Visual Conditions and Code Conditions
TL;DR
CONDITIONmust be something the builder's condition panel can draw: exactly ONE group inorExpressionGroups,operator"AND"or"OR", 1–20booleanExpressions. Each expression is ONE function from §2 (optionally insidenot(…)— only the negatable ones), with the field asvar()and a literal value.- The panel re-writes every expression the moment the user opens the step. A shape outside §2 is dropped, mis-read or silently changed — restructure (§4) or use
CODE_CONDITION(§5). - Entity fields hold ids:
stringContains(["<id>"];var("field")), never a display name. - String literals are URI-encoded (Automations Mapping Expressions §1); date literals may be encoded or not (§2).
truePostActionIds/falsePostActionIds: at most ONE id each; branch children have this condition as their only parent (Automations Graph and Data Model).
1. Shape
{
"id": "<uuid-1>",
"type": "CONDITION",
"namespace": "CONDITION-1",
"displayName": "VIP order?",
"conditionInfo": {
"orExpressionGroups": [
{
"operator": "AND",
"booleanExpressions": [
"{{stringEq(var(\"customer_tier\");\"premium\")}}",
"{{numberGt(var(\"order_count\");5)}}"
]
}
],
"truePostActionIds": ["<uuid-2>"],
"falsePostActionIds": []
}
}MUST:
- Exactly one entry in
orExpressionGroupswith an explicitoperator("AND"= all hold,"OR"= any). Several groups are flattened into one on first open and their logic is lost; a missingoperatoris saved asOR. - 1–20 expressions — an empty group makes the builder loader hang; the panel allows at most 20 (more than 20 → a code condition).
- One comparison per entry; never combine with
and(…)/or(…)inside an entry. - Every
var()path exists in THIS step's aggregated schema (trigger + ancestors; Automations Graph and Data Model §4). A path the panel can't find marks the step invalid and its canvas label stays empty. - No whitespace outside string literals (
{{ stringEq(…makes the function unreadable). - Only
conditionInfoon the step; both branch arrays present; never both empty (dead end). Set a shortdisplayName.
2. Operator table (the only shapes that round-trip)
The builder ships two panel layouts (a dropdown and a newer property picker) and users get either. Everything below survives both; when a user edits a condition, the property picker may rewrite arraySome/arrayEvery into arrayIncludes* forms — that is outside your control; never write arrayIncludes* yourself (see the list below).
Classify the field from its schema, in this order: format: "date" → date · format: "date-time" → date-time · type: "string" + format: "number" → number · has enum (or string/number oneOf of consts) → enum / number-enum · integer → number · string with itemsSelectionConfiguration (providerKey or tag) → item selection · otherwise its type.
| Field type | Operator (UI) | Expression (¬ = may wrap in not(…)) |
|---|---|---|
| string | is / is not ¬ | stringEq(var("f");"v") |
| contains / doesn't contain ¬ | stringHasSubString(var("f");"v") |
|
| number | equals / not equals ¬ | numberEq(var("f");5) |
| greater / less than | numberGt(var("f");5) · numberLt(var("f");5) |
|
| date | is / is not ¬ | dateEq(var("f");"2026-12-25") |
| before / after | dateBefore(…) · dateAfter(…) |
|
| date-time | is / is not ¬ | dateTimeEq(var("f");"2026-12-25T10:00:00Z") |
| before / after | dateTimeBefore(…) · dateTimeAfter(…) |
|
| boolean | is true / is false | boolEq(var("f");true) · boolEq(var("f");false) |
| enum (string) | is / is not ¬ | stringEq(var("f");"PAID") |
| is one of / is not one of ¬ | stringContains(["PAID","PENDING"];var("f")) — list FIRST |
|
| number enum | is ¬ / is one of ¬ | numberEq(var("f");2) · numberContains([1,2];var("f")) |
| item selection (id) | is one of / is not one of ¬ | stringContains(["<id-1>","<id-2>"];var("f")) |
| array of primitives | includes any of / doesn't ¬ | arraySome(var("f");contains(["a","b"];$_)) |
| includes only | arrayEvery(var("f");contains(["a","b"];$_)) |
|
| includes all of | one arraySome(var("f");contains(["a"];$_)) entry per value in an AND group (see below) |
|
| array of objects | same as array of primitives | var("f") → arrayMap(var("f");"<item.property>") — ONLY the property named by the array's defaultConditionedProperty |
| any type | is empty / is not empty ¬ | isEmpty(var("f")) |
NEVER:
not(…)around anything not marked ¬ (numberGt,numberLt,date*Before/After,boolEq,arrayEvery) — the panel loses the operator. NegatingboolEq(…;true)can useboolEq(…;false). NEVER negate a strict comparison by swappingGt/Ltor Before/After:not(x > N)meansx <= N, including equality. Preserve that boundary with comparison + equality in a singleORgroup when the full logic fits (§4), or use CODE_CONDITION. For example, "not more than 100" includes 100; "not before a date" includes that date. Do not invent an inclusive visual operator.arrayIncludesAnyOf/AllOf/Only(…)— the dropdown layout reads all three as "includes only" and re-saves them with that meaning.- The collection-first
arrayEvery(["a","b"];contains(var("f");$_))— the property-picker layout cannot read it. For "includes all of" use onearraySomeentry per value withoperator: "AND"; if the group must beOR, chain conditions (§4) or use code. arrayMapto any property other thandefaultConditionedProperty(or on an array without one) — the dropdown layout re-points it or fails to save. The path is relative to the item ("service.id") and must exist in the item schema; otherwise →CODE_CONDITION.- Anything around the field (
lower(var("f")),month(var("d"))),var()ornow()as the value, two fields compared,eq/gt/containsat top level,isEmptyString,startsWith,if,and/or. These are valid formulas but not drawable.
Literal rules (the value inputs reject or rewrite others):
| Value | Rule |
|---|---|
| string | ≤ 2500 chars; must not contain " or ' (the input flags it) — test a quote-free part with stringHasSubString, or use code |
| number | Unquoted; between −100000000 and 100000000; decimals such as 0.5 and -0.25 are supported; no omitted leading zero (.5), leading zeros (05) or exponents |
| boolean | true/false unquoted (a quoted "yes" is re-saved as a broken bare word) |
| enum | Exactly one of the schema's enum/const values, same case |
| date | "YYYY-MM-DD"; date-time: full ISO with zone ("2026-12-25T10:00:00Z"); never relative (now()) — relative windows → code or a set-variables boolean |
Date values and time zone: the panel writes a picked date/time as wall-clock time in the site
time zone with its offset (a date → that day's 00:00 site time), and URI-encodes it like every
literal ("2026-12-31T23%3A59%3A00%2B02%3A00"). Its reader decodes first, so an encoded and an
unencoded ISO literal load the same (a "YYYY-MM-DD" literal is unchanged by encoding). Treat a
calendar date the user names as a site-time-zone date: "valid until Dec 31" → compare with the end
of that day in the site's zone (Site Properties timeZone, Automations Schemas and Scheduling §4).
Semantics: stringEq/stringHasSubString/stringContains are case-insensitive. No ≥/≤: for integers numberGt(var("f");N-1); otherwise numberGt + numberEq in an OR group (only if the group may be OR) or code. $_ appears bare, only inside contains(…).
3. Entity-id fields
A field with itemsSelectionConfiguration (service, form, product, label, coupon, location, pipeline stage, …) carries an id or key. A display name passes validation and silently never matches. Get ids from the owning vertical’s documented public list, search or get endpoint for this entity type, or the user. Confirm a supplied id with a successful read of that entity. If the field’s selection configuration restricts eligible entities to a parent (such as a form) or fixed criteria, accept only ids that meet those restrictions. Never construct an entity-picker endpoint URL from the provider key or call the builder’s internal picker endpoint directly. Ids are whatever that API returns — label keys look like custom.vip-customers, not uuids.
- Scalar field
service_id:{{stringContains(["<service-id>"];var("service_id"))}} - Property in an array of objects
lineItems[].rootCatalogItemId:{{arraySome(arrayMap(var("lineItems");"rootCatalogItemId");contains(["<product-id>"];$_))}}— visual only when that property is thedefaultConditionedProperty; else code:(payload.lineItems || []).some(i => ids.includes(i.rootCatalogItemId)) - The field is an array of ids
labelKeys.items:{{arraySome(var("labelKeys.items");contains(["<label-key>"];$_))}}
Never synthesize [0], .0, firstItem or a dotted path through an array. "The order contains product X" is a whole-array test — keep it one. If the user needs one specific item, clarify. If you cannot obtain the ids, the entity set is unknown, not empty: tell the user and ask which entity to use.
4. When the logic doesn't fit one group
(A AND B) OR C/ mixed AND+OR / anything needing more than one group → oneCODE_CONDITION(§5) with exactly that logic — the default; it keeps a single true/false branch. Chaining two visual conditions (A AND B→ false: conditionC) is an alternative only when the true branch is one small step, since that step must then be duplicated (tree only — duplicate, never join; Automations Graph and Data Model). Never write severalorExpressionGroups.- Starts / ends with → No visual operator. Use an exact
CODE_CONDITION, or compute a boolean withstartsWith/endsWithin a preceding set-variables step and test it withboolEq. Never silently substitute a substring test; explain any proposed change in semantics and obtain the user's agreement before building it. - Two fields compared, computed values, relative dates, month/day of a date (birthdays), string length, any §2 NEVER →
CODE_CONDITION(§5), or compute a boolean with a set-variables step (Automations Delays Variables and Branches) and test it withboolEq(var("setVariable.<key>");true) - Optional field ("if phone is present it must contain 555") → Two chained conditions (
not(isEmpty(…)), then the test), or code
Prefer a visual CONDITION when it expresses the logic exactly — users can keep editing it. Don't force complex logic into it; if the user insists, explain what can't be drawn. Never say the logic is impossible when code can do it.
5. CODE_CONDITION
Before constructing a calendar condition: obtain the IANA time zone from current tool-returned site metadata for the exact target site, or read Site Properties (Automations Schemas and Scheduling §4) if that metadata is absent. A zone from another site, documentation, memory or an example is not evidence. Validate the returned zone and replace <SITE_TIME_ZONE> before saving; a confirmed literal is expected in saved code.
{
"id": "<uuid-3>",
"type": "CODE_CONDITION",
"namespace": "CONDITION-2",
"codeConditionInfo": {
"snippet": {
"language": "JAVASCRIPT",
"code": "/**\n * @param {Payload} payload - Automation payload with contact birthdate.\n * @returns {boolean} whether today is the contact's birthday at the site.\n */\nexport default function (payload) {\n const b = payload.contact?.birthdate;\n if (typeof b !== 'string' || !/^\\d{4}-\\d{2}-\\d{2}$/.test(b)) return false;\n const [y, m, d] = b.split('-').map(Number);\n const days = [31, y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];\n if (!y || !m || m > 12 || !d || d > days[m - 1]) return false;\n try {\n const parts = new Intl.DateTimeFormat('en-US', {\n timeZone: '<SITE_TIME_ZONE>',\n calendar: 'gregory',\n numberingSystem: 'latn',\n month: '2-digit',\n day: '2-digit',\n }).formatToParts(new Date());\n const get = type => parts.find(part => part.type === type)?.value;\n return b.slice(5, 7) === get('month') && b.slice(8, 10) === get('day');\n } catch (e) {\n return false;\n }\n}"
},
"dynamicVariableExpressions": ["{{var(\"contact.birthdate\")}}"],
"truePostActionIds": ["<uuid-4>"],
"falsePostActionIds": []
}
}The birthday example requires a confirmed IANA site time zone (Automations Schemas and Scheduling §4).
A birthdate is a date-only YYYY-MM-DD: reject impossible Gregorian dates (including
February 29 in a non-leap birth year and year 0000), then compare its literal month/day
with today's calendar parts in that zone. Do not parse the birthdate as a UTC instant or use the runtime's local
getMonth() / getDate(). An unresolved or invalid zone blocks saving; the runtime guard is
only a fallback. A February 29 birthday matches February 29, not an invented non-leap-year date.
Minimal array check (the code reads only the declared array):
"displayName": "Check if order has 3+ items",
"codeConditionInfo": {
"snippet": { "language": "JAVASCRIPT",
"code": "/**\n * @param {Payload} payload\n * @returns {boolean}\n */\nexport default function (payload) {\n return (payload.lineItems || []).length >= 3;\n}\n" },
"dynamicVariableExpressions": ["{{var(\"lineItems\")}}"],
"truePostActionIds": ["<uuid-2>"], "falsePostActionIds": [] }Numeric values in code. Payload numbers can arrive as strings, including fields with
format: number. A bare typeof value === 'number' rejects those valid values. Convert only
numbers or nonblank strings, then require Number.isFinite before arithmetic or comparison.
Do not turn missing, null or blank values into zero unless the user's rule explicitly requires it.
For a same-line quantity/price check, use the actual schema paths in place of these example names
and declare the entire lineItems array in dynamicVariableExpressions:
{
"id": "<uuid-5>",
"type": "CODE_CONDITION",
"namespace": "CONDITION-3",
"displayName": "Same item has quantity 3+ and price over 50",
"codeConditionInfo": {
"snippet": {
"language": "JAVASCRIPT",
"code": "/**\n * @param {Payload} payload\n * @returns {boolean}\n */\nexport default function (payload) {\n const number = value =>\n typeof value === 'number'\n ? value\n : typeof value === 'string' && value.trim() !== ''\n ? Number(value)\n : NaN;\n return (\n Array.isArray(payload.lineItems) &&\n payload.lineItems.some(item => {\n const quantity = number(item?.quantity),\n price = number(item?.unitPrice);\n return (\n Number.isFinite(quantity) &&\n Number.isFinite(price) &&\n quantity >= 3 &&\n price > 50\n );\n })\n );\n}\n"
},
"dynamicVariableExpressions": ["{{var(\"lineItems\")}}"],
"truePostActionIds": ["<uuid-6>"],
"falsePostActionIds": []
}
}MUST:
type: "CODE_CONDITION"with onlycodeConditionInfo;namespacefollows the condition pattern (CONDITION-N, unique).languageis alwaysJAVASCRIPT. The code default-exports a synchronousfunction (payload)with exactly one parameter, starts with the JSDoc block the builder's template has (/** @param {Payload} payload … @returns {boolean} … */— required), and returns an explicit boolean. No imports, no network calls. Whole code ≤ 1000 characters; newlines escaped in JSON.- Guard every access (
?.,Array.isArray,|| [],typeof,try/catchfor deep paths); a missing field must not throw. Numeric conversion follows the rule above, not an unconditional|| 0default. - Access — the same paths as the aggregated schema (Automations Graph and Data Model §4):
payload.field,payload['field-with-hyphens'], action outputspayload['<namespace>'].field,payload.contact.email,payload.setVariable['<key>']. JS may index arrays and use.some/.every/.filterandDatemath;new Date()gives the current time for calendar checks. dynamicVariableExpressions: one{{var("<path>")}}for EVERY field the code reads — the runtime hydrates ONLY these, so an undeclared field isundefined. Arrays: declare the array itself (payload.lineItems.some(…)→{{var("lineItems")}}), never items or indexes; reading an object whole needs the object declared; if a path has no validvar(), declare its closest valid parent. Neverpayload[computedKey]or the wholepayload.[]only when the code reads no field. Every path must exist in this node's aggregated schema.- Use it only when the visual panel can't express the logic (array indexing, per-element math, string splitting, date parts, regex — §4).
- Test mentally against a true case, a false case and a payload with the fields missing.
Other special steps (delay, rate limit, set variables, split): Automations Delays Variables and Branches.
6. Pre-save checklist
- One group; explicit
AND/OR; 1–20 expressions; no nestedand/or; no stray whitespace. - Each expression is a §2 row for the field's classified type;
not()only on ¬ rows; noarrayIncludes*, no collection-firstarrayEvery. - Value literal obeys §2 (no quotes in strings; no
.5,05or exponent numbers —0.5and-0.25are valid; exact enum values; unquoted booleans). - Every
var()path exists in this step's aggregated schema;arrayMaponly ontodefaultConditionedProperty. - Entity fields compared to ids (§3); no synthetic array paths.
- String literals URI-encoded; JSON quotes escaped.
- Branch arrays ≤1 id each, children single-parent, not both empty;
namespaceunique. - Anything else → restructured (§4) or a
CODE_CONDITIONmeeting §5. - Validate Automation returns no errors for this step.