What is this?

Admin note: Rulebooks decide what the application does on its own: which invoices get a reminder, who approves a received document, how a line of a received invoice finds its product, how much is ordered from a supplier, what an automation does when an order is paid. Most organisations only switch the ready-made rules on and fill in their settings (Settings > the area of the rules). Writing rules of your own in this language is for a consultant or a developer – or describe the rule in a sentence and let the AI assistant in the rules dialog write it.

Key points:

• One language everywhere: dunning, approval, receiving, purchasing, payment pairing, paying, fulfillment, shipping, the warehouse and automations all use the same rulebooks.
• Safe by design: a rule reads only the facts its area offers and does only the actions its area allows; every result says which rule produced it (“Why”).
• Try before saving: the rulebook tester checks a rulebook and runs it on facts you type in.

Rulebooks

A rulebook is a Markdown text of rules for the rule engine. One rulebook belongs to one domain: dunning, approving documents, receiving, purchasing, payment pairing, paying, fulfillment, shipping, the warehouse domains and automations. The domain decides what the rules may read (facts), decide (targets), look up (resolvers) and do (actions), and when they run. This page describes the language; what each domain offers (its facts, targets, resolvers, actions and triggers) is listed in the rulebook tester for the domain you pick, and on the MCP server as doc://rulebook-domains. A rule may use only what its domain declares.

1. A rulebook

# Upomínky
domain: dunning
const minimum = 50
const firstTemplate = 'UPOMINKA-1'

## Neupomínat malé částky
> Faktura, na které zbývá zaplatit méně než nastavená částka, se neupomíná.
id: minimum
when: remaining < minimum
stop

## 1. upomínka
> Několik dní po splatnosti dostane partner první upomínku se všemi fakturami po splatnosti.
id: first
level: 1
when: daysOverdue >= 3 and reminderLevel < 1
do sendMessage firstTemplate group by partner.id once

• The first line # <title> is the name of the rulebook. Only one # heading is allowed.
• Header lines come before the first rule:
  • domain: <domain> (required);
  • const <name> = <value> (settings the rules use by name);
  • scope: <entities> or scope: *, language: <code>, disable: <rule ids>, secret: true|false.
• ## <rule title> starts a rule (a node). ### <rule> under it is a more specific rule: it applies only when the condition of its parent holds too. A heading may not skip a level.
• Lines under a rule, in this order by convention:

• // starts a comment line. Any other line that is not a directive or a statement is prose and is ignored.

2. Statements

A domain allows only some of the statements: the validator reports a statement the domain does not list.

How the outcome is made

• Every matching rule applies, in written order. stop ends the rest for the subject.
• All matching do actions run (not just the first one). Each action has an idempotency key made of the rulebook, the rule, the action and the subject or group, so once really runs once.
• Several sets of one target: the most specific rule (deepest heading) wins; equal ones are a conflict.
• Layers: system rulebooks (ready-made rules), then the organisation’s methodology, then its own rulebooks in their order.
• A check with block blocks the subject. Every blocking reason is reported, not only the first.

Collections: per line, per component

A statement prefixed with a collection name runs once per element of it:

lines: try product by ean
lines: try product by supplierCode
lines: else ask "Vyberte nebo založte produkt pro ${name}"
lines: check priceDifference <= priceTolerance else warning "Cena ${name} se liší od poslední nákupní ceny"
lines: when: quantity > 0

Inside a collection the element’s facts are read by name. The subject is read by the parent name the domain declares, for example document.partner. <collection>: when: <condition> restricts the elements a rule applies to.

3. Conditions

when:, the when of a statement and check use the filter language (Where):

remaining < minimum
daysOverdue >= 3 and reminderLevel < 1
partner.labels.code in ('VIP', 'PARTNER')
labels.code = 'BEZ-UPOMINEK'
note is null
name like 'servis'          // contains
code begins 'ZB'
isWorkday = false
total > 100000 and (costCenter.code = 'MKT' or branch.code = 'PRAHA')

• Texts are in single quotes; numbers, true and false are bare.

• A relation or a list fact is followed with a dot. For a list, labels.code = 'VIP' means “any of them”.

• A comparison with an unknown (null) fact is false; facts never fail a rule.

• ${name} inside a condition is replaced by a setting or parameter before the condition is read: partner.labels.code in ('${companyLabels}').

• Names a condition may read:

  • the facts of the domain;
  • for domains that run on records (automation, dunning, approval), also the record’s fields and relations;
  • the calendar: today, now, country, isWorkday, isHoliday;
  • the rulebook’s consts, the domain’s settings and the rule’s parameters;
  • the rule’s lets.

  Any other name is reported as Unknown fact "x".

4. Values and messages

The value of set, the arguments of do and the value of let are expressions:

The messages of check and else ask are templates: "Objednávka u ${supplier.name} za ${orderTotal} je nad limitem".

5. Facts of the rule: let

6. Triggers: on:

Only domains with triggers (automations) take on:; the other domains are run by the application (on save, every day, on the ordering page, …).

on: saved
on: created, deleted
on: changed isPaid to true
on: changed status from 'new' to 'confirmed'
on: event 'paid'
on: schedule daily
on: manual

• Several triggers are separated by commas. A rule without on: takes its parent’s triggers; a rule with no on: above it runs on every trigger.
• Events: paid (a payment was paired), sent (a message about the record was sent), fromInbox (a document was created from the inbox).
• In an automation the facts previous.<field> (the value before the change) and changed.<field> (true when the change touched the field) are available.

7. Ready-made rules, settings and parameters

System rulebooks hold ready-made rules: rules with an id, a description, default: on|off and the settings they use. The organisation switches them on or off and fills in their settings; only that choice is stored (as activations), never the text. Its own rules are written in its own rulebooks of the same domain and run after the system ones.

## Velké částky
> Nad nastavenou částku schvaluje vedoucí střediska, jeho nadřízený a pak jednatel.
id: large
default: off
when: total > largeAmount
do requireApproval by costCenter.manager then by costCenter.manager.superior then by role '${directorRole}'

A parameter of a rule: param <name>: <type> [= <default>] ["<label>"]. The types are:

• number, money, days, text, template;
• code <entity>, codes <entity>, where <entity>;
• enum(a, b, c).

A parameter is used as ${name} or as a bare name.

param tolerance: money = 1 "Tolerance"
param labels: codes labels = 'VIP' "Štítky"

8. Examples by domain

Receiving: finding the product of a line

## Hledání produktu podle kódů
id: codes
lines: try product by ean
lines: try product by packageEan
lines: try product by supplierCode
lines: else ask "Vyberte nebo založte produkt pro ${name}"

Purchasing: quantity by packages, a suspicious order

## Množství podle dodavatele
id: packages
set quantity = roundup(max(quantity, minimumQuantity), packageQuantity)

## Podezřelá objednávka
id: suspicious
check orderTotal <= suspiciousOrder else block "Objednávka u ${supplier.name} za ${orderTotal} je nad limitem – zkontrolujte ji"

Approval: small amounts without approval, a changed bank account to the accountant

## Malé částky bez schvalování
id: small
when: total <= 5000
do approve
stop

## Změněný bankovní účet
id: account
when: bankAccountChanged = true
do requireApproval by role 'UCETNI'
stop

Automation: a paid order gets a task for the warehouse

## Zaplacená objednávka
id: paid
on: changed isPaid to true
do createTask 'Vyskladnit ${code}' for 'role:SKLAD'

9. Errors

The parser and the domain report each problem with its line: