Docs Designing the system 17
Expressions: conditions and values
On this page
An expression is how a design says when something holds, or what a value is, without writing code: a policy's condition, a field shown only when another has a value, a transaction's checks and what its steps set, a screen's filter, a pop-up's trigger, a flow's branch. It is written as JSON, and the designer checks it as you type (a box that does not read right turns red, and the problem says what it read that it may not). It never runs code: the platform walks it.


You rarely type one. Wherever a design takes a condition, the designer shows it in words and builds it for you: Add a condition (or Edit) opens rows of a field, an operator, a value, picked from what that place can read, with the field's own choices, numbers or dates; + condition adds another (all of them must hold; switch the group to any of these or none of these), + group nests one, and + from a pattern… starts from a common one (is in state…, is one of…, is empty, is between…, the person has the role…). A problem is named as you build (a field that place cannot read). Try checks it on values you type and says whether it holds, and why. JSON shows the same condition as text, for the rare one the rows do not draw (a count's conditions, every row of a table): it is the language below.


{"in": [{"lookup": "carrier.kind"}, ["magazine", "carrier"]]}
reads: the kind of the carrier entered is magazine or carrier. in is the operator; {"lookup":
"carrier.kind"} reads a value; ["magazine", "carrier"] is a list of values. Every expression is
built from those three things.
Values you write
| Format | Write it as | Notes |
|---|---|---|
| Text | "released" | In double quotes. A choice field's value is its stored name ("on_hold", not "On hold"). Case matters. |
| Number | 25, 2.5, -3 | No quotes: "5" is text and is not equal to 5. |
| Yes / no | true, false | No quotes. |
| Empty | null | A field with no value. Test it with is_null. |
| List | ["magazine", "carrier"] | For in, and what contains looks in. |
| Date | "2026-10-03" | A date field holds its day as text, year first, so lt, gt compare dates correctly. |
| Moment | "2026-10-03T06:30:00Z" | No field or input type holds a date and time (a date field holds its day); a record's own archived_at is one, in UTC. |
| A record | its id | A reference field (or input) holds the id of the record it names: compare it with another reference, or read the record's fields with lookup. |
| Several choices | a list | A field taking several choices holds a list: ask with contains. |
There is no "now" or "today" in an expression: a condition gives the same answer whenever it is checked. Time belongs in schedules, waits and analytics.
Values you read
A reference is { "<where from>": "<what>" }. What it can read depends on where the expression
is written; the designer says so if you read from somewhere it cannot.
| Reference | Reads | Example |
|---|---|---|
record | The record as it is saved: a field, or state, type, id | {"record": "state"} |
data | The form as it is being filled in, before it is saved | {"data": "disposition"} |
user | The person: id; in a policy, also roles, departments, groups (every group they belong to, their departments too) and certifications; in a transaction, also name, departments, groups and certifications (held today); in a screen block's Shown when or Enabled when, also name, departments and groups | {"user": "id"} |
person | A field of the built-in Person record of who runs it (a badge, certifications) | {"person": "semi_certified_for"} |
event | In a rule's entry: kind, action, changed (the fields being changed) | {"event": "kind"} |
input | What was entered in a transaction or an input flow; a reference input is its record's id | {"input": "good_qty"} |
lookup | A field (or state) of the record an input names, one level: <input>.<field> | {"lookup": "machine.capacity"} |
row | Inside some / every, or a step run once per row: a field of one row of a table input | {"row": "value"} |
param | What a screen was opened with (its machine) | {"param": "machine"} |
node | A setting of the route step a transaction runs at (a sequence's settings), or its name or label | {"node": "lsl"} |
flow | A value of the route run a transaction's traveler is in: the template's values, what a segment was passed, what a script set; inside a segment, the route's it runs inside too. Empty off a route | {"flow": "layer"} |
now | The moment (iso, a date and time) or today in the plant (date), in a transaction's or a flow's condition: a date field against today | {"now": "date"} |
context | A flow's run: its records' fields (lot.state) and its values | {"context": "lot.scrap_qty"} |
found | In a transaction step after one that finds records: how many it found, or a field of the first, by its name (<as>.count, <as>.first.<field>) | {"found": "holds.first.reason"} |
A path may go one step into a record (lookup: "lot.product" gives the product's id), not through it
to the product's own fields: to read those, add an input filled in from it (from: "lot.product").
A count ({"count": {"object": "reading", "where": {"product": {"context": "lot.product"}}}}) is of
the records in use whose fields equal the values given (a list: any of them); where may also name a
moment of the record's own with a window of minutes ("created_at": {"within": 240}, updated_at too):
the readings made in the last four hours. A transaction's checks and a flow's decisions count the same way.
Where you write it, and what it reads:
| Where | Reads |
|---|---|
| A policy's condition (Roles & policies) | record, user |
| A field's Shown when, Enabled when, Required when (Layout) | data, record, user |
| A transaction's Appears on … only when | record, user (its id) |
| A rule's entry, run only when (Rules) | event, data, record, user |
| A transaction's checks, a step's values and its only when; an input's required when | input, lookup, row, node, user, person, and count; a step after one that finds records, found; required when reads data |
| A screen's blocks (which records, which record, what a form is filled with) | param, user |
| A screen block's Shown when, Enabled when | param, lookup (a field of the screen's record), user, and count |
| A certification a role needs, only when (Roles & policies) | record |
| A query's parameters where a form, a transaction, a screen or a flow fills them | as that place reads: data, record, user on a form; input, lookup, user, node in a transaction; param, user on a screen; context, user in a flow |
| A pop-up's while and with | input, lookup, param, user, and count |
| A route's or a plan's conditions (start, wires, ends early) | context |
| An input flow's wires and fills | input, lookup, param, user |
Operators
| Operator | Means | Example |
|---|---|---|
eq, ne | equal, not equal | {"eq": [{"record": "state"}, "on_hold"]} |
lt, le, gt, ge | less than, at most, more than, at least (numbers; texts and dates in order) | {"gt": [{"input": "scrap_qty"}, 0]} |
in | the value is one of a list | {"in": [{"lookup": "carrier.kind"}, ["magazine", "carrier"]]} |
contains | a list holds the value (the other way round from in) | {"contains": [{"person": "semi_certified_for"}, {"lookup": "equipment.process"}]} |
is_null | the value is empty | {"is_null": {"input": "reason"}} |
all | every part holds (and) | {"all": [{"eq": [{"record": "state"}, "on_hold"]}, {"ne": [{"data": "disposition"}, null]}]} |
any | at least one part holds (or) | {"any": [{"eq": [{"record": "type"}, "wip"]}, {"eq": [{"record": "type"}, "finished"]}]} |
not | the part does not hold | {"not": {"in": [{"record": "state"}, ["shipped", "scrapped"]]}} |
add, sub | sum, difference; an empty value counts as 0 | {"add": [{"input": "good_qty"}, {"input": "reject_qty"}]} |
mul, div | product, quotient; an empty value, or a division by 0, gives no value | {"div": [{"input": "good_qty"}, {"lookup": "lot.qty"}]} |
some, every | some, or every, row of a table input holds the condition, read with row | {"every": [{"input": "readings"}, {"le": [{"row": "value"}, 36]}]} |
sum | the value read for each row of a table input, added up (an empty value counts as 0) | {"eq": [{"sum": [{"input": "lines"}, {"row": "debit"}]}, {"sum": [{"input": "lines"}, {"row": "credit"}]}]} |
count | how many records in use match: their fields equal the values given (a list: any of them) | {"count": {"object": "lot", "where": {"machine": {"input": "machine"}, "state": ["at_machine", "processing"]}}} |
eq, ne, lt, le, gt, ge take two parts, in and contains two (the value and the list,
the list and the value), some and every two (the table input and the condition), sum two (the table input and the value), all, any, add, sub, mul and div a
list of parts, not and is_null one. Parts may be
values, references or other operators, nested as deep as needed.
How it is read
- Exactly equal.
eqcompares as written:"5"and5are not equal;"On hold"and"on_hold"are not either. - **A condition holds only when it is
true**;notof anything that is nottrueis true. - Empty values. A field with no value is empty: it is not
eqto any value, but inlt,le,gt,gean empty number may count as 0. Where a field may be empty, ask first:{"all": [{"not": {"is_null": {"input": "temp"}}}, {"lt": [{"input": "temp"}, 80]}]}.is_nullis true for no value; an empty text ("") is a value: to take both,{"any": [{"is_null": {"data": "note"}}, {"eq": [{"data": "note"}, ""]}]}. - Sums.
addandsubcount an empty value as 0 (a reject quantity left empty);mulanddivgive no value then, anddivby 0 gives no value rather than an error (a yield on nothing is not 0 %). Results are rounded to 9 decimals. - A count counts in the database the object's records in use (not archived) whose fields equal the values given (a list: any of them).
- Why? On a record, Why? shows each condition that decided, the values it read, and which part did not hold.
Patterns
| What you want | Expression |
|---|---|
| A field only on hold | {"eq": [{"record": "state"}, "on_hold"]} |
| A reason only when rejecting | {"eq": [{"data": "disposition"}, "reject"]} |
| The machine is not full | {"lt": [{"count": {"object": "lot", "where": {"machine": {"input": "machine"}, "state": ["at_machine", "processing"]}}}, {"lookup": "machine.capacity"}]} |
| Good and rejected add up to the lot | {"eq": [{"add": [{"input": "good_qty"}, {"input": "reject_qty"}]}, {"lookup": "lot.qty"}]} |
| Every reading within limits | {"every": [{"input": "readings"}, {"all": [{"ge": [{"row": "value"}, {"node": "lsl"}]}, {"le": [{"row": "value"}, {"node": "usl"}]}]}]} |
| The operator is certified for this machine's process | {"contains": [{"person": "semi_certified_for"}, {"lookup": "equipment.process"}]} |
| The scanned lot is on hold (an input flow's wire) | {"eq": [{"lookup": "lot.state"}, "on_hold"]} |
With the copilot. Ask it in words ("only when the lot is on hold and the disposition is reject"): it writes the expression into the draft, and the designer checks it like any other. The AI API's contract describes them too, each where it may be written (a transaction's, a flow's).