Expressions
The expression language used in eligibility rules, score formulas, signal transforms, cohort filters, data-contract rules and webhook success conditions.
An expression is a short formula that Optima evaluates for one profile, one value or one response. It returns true or false, a number, or a piece of text. The same language is used in several places in the console; what differs is the data the expression can read and what the result must be.
Most screens offer a point-and-click builder for the common cases. Use an expression when the builder cannot say what you need. Expressions are compiled when you save, so a mistake in the syntax is rejected on the spot with a message that points at the position.
Where expressions are used
| Where in the console | Label | Reads | Must return | If it fails |
|---|---|---|---|---|
| Offers | Eligibility expression (under Advanced: expression) | attributes.*, signals.*, context.*, profile_id | true or false | The offer is excluded for that profile (reason Eligibility expression error). |
| Offers and offer catalogues | Score formula / Scoring formula | attributes.*, signals.*, context.* | A number | The offer scores 0. A scoring error never excludes the offer; running over the time limit does. |
| Signals | Transform expression | value, the signal's raw result | A value of the signal's type | The raw value is stored unchanged. |
| Cohorts | Filter expression | The signal values of the entity, by signal name | true or false | A signal name that does not exist matches nobody. |
| Data contracts | Validation expression | value, attrs | true | The value is rejected. |
| Data contracts | Transform expression | value | The replacement value | The value is kept unchanged. |
| Journey Webhook node | Success when | status, body and the keys you mapped from the response | true or false | Decides the success or error branch. |
| Journey Condition and goal (older ones) | Legacy expression | attributes.*, signals.* | true or false | Still evaluates. New conditions use a segment and the condition builder. |
Details of each:
- Eligibility and score.
attributes.*are the profile's attributes,signals.*its signals, andcontext.*the situational values supplied with the request, such aschannelorpage. A name that does not exist is not a save-time error: it evaluates to nothing (nil). Using nothing in a comparison or in arithmetic is a run-time error for that profile, so write expressions that cope with sparse profiles (see??below). Example eligibility:signals.churn_risk > 0.7 && attributes.country == "SK". Example score:signals.engagement * 10 + (attributes.tier == "gold" ? 5 : 0). - Signal transform. Runs once per profile on every recompute.
valueis a number for numeric signals and text for text signals, and the expression is checked against that type when you save: arithmetic on a text signal, orupper()on a numeric one, is refused. The result is converted to the signal's type afterwards; an integer signal drops the decimals (0.42 becomes 0), so scale before you round. Examples:min(value, 1000),round(value * 100) / 100,upper(value). A transform applies on the next recompute and is not retroactive. - Cohort filter. Reads only the signals of that entity; profile attributes are not in scope. Example:
churn_risk_score > 0.7 && rfm_score >= 4. - Data contracts.
valueis the incoming value of the attribute and, for validation only,attrsholds every attribute in the payload. Validation must returntrue; anything else rejects the value. Example:len(value) > 3 and attrs.country == "SK". Transform example:phone_e164(trim(value)). Four extra helpers exist only here, listed below. - Webhook success.
"2xx"(the default) and"any"are shorthand; anything else is an expression such asstatus == 200 && outcome == "accepted".
Writing expressions
Values
| Kind | Examples |
|---|---|
| Numbers | 42, 0.7 |
| Text | "gold" or 'gold' |
| True and false | true, false |
| Nothing | nil |
| Lists | ["a", "b"] |
| Number ranges | 1..5 (a list of 1 to 5) |
Read a value by name. Reach inside with a dot or brackets: attributes.country, attributes["country"], attrs.tags[0]. Put ?. before a name to read it safely when something earlier may be missing: attributes?.address?.city.
Operators
| Operators | Meaning |
|---|---|
== != < <= > >= | Compare |
+ - * / % ** | Arithmetic. ** (also written ^) is the power. + also joins text. |
and or not | Combine conditions |
in, not in | Membership: value in ["a", "b"] |
contains, startsWith, endsWith | Text tests: value contains "@" |
matches | Regular-expression test: value matches "^SK-[0-9]+$" |
a ? b : c | Choose: attributes.age >= 18 ? "adult" : "minor" |
a ?? b | A fallback for a missing value: attributes.nick ?? "friend" |
&&, || and ! are accepted as other spellings of and, or and not.
+ adds numbers or joins two pieces of text. Mixing them ("x" + 1) is refused when you save with invalid operation: string + int; convert first, for example "x" + string(1).
Functions
| Group | Functions |
|---|---|
| Text | len, upper, lower, trim, trimPrefix, trimSuffix, split, replace, indexOf, hasPrefix, hasSuffix, join |
| Numbers | abs, ceil, floor, round, min, max, sum, mean, median |
| Conversion | int, float, string, toJSON, fromJSON |
| Lists | len, first, last, take, reverse, sort, uniq, concat, flatten, keys, values |
| Lists with a condition | all, any, none, one, filter, map, count, find, findIndex, sortBy, groupBy, reduce |
| Time | now(), date("2026-01-02"), duration("2h") |
The condition in a list function refers to the current entry as #:
all(attrs.tags, # != "blocked")
filter(attrs.tags, # startsWith "vip")
map(attrs.tags, upper(#))
count(attrs.tags, # contains "a")Examples of results, for value = " SK-123 ":
| Expression | Result |
|---|---|
trim(value) | "SK-123" |
upper(trim(value)) | "SK-123" |
replace(trim(value), "-", "") | "SK123" |
trim(value) matches "^SK-[0-9]+$" | true |
len(split("a,b,c", ",")) | 3 |
round(3.14159 * 100) / 100 | 3.14 |
Helpers for data contracts
These four exist only in data-contract validation and transform expressions.
| Helper | What it does | Example |
|---|---|---|
trim_lower(text) | Trims spaces and lowercases. | trim_lower(" SK-123 ") is "sk-123" |
phone_e164(text) | Keeps the digits and a leading +, and adds a + if there is none. It does not know country codes, so supply the full international number. | phone_e164("(421) 905 123 456") is "+421905123456" |
parse_iso_date(text) | Reads an ISO 8601 date (2026-10-15, 2026-10-15T09:30:00, or with a zone) and returns it as UTC in RFC 3339 form. Anything it cannot read comes back unchanged. | parse_iso_date("2026-10-15") is "2026-10-15T00:00:00Z" |
truncate(text, n) | Cuts the text to at most n characters. | truncate("abcdefghij", 5) is "abcde" |
Limits
Expressions are bounded so that one cannot slow everything down. These limits are checked when you save, and a refused expression says which one it hit.
| Limit | Value |
|---|---|
| Length of an expression | 8,192 bytes |
| Size (number of parts the formula is made of) | About 2,000 |
Nesting of list functions (all, any, map, filter and similar inside each other) | 2 levels. all(a, any(b, all(c, true))) is refused. |
A written range such as 1..5000 | At most 1,000 numbers |
| A text result (or the total text in a list) | 32 KB |
| Running time | Cut off if an expression runs too long: 50 ms for a data-contract rule, 200 ms for a signal transform, 500 ms for a cohort filter or an offer expression |
repeat is not available. An expression that runs over its time limit counts as a failure: an offer whose eligibility expression or score formula overruns is excluded for that profile.
Common problems
| Symptom | Cause | What to do |
|---|---|---|
| invalid operation: string + int on save | + between text and a number. | Convert one side with string() or int(). |
| expression nests predicate functions … 3 deep; the limit is 2 | List functions inside list functions inside list functions. | Split the work: compute a signal or a computed attribute first, and use that. |
| A transform seems to do nothing | The expression failed at run time, so the raw value was kept. | Test it on sample values; check the type (text or number). |
| An offer never shows | The eligibility expression errors for profiles missing a value. | Add ?? default for fields that can be absent. |
| A score formula returns 0 for everyone | The formula errors or returns text. | Return a number. signals.x ?? 0 covers a missing signal. |
| A cohort filter matches nobody | A signal name is misspelt or does not exist for that entity. | Check the name on the Signals screen. |
Related
- Query filters for the filter builder used by segments and reports.
- Segments, signals and cohorts
- Attribute types