Skip to content

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 — a when condition plus then output assignments, all in JEXL (the same expression language used by workflow step preconditions).
  • decision-table — input/output columns and rows of cases, with a FIRST or COLLECT hit 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.

id: high-value-order
name: High value order approval
description: VIP orders over 100 get a discount and need approval
type: expression
salience: 10
tags: [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.

{
"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):

CellMeaning
* or blankalways matches
> 100, >= 10, < 5, <= 1, != 0, == 3comparison against the input
100, 99.5numeric equality
'express'equality, as written
VIPstring 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.
FieldTypeDescription
idstringUnique 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.
namestringRequired. Human-readable name.
descriptionstringOptional description.
typestringRequired. expression or decision-table.
versionintegerDefinition version number.
salienceintegerPriority for group (tag) evaluation: higher runs first.
tagsstring[]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.

  • rules.persistence=memory (default) or jpa.
  • Read API for remote runtimes: GET /rules (optional ?tag=), GET /rules/{id} — and the same over gRPC (RuleService.GetRule / ListRules) when rules.grpc.enabled=true (port rules.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 / RuleDeleted on the rules destination, so remote runtimes refresh their caches instantly.

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/rules

Each 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.

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 repos

At 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.