From 933cb2666dfd7f1a0839108d980020620c0c3628 Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Wed, 27 Dec 2023 00:37:35 -0800
Subject: [PATCH] Update documentation for workflows
---
docs/api.md | 2 +-
docs/usage.md | 72 ++++++++++++-------
src-ui/src/app/app.component.ts | 2 +-
.../workflow-edit-dialog.component.html | 2 +-
4 files changed, 51 insertions(+), 27 deletions(-)
diff --git a/docs/api.md b/docs/api.md
index 82244936f..39a06f37f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -8,7 +8,6 @@ most of the available filters and ordering fields.
The API provides the following main endpoints:
-- `/api/consumption_templates/`: Full CRUD support.
- `/api/correspondents/`: Full CRUD support.
- `/api/custom_fields/`: Full CRUD support.
- `/api/documents/`: Full CRUD support, except POSTing new documents.
@@ -24,6 +23,7 @@ The API provides the following main endpoints:
- `/api/tags/`: Full CRUD support.
- `/api/tasks/`: Read-only.
- `/api/users/`: Full CRUD support.
+- `/api/workflows/`: Full CRUD support.
All of these endpoints except for the logging endpoint allow you to
fetch (and edit and delete where appropriate) individual objects by
diff --git a/docs/usage.md b/docs/usage.md
index 42701728d..66b548a2f 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -238,7 +238,7 @@ do not have an owner set.
### Default permissions
-Default permissions for documents can be set using consumption templates.
+Default permissions for documents can be set using workflows.
For objects created via the web UI (tags, doc types, etc.) the default is to set the current user
as owner and no extra permissions, but you explicitly set these under Settings > Permissions.
@@ -255,29 +255,42 @@ permissions can be granted to limit access to certain parts of the UI (and corre
In order to enable the password reset feature you will need to setup an SMTP backend, see
[`PAPERLESS_EMAIL_HOST`](configuration.md#PAPERLESS_EMAIL_HOST)
-## Consumption templates
+## Workflows
-Consumption templates were introduced in v2.0 and allow for finer control over what metadata (tags, doc
-types) and permissions (owner, privileges) are assigned to documents during consumption. In general,
-templates are applied sequentially (by sort order) but subsequent templates will never override an
-assignment from a preceding template. The same is true for mail rules, e.g. if you set the correspondent
-in a mail rule any subsequent consumption templates that are applied _will not_ overwrite this. The
-exception to this is assignments that can be multiple e.g. tags and permissions, which will be merged.
+!!! note
-Consumption templates allow you to filter by:
+ v2.3 added "Workflows" and existing "Consumption Templates" were converted automatically to the new more powerful format.
+
+Workflows were introduced in v2.3 and allow for finer control over what metadata (tags, doc
+types) and permissions (owner, privileges) are assigned to documents. Workflows can have multiple 'triggers'
+and 'actions'. Triggers are events (with optional filtering rules) that will cause the workflow to be run
+and actions are the set of sequential actions to apply. Currently, there are three events that correspond
+to workflow trigger 'types':
+
+- Consumption: fires _before_ a document is consumed, so events can filter by e.g. source (mail, consumption
+ folder or API) and file path
+- Added: fires _after_ a document is added. At this time path and source information is no longer available but the document
+ has had document type, tags, etc. assigned so these can now be used for filtering.
+- Updated: fires when a document is updated. Similar to 'added' events, can include filtering by tags, doc type, or
+ correspondent
+
+In general, workflows are applied sequentially (by sort order) but the behavior of consequtive workflows depends on the type.
+"Consumption" workflows will never override an assignment from a preceding workflow. "Added" and "Updated" workflow triggers
+will overwrite these values (since these are immediately assigned to the document). Titles are always overwritten by
+subsequent workflows. Assignments that accept multiple items e.g. tags, custom fields and permissions will be merged.
+
+Workflows allow you to filter by:
- Source, e.g. documents uploaded via consume folder, API (& the web UI) and mail fetch
- File name, including wildcards e.g. \*.pdf will apply to all pdfs
- File path, including wildcards. Note that enabling `PAPERLESS_CONSUMER_RECURSIVE` would allow, for
example, automatically assigning documents to different owners based on the upload directory.
-- Mail rule. Choosing this option will force 'mail fetch' to be the template source.
+- Mail rule. Choosing this option will force 'mail fetch' to be the workflow source.
+- Tags (`Added` and `Updated` triggers only). Will filter for documents with any of the specified tags
+- Document type (`Added` and `Updated` triggers only). Filter documents with this doc type
+- Correspondent (`Added` and `Updated` triggers only). Filter documents with this correspondent
-!!! note
-
- You must include a file name filter, a path filter or a mail rule filter. Use * for either to apply
- to all files.
-
-Consumption templates can assign:
+Workflows can assign:
- Title, see [title placeholders](usage.md#title-placeholders) below
- Tags, correspondent, document types
@@ -285,21 +298,21 @@ Consumption templates can assign:
- View and / or edit permissions to users or groups
- Custom fields. Note that no value for the field will be set
-### Consumption template permissions
+### Workflow permissions
-All users who have application permissions for editing consumption templates can see the same set
-of templates. In other words, templates themselves intentionally do not have an owner or permissions.
+All users who have application permissions for editing workflows can see the same set
+of workflows. In other words, workflows themselves intentionally do not have an owner or permissions.
-Given their potentially far-reaching capabilities, you may want to restrict access to templates.
+Given their potentially far-reaching capabilities, you may want to restrict access to workflows.
-Upon migration, existing installs will grant access to consumption templates to users who can add
+Upon migration, existing installs will grant access to workflows to users who can add
documents (and superusers who can always access all parts of the app).
### Title placeholders
-Consumption template titles can include placeholders, _only for items that are assigned within the template_.
-This is because at the time of consumption (when the title is to be set), no automatic tags etc. have been
-applied. You can use the following placeholders:
+Workflow titles can include placeholders but the available options differ depending on the type of
+workflow trigger. This is because at the time of consumption (when the title is to be set), no automatic tags etc. have been
+applied. You can use the following placeholders with any trigger type:
- `{correspondent}`: assigned correspondent name
- `{document_type}`: assigned document type name
@@ -314,6 +327,17 @@ applied. You can use the following placeholders:
- `{added_time}`: added time in HH:MM format
- `{original_filename}`: original file name without extension
+The following placeholders are only available for "added" or "updated" triggers
+
+- `{created}`: created datetime
+- `{created_year}`: created year
+- `{created_year_short}`: created year
+- `{created_month}`: created month
+- `{created_month_name}`: created month name
+- `{created_month_name_short}`: created month short name
+- `{created_day}`: created day
+- `{created_time}`: created time in HH:MM format
+
## Custom Fields {#custom-fields}
Paperless-ngx supports the use of custom fields for documents as of v2.0, allowing a user
diff --git a/src-ui/src/app/app.component.ts b/src-ui/src/app/app.component.ts
index fd2268818..e93fde30c 100644
--- a/src-ui/src/app/app.component.ts
+++ b/src-ui/src/app/app.component.ts
@@ -177,7 +177,7 @@ export class AppComponent implements OnInit, OnDestroy {
},
{
anchorId: 'tour.workflows',
- content: $localize`Workflows give you finer control over the document ingestion process.`,
+ content: $localize`Workflows give you more control over the document pipeline.`,
route: '/workflows',
backdropConfig: {
offset: 0,
diff --git a/src-ui/src/app/components/common/edit-dialog/workflow-edit-dialog/workflow-edit-dialog.component.html b/src-ui/src/app/components/common/edit-dialog/workflow-edit-dialog/workflow-edit-dialog.component.html
index 195d81c5a..e2b8b1de9 100644
--- a/src-ui/src/app/components/common/edit-dialog/workflow-edit-dialog/workflow-edit-dialog.component.html
+++ b/src-ui/src/app/components/common/edit-dialog/workflow-edit-dialog/workflow-edit-dialog.component.html
@@ -112,7 +112,7 @@