Paperless-ngx Workflow: Triggers, Actions, and Examples That Automate Filing
A Paperless-ngx workflow is a rule made of one or more triggers and a list of actions. The trigger says when the rule runs (a file starts consuming, a document is added, a document is updated, or a date is reached), its filters say which documents it applies to, and the actions say what happens: assign tags, a correspondent, a storage path, an owner or custom fields, remove metadata, send an email or a webhook, remove a PDF password, and a few more. You build them under Workflows in the management section of the web UI, and Paperless applies them in sort order.
Most problems people hit with workflows come from picking the wrong trigger, because each trigger sees different information about the document. This guide covers the triggers and filters first, then the actions and placeholders, then six workflows worth copying and how to debug them. Everything here is checked against the workflow documentation for v3.4.2, the current release at the time of writing.
If you were looking for the recommended way to handle documents day to day (inbox tag, review, file the paper by ASN), that is a different “workflow”. The docs call it the recommended workflow, and our Paperless-ngx tips article covers it.
The four triggers and what they can see
| Trigger | Runs | Can filter on | Good for |
|---|---|---|---|
| Consumption Started | Before the document exists | Source, file name, file path, mail rule | Owner, permissions, and tags based on where a file came from |
| Document Added | After OCR and automatic matching | Content, tags, document type, correspondent, storage path, custom field query | Anything that depends on what the document is |
| Document Updated | When an existing document is saved | Same as Document Added | Follow-up actions after a person reviews a document |
| Scheduled | Hourly check against a date | Same as Document Added, plus a date and offset | Reminders, retention, recurring follow-ups |
The split between the first two matters most. At Consumption Started, Paperless knows the source (consume folder, API upload, mail fetch or web UI), the file name and the path, but it has no text, no correspondent and no document type yet. At Document Added, the source and file path are gone, but the content has been extracted and matching rules have already assigned tags, correspondent, type and storage path.
So “files from the scanner’s accounting folder belong to the finance group” is a Consumption Started job, and “invoices from this supplier get a storage path and a due date field” is a Document Added job. Trying to filter on correspondent at consumption time silently matches nothing.
A few details on the filters themselves:
- File name and path filters accept
*wildcards and are case insensitive. A file name filter must match the whole name, so use*invoice*rather thaninvoice. - Path filters on subfolders only make sense if
PAPERLESS_CONSUMER_RECURSIVEis enabled, otherwise Paperless never picks up files from subfolders. - Content matching offers Any word, All words, Exact match, Regular expression and Fuzzy word. There is no Auto option here, unlike on tags and correspondents.
- The advanced filters for the later triggers include any, all or none of a set of tags, document type and correspondent (with “not” variants), storage path, and a custom field query using the same builder as the document list.
Scheduled triggers check by default every hour at five past, controlled by PAPERLESS_WORKFLOW_SCHEDULED_TASK_CRON. You choose the date to compare (added, created, modified, or a date custom field), a day offset where negative values fire before the date, and whether the schedule repeats every N days.
Actions
The current release offers these action types:
- Assignment: title, tags, correspondent, document type, storage path, owner, view and edit permissions, and custom fields with or without a value.
- Removal: specific or all tags, correspondents, document types, storage paths, custom fields, owner and permissions.
- Email: send a message with placeholders in subject and body, optionally with the document attached. It needs email sending configured.
- Webhook: POST to a URL with a text body or key-value parameters, sent as JSON or form data, with custom headers, and optionally the document file itself.
- Move to Trash: always runs at the end of the workflow. Used in a Consumption Started workflow, it aborts consumption and deletes the file.
- Password Removal: tries a list of passwords on encrypted PDFs and stores the decrypted file as a new document version.
- Remote OCR: sends matching documents to the configured remote OCR engine. It only works with Consumption Started.
- Apply AI Suggestions: applies the configured AI service’s title and metadata suggestions. It works with every trigger except Consumption Started, because it needs the extracted text.
One rule governs how actions combine. Workflows and their actions run in sort order. For single-value fields (title, correspondent, document type, storage path, owner), a later assignment overrides an earlier one. For tags, custom fields and permissions, assignments are merged. When two workflows disagree, the one with the higher sort order wins.
Placeholders for titles and webhooks
Title assignments, email text and webhook bodies are Jinja templates. With any trigger you can use {{ correspondent }}, {{ document_type }}, {{ owner_username }}, the {{ added }} family (added_year, added_month, added_day and so on), {{ original_filename }}, {{ filename }}, {{ doc_title }} and {{ custom_fields }}. The Document Added and Document Updated triggers add the {{ created }} family, {{ doc_id }} and {{ doc_url }}. The last one only works when PAPERLESS_URL is set.
The trigger limitation applies here too. A title template such as {{ created_year }} {{ correspondent }} {{ document_type }} belongs in a Document Added workflow. At Consumption Started the correspondent and type are usually empty and the created date is not available, so you get a title full of blanks.
For custom fields, {{ custom_fields | get_cf_value("Invoice Number", "") }} returns a fallback when the field is missing, which keeps titles readable on documents that have not been filled in yet. Dates can be localized with the localize_date filter, for example {{ created | localize_date('MMMM', 'en_US') }}.
Six workflows worth building
-
Owner by scanner folder. Trigger: Consumption Started, source Consume Folder, path filter
*/anna/*. Action: assign owner Anna and view permission for the household group. One workflow per person, and every scan lands with the right owner without anyone touching it. -
Mail rule labels. Trigger: Consumption Started, mail rule “Utility bills”. Action: assign tag
billsand document type Bill. Mail rules can already set some metadata, but a workflow keeps the logic in one place with the rest of your rules. -
Invoice preparation. Trigger: Document Added, document type Invoice. Actions: assign storage path Invoices, add custom fields Invoice Number and Due Date without values, and set the title to
{{ correspondent }} invoice {{ created }}. The empty fields are a visible to-do list, and the storage path files the document as soon as they are filled. Our guide to Paperless storage paths shows templates that read those custom fields. -
Contract reminder. Trigger: Scheduled, date custom field Contract End, offset -30. Action: email yourself with
{{ doc_title }}and{{ doc_url }}in the body. You get a link to the contract a month before it ends. -
Notify another system. Trigger: Document Added, any tag
to-pay. Action: webhook with a JSON body:{ "id": "{{ doc_id }}", "title": "{{ doc_title }}", "correspondent": "{{ correspondent }}", "type": "{{ document_type }}", "url": "{{ doc_url }}" }Add an
Authorizationheader if the receiving service expects one, and enable “include document” only if it actually needs the file. -
Unlock bank statements. Trigger: Consumption Started, file name
*statement*. Action: Password Removal with your bank’s PDF password. Because the trigger fires before the file exists, Paperless first stores the encrypted file without OCR text, then re-consumes the decrypted file as a new version with normal text extraction. With a Document Added trigger the decryption happens right away, but the first version still has no text.
Debugging and ordering
When a workflow does not do what you expected, check these in order:
- The trigger. Most “it never runs” reports are correspondent, type or content filters on a Consumption Started trigger.
- The sort order. If a field ends up with the wrong value, a later workflow probably overwrote it. Give broad defaults low sort numbers and specific exceptions higher ones.
- The document’s History tab. Changes made by workflows are recorded there with their actor, which shows which rule touched the document.
- The logs. Webhooks are sent from the task queue with a five second timeout and up to three retries when the receiver returns an error status, and failures are written to the log. Delivery is also subject to
PAPERLESS_WEBHOOKS_ALLOWED_PORTSandPAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS, so a webhook to a service on the same host can be blocked by configuration rather than by the network.
Two habits prevent most surprises. When a Document Updated workflow should act only once, have it assign a marker tag and exclude that tag in its own filter. And remember that Consumption Started and Document Added only fire for new documents; to reach documents already in the archive, use a Scheduled or Document Updated trigger, or re-run matching with the document_retagger command.
Workflows also have no owner. Everyone with permission to edit workflows sees and can change all of them, and a workflow can change permissions on any document it matches. The docs suggest restricting workflow access for that reason.
What workflows cannot do
Workflows route and label documents based on information Paperless already has. They do not understand the document. A Document Added filter on content works only as well as the OCR text and your match pattern, and assigning document type Invoice still depends on matching rules or a person getting the type right first. Poor scans and documents that look alike are where filing goes wrong, and no ordering trick fixes a wrong correspondent.
That is the gap the webhook action is useful for. OCRskill connects to Paperless through a workflow webhook, reads each new page with a vision model, and returns the document type, correspondent and issue date for Paperless to store as metadata. Your own workflows then act on those values: storage paths, owners, reminders. The setup is described in our Paperless-ngx archive tutorial.
Conclusion
Pick the trigger by what the workflow needs to know. Use Consumption Started for anything based on the file’s origin and Document Added for anything based on content or metadata. Keep Document Updated and Scheduled for review steps and dates. Set sort order deliberately, because single-value assignments override and multi-value ones merge. Start with two or three workflows that remove work you do every week, check the History tab on the first documents they touch, and add more only when you can see a manual step repeating.
