Rule Definitions
The rule engine is the catalog of business rules: it stores, validates, versions and serves rule definitions — it does not execute them. Evaluation happens in the embeddable rule runtime, wherever your data lives.
Rules can be written in JSON or YAML (.json, .yaml, .yml, or .ecrule, which the IDE plugins highlight and validate against the rule schema), stored in version control, and referenced by RULE steps in workflow definitions. They can be imported from Git at startup, on demand via the MCP tool importRulesFromGit, or automatically via a GitHub webhook (POST /rules/webhooks/github, HMAC-signed with rules.git-import.webhook-secret).
There are two rule types:
expression— awhencondition plusthenoutput assignments, all in JEXL (the same expression language used by workflow step preconditions).decision-table— input/output columns and rows of cases, with aFIRSTorCOLLECThit policy.
The sandbox is the same one, too: a rule catalogue is untrusted input for the same reasons a
workflow definition is, and it evaluates on the same threads. What an expression may contain — and
in particular which regular expressions =~ accepts — is listed under
What an expression may contain.
Expression rules
Section titled “Expression rules”id: high-value-ordername: High value order approvaldescription: VIP orders over 100 get a discount and need approvaltype: expressionsalience: 10tags: [orders]when: "order.total > 100 && customer.category == 'VIP'"then: - name: discount expression: "order.total * 0.1" - name: approvalRequired expression: "true"If when is omitted the rule always matches. Each then assignment produces one output, evaluated against the facts.
Decision tables
Section titled “Decision tables”{ "id": "shipping-costs", "name": "Shipping costs", "type": "decision-table", "hitPolicy": "FIRST", "inputs": ["customer.category", "order.total"], "outputs": ["shippingCost", "courier"], "rows": [ { "when": ["VIP", "*"], "then": ["0", "'express'"] }, { "when": ["*", "> 100"], "then": ["5", "'standard'"] }, { "when": ["*", "*"], "then": ["10", "'standard'"] } ]}Each row’s when has one cell per input, and its then one JEXL expression per output.
Cell semantics (compiled to JEXL against the input column):
| Cell | Meaning |
|---|---|
* or blank | always matches |
> 100, >= 10, < 5, <= 1, != 0, == 3 | comparison against the input |
100, 99.5 | numeric equality |
'express' | equality, as written |
VIP | string equality |
Hit policies:
FIRST(default): the first matching row wins; its outputs are the result.COLLECT: all matching rows are gathered; the merged outputs are last-write-wins in row order, and every row’s outputs are also available individually in the evaluation result.
Top-level fields
Section titled “Top-level fields”| Field | Type | Description |
|---|---|---|
id | string | Unique identifier. Generated when a rule is saved without one; a rule imported from a repository without one is given an id derived from its path relative to the scan root — pricing/discount.json becomes pricing.discount — so the next import updates it rather than adding a copy. A rule invoked by a RULE step is better off declaring one. |
name | string | Required. Human-readable name. |
description | string | Optional description. |
type | string | Required. expression or decision-table. |
version | integer | Definition version number. |
salience | integer | Priority for group (tag) evaluation: higher runs first. |
tags | string[] | Tags for evaluating groups of rules together. |
when / then | — | Expression rules only. |
inputs / outputs / rows / hitPolicy | — | Decision tables only. |
Definitions are validated on save against the JSON schema (rule-schema.json) plus semantic checks: row arity must match inputs/outputs, and every expression must parse as valid JEXL.
Storage, API and UI
Section titled “Storage, API and UI”rules.persistence=memory(default) orjpa.- Read API for remote runtimes:
GET /rules(optional?tag=),GET /rules/{id}— and the same over gRPC (RuleService.GetRule/ListRules) whenrules.grpc.enabled=true(portrules.grpc.port, default 9090; off by default). The gRPC API is plaintext and unauthenticated — anyone who reaches the port reads every rule — so enable it only behind mTLS from a service mesh and a network policy; the REST read API sits behind the application’s authentication. - Management UI at
/_rules(Mateu), with the definition editable as JSON/YAML. - MCP tools:
listRules,getRule,saveRule,validateRule,deleteRule,evaluateRule,importRulesFromGit. - On every save/delete in Kafka mode the catalog emits
RulePublished/RuleDeletedon therulesdestination, so remote runtimes refresh their caches instantly.
Importing from a directory
Section titled “Importing from a directory”Rules already on disk — mounted into the container, checked out beside the app, written by whatever generates them — are imported at startup from the directories you name:
rules: directory-import: directories: - /definitions/rulesEach directory is scanned recursively, and every file with a name and a known rule type is
imported. Rules removed from the directory are deleted on the next import, tracked separately
per directory, and only ever rules that this import created.
It is the same import the Git one runs — a clone is a directory — which is the point of it existing.
Rules had no such place before, so the one filter they had drifted from the two that workflows and
forms share: .ecrule ended up declared in the engine’s shared extension list and in the Maven
plugin’s copy of it, and read by neither the engine nor either IDE plugin.
Git import
Section titled “Git import”rules: git-import: # webhook-secret: mysecret # for the GitHub webhook: without it an unsigned webhook is refused (401) # # unless Spring Security protects the app or workflow.message-api.allow-anonymous=true repositories: - url: https://github.com/your-org/your-rules-repo.git branch: main # username / password for private reposAt startup (and on webhook or MCP request) every .json/.yaml/.yml/.ecrule file with a name and a rule type is validated and upserted into the catalog. It is the file’s content that decides — a repository holding workflows next to rules is harmless whatever the files are called.