Skip to content

Rules DSL — Overview

The Secretary rules engine is driven by YAML files placed in the rules.d directory. Each file contains a list of rule objects.

Concepts

A rule is an automation unit that specifies:

  1. Triggers — which Paperless-ngx events activate the rule (created, updated, or all)
  2. Filters — fast pre-checks on classifier fields that short-circuit evaluation before the full condition block
  3. Conditions — the full boolean expression that must be true for actions to run
  4. Actions — the ordered list of operations applied to the document when conditions pass
flowchart TD
    E[Document event] --> T{Trigger matches?}
    T -- No --> SKIP[Rule skipped]
    T -- Yes --> F{Filters pass?}
    F -- No --> SKIP
    F -- Yes --> C{Conditions pass?}
    C -- No --> SKIP
    C -- Yes --> A[Execute actions]
    A --> SAVE[Changes written to Paperless-ngx]

Directory layout

rules.d/
├── _vars.yml          # Shared Jinja2 variables (optional)
├── invoices.yml       # One or more rules per file
├── bank-statements.yml
└── utils/
    └── tagging.yml    # Sub-directories are supported

Hot-reload

Secretary watches the rules.d directory for changes. New, modified, or deleted files are reloaded automatically — no restart required.

Minimal example

---
- id: tag_inbox_documents
  description: Add the "To Review" tag to every newly created document.
  triggers:
    - created
  conditions:
    - not:
        - field: tags
          contains: "To Review"
  actions:
    - add_tag: "To Review"
    - save

Draft mode

Set draft: true to disable a rule without deleting it:

- id: my_experimental_rule
  draft: true
  triggers:
    - all
  conditions:
    - correspondent: "ACME GmbH"
  actions:
    - save

Draft rules are loaded and validated but never executed.

Next steps