Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
InflowEL — Expression Language Manual
A practical way to author a reusable expression
Start with the input contract and the business question, then write the smallest pure expression that answers it. A rule can decide whether a requested quantity is eligible; it does not approve a human task or deduct a balance merely because the result is true. Effects remain in their admitted action/service/workflow boundary.
New reusable rules should declare inputs and use canonical namespaces such as inputs:requestedDays. Retired bang separators and JavaScript ternary syntax are not interchangeable with InflowEL. InflowEL conditionals use if … then … else …. Distinguish a name that was never declared from a declared nullable value, and use typed source fields rather than relying on apparent JSON shape.
| Authoring stage | Record and inspect |
|---|---|
| Define inputs | Names, kinds, ONE/MANY, requiredness and description; unknown supplied names are not harmless extras. |
| Choose source | Expression body is text; the create/update HTTP request is a separate JSON envelope. |
| Validate | Syntax, declared references, function signatures and any purpose restrictions. |
| Try examples | Normal value, boundary, absent optional value, wrong type and denied nested rule. |
| Publish and call | Actual workspace, rule key and supported published version; use returned IDs rather than guesses. |
| Diagnose | Safe error code/location plus the original expression and input shape, without logging secrets. |
The examples below are source-backed expression designs and request fragments. They are not a statement that a provider, workflow, browser or shared data environment has executed them. Continue with the leave data/rules tutorial for the surrounding publication sequence.
Worked examples
Example DATA-EL-01 — Decide eligibility from an explicit two-input contract
Scenario and inputs. Nadia defines leave-eligible with required INTEGER inputs requestedDays and availableDays. Mohammad requests 5days and the policy data supplies 12available days. The expression is a reusable Boolean decision; the amount of available leave must come from the application’s admitted source rather than trusting a claimant’s unverified form field.
Procedure. 1. Declare both input names and types in the rule editor. 2. Enter inputs:requestedDays > 0 and inputs:requestedDays <= inputs:availableDays as the expression body. 3. Validate the body and test 5/12,0/12,13/12 and a missing required input. 4. Publish the reviewed rule and record its actual version for consumers that require a pin. 5. In the containing workflow, use the result as an eligibility fact and retain the separate manager decision and authorized mutation path.
Expected result. The first input pair evaluates true; zero or an amount beyond the available balance evaluates false. A missing required input is a contract error, not a false eligibility answer that can be silently presented as a business decision.
Failure and recovery. If a reference is reported undeclared, compare its exact name and namespace with the input contract. Correct inputs:requestedDays, not the global variable store. If the rule is denied, fix the intended caller’s scoped access or change the design; do not run it as an administrator merely to obtain a result.
Sources. ExprInterpreter.java, RuleInputDefinition.java.
Example DATA-EL-02 — Sum financial inputs without losing exact cents
Scenario and inputs. An expense extension contains exact source amounts 0.10,0.20 and 125.50. Nadia wants a total under the current explicit decimal function contract. Ordinary arithmetic follows its documented DECIMAL64 policy; an exact financial operation must deliberately use the appropriate admitted first-party function and preserve exact values before they reach the evaluator.
Procedure. 1. Read the function catalog for decimalSum and confirm its pack/version is admitted. 2. Supply exact Numbers, converting original decimal text with the native number function where appropriate, rather than first constructing rounded binary values in a client. 3. Evaluate decimalSum([number("0.10"), number("0.20"), number("125.50")]). 4. Apply the published settlement/rounding policy once at the intended business boundary, not separately to every display fragment. 5. Test the supported empty-list and missing-element refusal behavior alongside the normal example.
Expected result. The mathematical total is 125.80; scale/display representation may remove trailing zeros without changing that value. The calculation produces a value only: it does not create a financial posting or authorize a payment.
Failure and recovery. An empty list is not accepted by decimalSum; use an explicit known zero input only when business meaning says there are no segments. A value already rounded upstream needs its original source restored. Do not conceal a type/refusal error by substituting zero or broadening the business effect.
Sources. ExprInterpreter.java, DecimalSumFunction.java.
Example DATA-EL-03 — Compose a published policy without creating a permission bypass
Scenario and inputs. A permitted Constant rule leave-max-days holds the policy limit, and a second expression needs to compare that policy with requestedDays. Nadia can author both rules, but Sara’s eventual application/session may have different access. Display labels and draft existence do not establish that an eligible published dependency can be called.
Procedure. 1. Publish the reviewed constant using its actual value contract. 2. In the dependent rule, declare requestedDays and use the supported constants:["leave-max-days"] reference or the documented constant helper appropriate to the editor. 3. Validate dependency discovery and test under the actual intended caller/workspace. 4. Where a published callable rule is needed instead of a constant, use the canonical rules:key(name: value) syntax and the callee’s real declared input names. 5. Keep the published dependency/version semantics visible in the containing rule’s release review.
Expected result. A permitted consumer receives the constant or rule result through the normal resolver, with existing cycle/depth/input checks. The nested call cannot turn a caller-chosen name into authority for another workspace or action.
Failure and recovery. A denied dependency is different from a missing key or cyclic call. Identify which exact published dependency and scope failed; grant only the intended access through its owner or remove the dependency. Do not inline secret data from another actor or replace a failed policy call with a permissive default.
Sources. PublishedRuleExpressionReferences.java, DefaultRuleDefinitionService.java.
Example DATA-EL-04 — Correct syntax and absence errors without changing the business rule
Scenario and inputs. Nadia first writes JavaScript-style requestedDays ? true : false and later copies an old bang-separated input name. A different optional input, decisionComment, is legitimately declared but absent. These are three separate conditions: invalid syntax, an undeclared reference and an admitted nullable value.
Procedure. 1. Read the diagnostic code and character location before changing inputs. 2. Replace a ternary with an actual InflowEL conditional such as if inputs:requestedDays > 0 then true else false. 3. Replace retired namespace separators with the declared inputs: form. 4. For decisionComment, inspect requiredness and use supported null/coalesce logic instead of inventing a missing variable. 5. Test an absent declared optional input and a genuinely undeclared name separately, then republish only after the intended input/output contract remains unchanged.
Expected result. The corrected conditional is syntactically valid and its true/false result still answers the same numeric question. A declared nullable input can represent absence, while a name outside the rule contract remains a validation error.
Failure and recovery. Changing an input to ANY or deleting requiredness merely to silence a useful error weakens the contract. Correct the reference or mapping and retain the original business constraints. Never print raw confidential inputs in a shared diagnostic; the safe error and source position are usually enough to identify the authoring mistake.
Sources. ExprInterpreter.java, InflowExpressionEvaluatorTest.java.
Detailed reference
InflowEL is the platform-owned expression language used in sequence flow conditions, and (as later phases land) multi-instance cardinality, conditional events, and input/output mappings. It is built into the platform with no third-party dependency.
Design guarantees:
- Safe: the interpreter can only read process variables. There is no reflection, no type access, no method calls on values, no I/O.
- Policy-aware determinism: pure functions are deterministic — same
variables, same result. Volatile functions such as
today()andnow()are registered as non-deterministic so rule-purpose policies can allow or block them explicitly. - Bounded: expression length ≤ 4000 chars, nesting depth ≤ 64, token
count ≤ 1000, identifier length ≤ 63 chars, regex pattern ≤ 200 chars.
Hostile input fails fast with
EXPRESSION_LIMIT, never a stack overflow.
Values
Strings, numbers, booleans, lists, objects (maps), and null. All numbers are
decimal (BigDecimal) — 0.1 + 0.2 == 0.3 is true in InflowEL.
A process variable can be null, and null means ABSENT. Two spellings reach
the same value: a field a form submitted empty, and a declared case-file
variable nothing has written yet — a declared variable is in scope from the
moment it is declared and reads as a typed null until something writes it
(process spec A2.2). EXPRESSION_UNDEFINED_VARIABLE is reserved for names that
genuinely are not declared. (An earlier version of this manual said process
variables could not be null "because the variable map rejects null values";
VariableMap has kept null entries for as long as Studio LiveForm has sent
them.)
Because null is absence, an ordering comparison against it answers false
rather than failing — discount > 100 on an untouched discount is false —
and both directions are false at once, so < and >= stop being each other's
negation wherever a null is involved. Test for absence with x = null, supply
defaults with coalesce(...), and use has('name') or has('object.path') to
ask whether a name is in scope at all (a declared variable answers true
whether or not anything has written it). The
path passed to has() must be a fixed string literal in reusable rules;
computed paths such as has(path) or has(concat(...)) are rejected at
publication because their scope cannot be verified against the rule contract.
Reusable-rule input contracts and scopes
New reusable rules declare an ordered, typed input contract and reference its
members with the inputs: namespace: inputs:amount, inputs:customer.tier,
and has('inputs:customer').
: is the only separator a namespace reference can use. An earlier, retired
spelling used ! instead — ruleinput!amount, and its alias ri!amount — but
the platform never shipped, so there was never a published rule body anywhere
spelled that way for the engine to stay compatible with. The parser now refuses
! as a separator outright, with a clear EXPRESSION_SYNTAX error naming the
: spelling to use instead, rather than silently accepting it.
Published versions with a non-empty contract reject missing required values,
unknown supplied values, type/cardinality mismatches, and undeclared canonical
or bare references. Historical versions whose contract is empty retain bare
name behavior (amount, has('amount')) so existing rules keep running; new
authoring should not rely on that compatibility mode.
The namespaces
| Write this | Reads |
|---|---|
inputs:name |
a declared rule input |
locals:name |
a value named inside this rule |
constants:key |
a published CONSTANT rule |
rules:key(name: value) |
calls a published rule |
processvars:name |
a process variable — the case file |
output:name |
an output the current process node just produced |
process:name |
the running instance's metadata |
error:name |
the failure the current handler is recovering from |
data:name |
a screen's resolved data-control values |
The plural/singular split is deliberate rather than an inconsistency: a
namespace you name a member of is plural (inputs:, locals:, constants:,
rules:, processvars:), and a single ambient object is singular (process:,
error:, data:).
Every namespace in that table resolves. There used to be five that did not —
processvars:, process:, error:, event: and data: parsed, were listed
here, were offered by the editor, and threw Unknown variable at every
evaluation site, forever. That third state is now forbidden: a namespace either
resolves or is not a namespace, and a test walks the engine's registry asserting
that every entry in it actually answers. The editor's completion table is
generated from that same registry, so what you are offered while typing and what
the engine resolves cannot come apart. (This page is prose and is not generated —
it is the one copy still kept by hand.)
Typed members after a dot (spec 4262). The editor suggests a value's fields after a dot whenever their shape is known:
- AI task calls. After
rules:<key>(…).,rules:["<key>"](…).orrule('<key>').the editor suggests the AI task's result fields. A list field offers nothing after a dot (read its items with a comprehension), a version-pinned call (rules:<key>@2(…)orrule('<key>', 2)) offers nothing, and a Text task returns Text, so it has no fields. - Case variables. In the lifecycle designer, after a case variable declared as Record of X, the editor suggests
X's fields, through its relations, in every expression editor including email letters. A variable pinned to a
published version gets exactly that version's fields. A list variable has no fields after a dot.
The suggested fields do not limit what you may write: other member paths (the system id, relationship key columns)
stay valid. A suggested Number, Text or Yes/No field carries its type into the check, so
customer.score(a Number) where a Text is expected is reported, as the runtime would refuse it. A date or date-time field is stored as ISO text, so it is typed as any value:date(customer.due)and a Text binding of it stay valid. - No requests. Rule shapes come with the rule list the editor already loads, and record types with the list the designer already loads.
processvars:name is the bare name name. It is the explicit spelling of
the case file, not a second store: the same map, the same value, the same miss.
Write whichever reads better.
process:, error: and data: are ambient objects, and ns:member is
exactly ns.member — one lookup with two spellings. Wherever the dot form
answers, the colon form answers; where the root is not bound, both fail the same
way. So process:instanceId and process.instanceId are the same expression,
and error.code is what a boundary handler branches on:
error.code = 'PROCESS_DOCUMENT_ACCESS_DENIED'
error is set by the engine when a node fails and an error boundary catches it:
error.nodeId, error.code, error.message.
There is no event: namespace. Nothing in the platform binds an event root, so
it was removed rather than left parsing — the same test input: failed. There is
no task: namespace yet either, and task is reserved so that one can arrive
later without shadowing a variable somebody declared in the meantime.
output: is the one member-namespace spelled in the singular, and the reason is
worth stating so nobody "corrects" it: the plural form it would otherwise take,
outputs:, would pair with an inputs: that has meant rule inputs since v2 —
so a symmetric pair was never available for node I/O.
output: resolves only while a process node's output mapping is being applied —
inside that mapping's transform or its set-at index expression — and it names
the fields the node's step just produced. It exists for one job: reshaping a
produced value on its way into the case file, such as output:document.id or
upper(output:status). It is discarded when the mapping commits; nothing
survives a node except what a mapping writes.
There is no input: namespace. A node's evaluated inputs are not addressable,
because the engine cannot recover them everywhere an output mapping runs — a node
resumed after a wait no longer holds them — and a namespace that resolved in some
places and failed in others would be worse than none. input: is an unknown
namespace everywhere, refused identically when you publish and when the process
runs.
constants:, rules: and output: are governed: caller data can never
impersonate one. Supplying a variable named constantTaxRate does not make
constants:taxRate read it, and a case-file variable named document does not
make output:document read it — those values live in bindings the engine
installs, never in the ordinary variable map.
The ambient objects are different, and the difference is worth being clear
about: process:x reads whatever is bound at process, because that is what
process.x does and the two must not disagree. What keeps the engine's metadata
honest there is the reserved-name registry — process, task, error and
event cannot be declared as process variables and cannot be written by any
authored step — rather than the separator you used.
Calling another rule
rules:approvalCheck(amount: order.total)
rules:approvalCheck(amount) -- shorthand for amount: amount
rules:approvalCheck@2(amount: order.total)
constants:taxRate
Arguments are named, and the called rule receives only what you pass it.
This is the substantive difference from the older rule("key") form, which
handed the callee your entire set of variables — so a rule worked only while you
happened to name your variables what it declared, and renaming one of yours
could change its answer with no error anywhere.
Positional arguments are refused on purpose: making argument order the contract reintroduces exactly that fragility.
A wrong argument name, or a missing required input, is reported while you type rather than when the rule runs.
@2 pins a version. It is rare and usually unnecessary — the default is the
latest published version — but without it a published rule's meaning changes
retroactively when something it calls is republished, so a decision can no
longer be re-run as it was made.
Hyphens. - is subtraction, so rules:versioned-policy(x) would otherwise
read as rules:versioned minus policy — a valid subtraction with a wrong
answer. It is refused.
A key you create today will not hit this: the Studio generates keys with
underscores, so Calculate Tax becomes calculate_tax and rules:calculate_tax
just works. That is the reason it generates them that way.
A key made before that, or one carried in from an import, may still contain a
hyphen. Both remain valid keys and both keep working — reach them with the
bracket form, rules:["versioned-policy"](x). For arithmetic, put spaces around
the operator: locals:total - 1.
Syntax
amount > 10000 && currency == 'USD'
request.customer.tier == 'GOLD'
contains(['GOLD', 'PLATINUM'], tier)
startsWith(lower(name), 'inflow')
amount * (1 + taxRate) <= budget.remaining
not has('discount') or discount < 0.5
- Literals:
42,3.14,'text'or"text",true,false,null, lists[1, 2, 3]. - Variables:
amount, nested accessrequest.customer.tier, indexingitems[0],request['customer']. - Operators by precedence (low to high):
||/or;&&/and;==(alias=),!=;<,<=,>,>=;+,-;*,/,%; unary!/not,-. +concatenates when either side is a string, adds when both are numbers.- Comparisons require two numbers or two strings. Equality across different
types is
false(never an error); relational across types is an error —a > 500with a booleanais a mistake, not a question with an answer. Relational against a null is the one exception: it isfalse, because null is absence and absence has an answer (see Values).betweencomposes from the same rule, so it inherits both halves. &&and||short-circuit.
Functions
size(x) string/list/object size · contains(c, v) string or list
membership · startsWith(s, p) · endsWith(s, p) · lower(s) · upper(s) ·
trim(s) · abs(n) · min(a, b) · max(a, b) · round(n) · floor(n) ·
ceiling(n) · number(s) parse string to number · string(x) ·
coalesce(a, b, ...) first non-null · has('name') variable presence ·
matches(s, regex) full-match.
Error codes
EXPRESSION_SYNTAX, EXPRESSION_EMPTY, EXPRESSION_LIMIT,
EXPRESSION_TYPE, EXPRESSION_UNDEFINED_VARIABLE, EXPRESSION_NULL_ACCESS,
EXPRESSION_INDEX, EXPRESSION_ARITHMETIC, EXPRESSION_ARGUMENTS,
EXPRESSION_UNKNOWN_FUNCTION, EXPRESSION_NOT_BOOLEAN.
Unknown variables are errors, not false — a typo in a condition should
surface loudly, not silently route down the default flow. A DECLARED variable
is not unknown, even before anything writes it: it reads as null and the
ordering operators answer false, which is the author's stated intent rather
than a typo.
Where it runs today
- Exclusive gateways (
DefaultGatewayEvaluator): conditioned flows are evaluated in model order; firsttruewins; an unconditioned non-default flow always matches; the default flow is the fallback when nothing matched; no match and no default raisesENGINE_GATEWAY_NO_PATH. A condition that fails to evaluate raisesENGINE_CONDITION_EVALUATION_FAILED(will become an incident once the incident model exists). - Publish-time validation (
DefaultProcessModelValidator): everyconditionExpressionis parsed at validation/publish; syntax errors are reported asINVALID_CONDITION_EXPRESSIONbefore the model can go live.
Conditions are carried in BPMN XML via the inflow:condition attribute on
sequenceFlow, and inflow:default="true" marks the default flow.
Extension points
The engine depends on the ExpressionEvaluator port
(com.inflowai.platform.expression), not on InflowEL directly. A FEEL or
other evaluator can be introduced later as an alternative port implementation
without engine changes. Parsed expressions are cached by
InflowExpressionEvaluator.
v2 update (2026-07-02)
InflowEL now lives inside the rules engine:
com.inflowai.platform.rule.expression. All evaluation goes through the
RuleService front door (evaluate, evaluateCondition,
validateExpression) with a RulePurpose; the BPMN gateway and the model
validator no longer touch the evaluator directly.
Natural-language grammar additions
if amount > 10000 then 'Manager' else 'Auto'
tier in ['GOLD', 'PLATINUM']
amount between 1000 and 5000
for item in items where item.qty > 0 return item.price * item.qty
every item in items satisfies item.qty > 0
some approval in approvals satisfies approval.role = 'finance'
Comprehensions are the only form of looping: no while, no recursion, no
mutable state — every expression terminates by construction. every over an
empty list is true; some over an empty list is false. The loop variable
shadows outer variables inside the comprehension only. Reserved words:
if, then, else, for, in, where, return, every, some, satisfies, between,
and, or, not, true, false, null.
Compiled evaluation (performance)
Expressions compile to lambda trees (CompiledExpression), cached by the
evaluator. For batch workloads, compile against a SlotSchema and evaluate
Object[] frames — measured ~70–90M evaluations/sec/core for a typical
condition in the sandbox. evaluateBatch(compiled, frames) processes rows
in bulk. Equivalence between the compiled and interpreted paths is pinned by
CompiledExpressionTest.
Function registry
Functions are extension points: implement ExpressionFunction (name,
deterministic flag, category) and register through
ExpressionFunctionRegistry — built-ins use the same mechanism. Lookup is
case-insensitive. Bundled and administrator-approved custom function plugins use
the current manifest/approval and isolated runner contract, described in
First-Party Expression Functions and
Expression Function Plugin Runner.
Do not create a conf/expression-functions XML catalog as an installation path.
Volatile functions (today(), now()) carry deterministic() = false for
purpose-based enforcement when RulePurpose policies land.
Date-time and Hijri (Umm al-Qura)
Gregorian dates: date('2026-07-02'), today(), addDays/addMonths/addYears,
year/month/day/weekday (weekday is ISO: 1=Monday … 7=Sunday, so a weekend is
weekday(d) >= 6), startOfMonth/endOfMonth, formatDate(d, pattern[, locale]).
Wall-clock date-times: now() (current instant), datetime('2026-07-04T09:30'),
hour(dt) (0-23), minute(dt) (0-59), addHours/addMinutes.
dateDiff(a, b, unit) accepts 'days'|'months'|'years' (calendar granularity)
and 'hours'|'minutes' (wall-clock granularity), signed positive when b is
after a — e.g. an SLA breach is dateDiff(createdAt, now(), 'hours') > 48.
Dates and date-times compare naturally (<, between): a date coerces to
start-of-day when compared against a date-time. Date variables arriving as ISO
strings through JSON (test panel, Web API) — '2026-07-02' or
'2026-07-04T09:30:00' — are coerced by both the comparison operators and the
date functions, so weekday(dueDate) and expiresAt < now() work on
transported inputs without an explicit date(...)/datetime(...) wrap.
Hijri via java.time HijrahChronology (official Umm al-Qura tables, no dependency):
toHijri(date('2026-07-02')) -- {year: 1448, month: 1, day: 17}
toGregorian(hijriDate(1447, 9, 1)) -- 2026-02-18 (1 Ramadan 1447)
hijriYear(d), hijriMonth(d), hijriDay(d)
hijriMonthName(hijriDate(1447, 9, 1)) -- رمضان
formatHijri(d, 'dd MMMM yyyy', 'ar')
addHijriMonths(d, 3) -- chronology-aware month arithmetic
Supported range 1300–1600 AH (~1882–2174 CE); outside it conversions raise
EXPRESSION_DATE_RANGE with a plain-language message rather than
approximating.
Human error messages
ExpressionException now carries humanMessage() in addition to the stable
code and system detail. Unknown variables get did-you-mean suggestions from
edit distance over the variable names ("I don't recognize 'amuont'. Did you
mean 'amount'?"). Position offsets for designer squiggles: planned with the
designer UI slice.
Excel-parity functions, tier 1
Text (1-based positions, like Excel): left(s, n), right(s, n),
mid(s, start, len), len(s), concat(...) (variadic, nulls become
empty), split(s, delim), substitute(s, old, new), textJoin(delim, list).
Math: sqrt(n), power(n, exp), roundTo(n, digits).
Aggregates over lists: sum, average, count, first, last,
distinct, any, all — designed to compose with comprehensions:
sum(for item in items where item.status = 'OPEN' return item.total)
any(for n in nums return n > 3)
Assist backend (invisible expression assistant)
POST /api/assist/expression/suggest (plain language -> expression) and
POST /api/assist/expression/fix (broken expression + error -> corrected).
Routed through the AI Gateway to the purpose default when it names an existing
model, otherwise the enabled model of an administrator AI provider connection
(no configured assist model; platform.assist.model and
platform.assist.provider were removed by SCRUM-4817). Every
candidate passes the trust gate — code-fence stripping, then the real
InflowEL parser — before it is returned; invalid suggestions are never
surfaced (available=false instead). Kill switch and tuning in
conf/custom_config.properties (platform.assist.*). When disabled, with no
enabled model, or when the model is down, responses degrade silently and the designer falls back to
deterministic completion.
To use a local model, run your own Ollama (the Compose stack no longer includes one) and connect it in Authorization -> AI providers.
Rule definitions — lifecycle and Web APIs
Rules are named, versioned artifacts with the same lifecycle as process
definitions: draft -> validate -> publish -> versioned execution, per-key
versioning with a stable definition id (unique (rule_key, version) index,
migration 22).
The production rule designer supports four business rule kinds:
- CONSTANT: a fixed JSON scalar, list, or object.
- EXPRESSION: one InflowEL expression.
- DECISION_TABLE: JSON rows such as
{"hitPolicy":"FIRST|COLLECT","rows":[{"when":"<InflowEL or blank = always>","output":{...}}]}. - QUERY: a governed query expression over published data-model record types, backed by the query builder.
Every rule validates before publish. Published versions are immutable. A republish creates a new version; restoring an older version opens it as a new draft and publishing that draft creates the next version number.
Rule composition is available inside expressions and query filter/value expressions:
constant('approval-limit')
constant('approval-limit', 3)
rule('calculate-risk-band', customerId)
rule('calculate-risk-band', 2, customerId)
rule('open-invoices-for-customer', { customerId: customerId })
Every rule kind — including QUERY — is called through rule(); there is no
separate queryRule() function.
Only published callable dependencies resolve. Optional version arguments pin the dependency to an immutable version. Composition uses the caller workspace and the same rule access checks, cycle detection, and nesting limits as normal rule execution.
Authoring endpoints: POST /api/rules/drafts,
PUT /api/rules/drafts/{id}, POST /api/rules/drafts/{id}/publish (body
{"exposeAsApi":true} opt-in), and GET /api/rules/{key}/versions/{v}.
Public Web API execution uses
POST /api/rules/{key}/execute[?version=n] with body {"inputs":{...}}.
That public endpoint is intentionally stricter than internal execution:
- The requested version must be published with
exposeAsApi=true; otherwise it returnsRULE_NOT_EXPOSED. - A valid Rule API key is required through
X-Api-Key: inf_rk_...orAuthorization: Bearer inf_rk_...; otherwise it returns 401RULE_API_KEY_REQUIREDwith aWWW-Authenticate: Bearerchallenge. This holds for a caller with no session, for a value that is not a Rule API key (for exampleBearer bogus), and for a signed-in Studio user. - An unknown, malformed, revoked or expired
inf_rk_key returns 401API_KEY_INVALID. A key outside its rule scope returns 403RULE_NOT_IN_KEY_SCOPE. A key pins its own workspace, so a key from another workspace returns 404RULE_NOT_FOUND. All of these fail closed before rule execution. - Browser requests that carry the Studio login cookie still need a CSRF token; integrations should call without cookies.
- A versionless public call resolves the latest exposed version, not merely the latest published internal version.
Studio preview, published interfaces, processes, service tasks, and other
platform internals do not need public Web API exposure. They call the governed
internal execution path (POST /api/rules/{key}/execute-internal or
RuleDefinitionService) and still enforce workspace, business-function, and
object access checks.
Published query rules pin their data-model source metadata at publish time:
model id, record type key, source key, and source version. Runtime execution
uses that exact governed source version and fails closed with
QUERY_SOURCE_VERSION_UNAVAILABLE if the pinned source is no longer available.
Incidents (runtime failures, parked durably)
Engine failures during resume (bad gateway condition, no matching path) are
recorded as durable incidents (migration 23, runtime_incidents) with code,
system message and humanMessage, then rethrown. Recording happens after the
transaction rolls back so the incident row survives the failure it reports.
GET /api/incidents (open, or ?processInstanceId=) and
POST /api/incidents/{id}/resolve. This is the foundation the BPMN
error-event and retry slices build on.
Business rule task — service.rule.evaluate
Processes call published rules through the service.rule.evaluate service
task (implementation rule-evaluate, registered in the service-task
catalogs). Configuration: ruleKey (required), version (optional — latest
when absent, pin for stability), resultVariable (default ruleResult).
The rule receives the current process variables as inputs. Its result lands
in resultVariable alongside ruleMatched and ruleVersion — and when a
decision table returns an output object, its entries are also merged
top-level, so a row output {"route":"manager"} makes route = 'manager'
usable directly on the next gateway.
Every rule execution — from processes (caller = process:<instanceId>), the
Web API (caller = api) or internal modules (caller = internal) — is
audited in rule_execution_records (migration 24) with version, matched
flag and duration. Audit persistence never fails the rule call.
Explicit exact-decimal financial arithmetic
Ordinary numeric operators and sum/average use DECIMAL64 (16 significant
digits), even though their values are represented by BigDecimal. Do not use
that default for a financial contract requiring more digits. The math
pack1.0.1 provides decimalSum and decimalDivide with explicit scale and
rounding; product is already exact. See
first-party functions.
These explicit functions preserve existing expression behavior and do not
perform business approvals, postings or implicit currency conversion.
Saved screen computations reading explicitly declared Long or Decimal inputs/locals preserve exact addition, subtraction, multiplication, remainder and terminating division, plus sum/average over these declared values, including values beyond the browser's safe integer range. Nonterminating division retains DECIMAL64 rounding. Their results cross the browser boundary as exact numeric text when needed; this does not turn Text declarations into numbers. Ordinary numeric expressions and aggregates over untyped numbers retain the defaults above. Called rules retain their own numeric policy; the internal exact calculation marker is not passed across the rule-call boundary.