Inflow.aiDocs

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() and now() 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>"](…). or rule('<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(…) or rule('<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 access request.customer.tier, indexing items[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 > 500 with a boolean a is a mistake, not a question with an answer. Relational against a null is the one exception: it is false, because null is absence and absence has an answer (see Values). between composes 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; first true wins; an unconditioned non-default flow always matches; the default flow is the fallback when nothing matched; no match and no default raises ENGINE_GATEWAY_NO_PATH. A condition that fails to evaluate raises ENGINE_CONDITION_EVALUATION_FAILED (will become an incident once the incident model exists).
  • Publish-time validation (DefaultProcessModelValidator): every conditionExpression is parsed at validation/publish; syntax errors are reported as INVALID_CONDITION_EXPRESSION before 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 returns RULE_NOT_EXPOSED.
  • A valid Rule API key is required through X-Api-Key: inf_rk_... or Authorization: Bearer inf_rk_...; otherwise it returns 401 RULE_API_KEY_REQUIRED with a WWW-Authenticate: Bearer challenge. This holds for a caller with no session, for a value that is not a Rule API key (for example Bearer bogus), and for a signed-in Studio user.
  • An unknown, malformed, revoked or expired inf_rk_ key returns 401 API_KEY_INVALID. A key outside its rule scope returns 403 RULE_NOT_IN_KEY_SCOPE. A key pins its own workspace, so a key from another workspace returns 404 RULE_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.

Try “document generation”, “integrations” or “first form”.