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.
- 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.
- 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.
- 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].