paperap.models.workflow.model module

Models for Paperless-NgX workflow functionality.

This module contains the data models representing workflows, workflow triggers, workflow actions, and workflow runs in the Paperless-NgX system. These models map directly to the corresponding API resources and provide a Pythonic interface for interacting with the workflow system.

Workflows in Paperless-NgX consist of triggers (conditions that start a workflow) and actions (operations performed when a trigger is activated).

class paperap.models.workflow.model.WorkflowTrigger(**data)[source]

Bases: StandardModel, MatcherMixin

Represents a workflow trigger in Paperless-NgX.

A workflow trigger defines the conditions under which a workflow will be executed. Triggers can be based on document creation, modification, scheduled events, or other system events.

sources

List of source types that can activate this trigger.

type

The type of trigger (e.g., document added, scheduled).

filter_path

Path filter for file-based triggers.

filter_filename

Filename filter for file-based triggers.

filter_mailrule

Mail rule filter for email-based triggers.

filter_has_tags

List of tag IDs that documents must have to trigger.

filter_has_correspondent

Correspondent ID that documents must have.

filter_has_document_type

Document type ID that documents must have.

schedule_date_field

Field to use for date-based scheduling.

schedule_date_custom_field

Custom field ID to use for date-based scheduling.

schedule_offset_days

Days to offset from the scheduled date.

schedule_is_recurring

Whether this trigger recurs on a schedule.

schedule_recurring_interval_days

Interval in days for recurring triggers.

Examples

>>> # Create a trigger for new documents with a specific tag
>>> trigger = WorkflowTrigger(
...     sources=["source_document"],
...     type="document_added",
...     filter_has_tags=[5]  # Tag ID 5
... )
Parameters:

data (Any)

sources: list[WorkflowTriggerSourceType]
type: WorkflowTriggerType | None
filter_path: str | None
filter_filename: str | None
filter_mailrule: str | None
filter_has_tags: list[int]
filter_has_correspondent: int | None
filter_has_document_type: int | None
schedule_date_field: ScheduleDateFieldType | None
schedule_date_custom_field: int | None
schedule_offset_days: int
schedule_is_recurring: bool
schedule_recurring_interval_days: int
class Meta(model)[source]

Bases: Meta

Metadata for the WorkflowTrigger model.

Parameters:

model (type[_Self])

queryset

alias of WorkflowTriggerQuerySet

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'filter_filename', 'filter_has_correspondent', 'filter_has_document_type', 'filter_has_tags', 'filter_mailrule', 'filter_path', 'id', 'schedule_date_custom_field', 'schedule_date_field', 'schedule_is_recurring', 'schedule_offset_days', 'schedule_recurring_interval_days', 'sources', 'type'}
read_only_fields: ClassVar[set[str]] = {'id'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:
Return type:

None

id: int
class paperap.models.workflow.model.WorkflowAction(**data)[source]

Bases: StandardModel

Represents a workflow action in Paperless-NgX.

A workflow action defines an operation to be performed when a workflow is triggered. Actions can include assigning metadata to documents, removing metadata, sending emails, or triggering webhooks.

type

The type of action to perform.

# Assignment action attributes
assign_title

Title to assign to the document.

assign_tags

List of tag IDs to assign to the document.

assign_correspondent

Correspondent ID to assign to the document.

assign_document_type

Document type ID to assign to the document.

assign_storage_path

Storage path ID to assign to the document.

assign_owner

Owner ID to assign to the document.

assign_view_users

List of user IDs to grant view permissions.

assign_view_groups

List of group IDs to grant view permissions.

assign_change_users

List of user IDs to grant change permissions.

assign_change_groups

List of group IDs to grant change permissions.

assign_custom_fields

List of custom field IDs to assign.

assign_custom_fields_values

Dictionary mapping custom field IDs to values.

# Removal action attributes
remove_all_tags

Whether to remove all tags from the document.

remove_tags

List of tag IDs to remove from the document.

remove_all_correspondents

Whether to remove all correspondents.

remove_correspondents

List of correspondent IDs to remove.

remove_all_document_types

Whether to remove all document types.

remove_document_types

List of document type IDs to remove.

remove_all_storage_paths

Whether to remove all storage paths.

remove_storage_paths

List of storage path IDs to remove.

remove_custom_fields

List of custom field IDs to remove.

remove_all_custom_fields

Whether to remove all custom fields.

remove_all_owners

Whether to remove all owners.

remove_owners

List of owner IDs to remove.

remove_all_permissions

Whether to remove all permissions.

remove_view_users

List of user IDs to remove view permissions.

remove_view_groups

List of group IDs to remove view permissions.

remove_change_users

List of user IDs to remove change permissions.

remove_change_groups

List of group IDs to remove change permissions.

# Email and webhook action attributes
email

Configuration for email actions.

webhook

Configuration for webhook actions.

Examples

>>> # Create an action to assign tags and a document type
>>> action = WorkflowAction(
...     type="assign",
...     assign_tags=[1, 2],
...     assign_document_type=5
... )
Parameters:

data (Any)

type: WorkflowActionType | None
assign_title: str | None
assign_tags: list[int]
assign_correspondent: int | None
assign_document_type: int | None
assign_storage_path: int | None
assign_owner: int | None
assign_view_users: list[int]
assign_view_groups: list[int]
assign_change_users: list[int]
assign_change_groups: list[int]
assign_custom_fields: list[int]
assign_custom_fields_values: dict[str, Any]
remove_all_tags: bool | None
remove_tags: list[int]
remove_all_correspondents: bool | None
remove_correspondents: list[int]
remove_all_document_types: bool | None
remove_document_types: list[int]
remove_all_storage_paths: bool | None
remove_storage_paths: list[int]
remove_custom_fields: list[int]
remove_all_custom_fields: bool | None
remove_all_owners: bool | None
remove_owners: list[int]
remove_all_permissions: bool | None
remove_view_users: list[int]
remove_view_groups: list[int]
remove_change_users: list[int]
remove_change_groups: list[int]
email: dict[str, Any] | None
webhook: dict[str, Any] | None
class Meta(model)[source]

Bases: Meta

Metadata for the WorkflowAction model.

Parameters:

model (type[_Self])

queryset

alias of WorkflowActionQuerySet

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'assign_change_groups', 'assign_change_users', 'assign_correspondent', 'assign_custom_fields', 'assign_custom_fields_values', 'assign_document_type', 'assign_owner', 'assign_storage_path', 'assign_tags', 'assign_title', 'assign_view_groups', 'assign_view_users', 'email', 'id', 'remove_all_correspondents', 'remove_all_custom_fields', 'remove_all_document_types', 'remove_all_owners', 'remove_all_permissions', 'remove_all_storage_paths', 'remove_all_tags', 'remove_change_groups', 'remove_change_users', 'remove_correspondents', 'remove_custom_fields', 'remove_document_types', 'remove_owners', 'remove_storage_paths', 'remove_tags', 'remove_view_groups', 'remove_view_users', 'type', 'webhook'}
read_only_fields: ClassVar[set[str]] = {'id'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:
Return type:

None

id: int
class paperap.models.workflow.model.Workflow(**data)[source]

Bases: StandardModel

Represents a workflow in Paperless-NgX.

A workflow is a combination of triggers and actions that automate document processing in Paperless-NgX. When a trigger condition is met, the associated actions are executed.

name

The name of the workflow.

order

The execution order of this workflow relative to others.

enabled

Whether this workflow is currently active.

triggers

List of trigger configurations for this workflow.

actions

List of action configurations for this workflow.

Examples

>>> # Create a simple workflow
>>> workflow = Workflow(
...     name="Tag Invoices",
...     enabled=True,
...     triggers=[{"type": "document_added", "filter_filename": "invoice"}],
...     actions=[{"type": "assign", "assign_tags": [5]}]
... )
Parameters:

data (Any)

name: str
order: int | None
enabled: bool | None
triggers: list[dict[str, Any]]
actions: list[dict[str, Any]]
class Meta(model)[source]

Bases: Meta

Metadata for the Workflow model.

Parameters:

model (type[_Self])

queryset

alias of WorkflowQuerySet

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'actions', 'enabled', 'id', 'name', 'order', 'triggers'}
read_only_fields: ClassVar[set[str]] = {'id'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:
Return type:

None

id: int
class paperap.models.workflow.model.WorkflowRun(**data)[source]

Bases: StandardModel

Represents a workflow run in Paperless-NgX.

A workflow run is a record of a specific execution of a workflow, including its status, timing information, and any errors that occurred during execution.

workflow

ID of the workflow that was executed.

document

ID of the document that triggered the workflow.

type

The type of trigger that initiated this workflow run.

run_at

The time when this workflow run was scheduled.

started

The time when this workflow run started execution.

finished

The time when this workflow run completed execution.

status

The current status of this workflow run.

error

Error message if the workflow run failed.

Examples

>>> # Check the status of a workflow run
>>> run = client.workflow_runs.get(123)
>>> if run.status == "SUCCESS":
...     print(f"Workflow completed successfully at {run.finished}")
... else:
...     print(f"Workflow failed: {run.error}")
Parameters:

data (Any)

workflow: int | None
document: int | None
type: WorkflowTriggerType | None
run_at: datetime
started: datetime | None
finished: datetime | None
status: str | None
error: str | None
class Meta(model)

Bases: Meta

Parameters:

model (type[_Self])

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'document', 'error', 'finished', 'id', 'run_at', 'started', 'status', 'type', 'workflow'}
read_only_fields: ClassVar[set[str]] = {'id'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:
Return type:

None