Rule Structure

A rule is a YAML mapping inside a list. Each file in rules.d/ contains one or more rules.

Full schema

- id: string                  # (required) Unique identifier across all rule files
  description: string         # (optional) Human-readable description, shown in the UI
  draft: false                # (optional) Disable without deleting — default false
  triggers:                   # (required) list of trigger types
    - all | created | updated
  filters:                    # (optional) fast classifier pre-checks
    - correspondent: "Name"
    - document_type: "Type"
    - storage_path: "Path"
    - tags: "TagName"
  conditions:                 # (required) full boolean block
    - <condition>
  actions:                    # (required) ordered list of actions
    - <action>

Field reference

`id`

A unique string identifier. Used to reference the rule in the REST API, MQTT messages, and execution history. Must be unique across all loaded rule files.

id: invoice_acme_title

`description`

Optional free-text description. Multi-line strings are supported via YAML block scalars:

description: >
  Checks all ACME invoices and sets the title to YYYY/MM.
  Falls back to adding a "Problem" tag if the date cannot be extracted.

`draft`

When true, the rule is parsed and validated but never executed. Useful for work-in-progress rules.

draft: true

`triggers`

A list of one or more trigger types. At least one trigger is required.

triggers:
  - all

`filters`

An optional list of filter conditions. Filters are evaluated before the full condition block and allow fast short-circuiting based on classifier fields (correspondent, document_type, storage_path, tags).

filters:
  - correspondent: "ACME GmbH"
  - document_type: "Invoice"

`conditions`

A required list of condition expressions. All conditions must be true (implicit AND at the top level).

conditions:
  - not:
      - field: title
        match: '^\d{4}/'

`actions`

A required list of actions executed in order when all conditions pass.

actions:
  - set_field: title
    value: "{{ year }}/{{ month }}"
  - save

Multiple rules in one file

Each file is a YAML list, so you can group related rules together:

---
- id: rule_one
  triggers: [all]
  conditions:
    - correspondent: "ACME GmbH"
  actions:
    - save

- id: rule_two
  triggers: [created]
  conditions:
    - document_type: "Invoice"
  actions:
    - add_tag: "Needs Review"
    - save