Feature: manual workflow trigger (#14704)

src/documents/tests/test_api_bulk_edit.py

@@ -15,7 +15,11 @@ from documents.models import Document
 from documents.models import DocumentType
 from documents.models import StoragePath
 from documents.models import Tag
+from documents.models import Workflow
+from documents.models import WorkflowAction
+from documents.models import WorkflowTrigger
 from paperless_testing.dirs import DirectoriesMixin
+from paperless_testing.factories import DocumentFactory
 from paperless_testing.factories import UserFactory
 from paperless_testing.permissions import grant_all_global
 from paperless_testing.permissions import grant_global
@@ -622,6 +626,111 @@ class TestBulkEditAPI(DirectoriesMixin, APITestCase):
         self.assertEqual(args[0], [self.doc1.id])
         self.assertEqual(kwargs, {"remote_ocr": True})
 
+    def _make_manual_workflow(self) -> Workflow:
+        trigger = WorkflowTrigger.objects.create(
+            type=WorkflowTrigger.WorkflowTriggerType.MANUAL,
+        )
+        action = WorkflowAction.objects.create()
+        workflow = Workflow.objects.create(name="Manual workflow", order=0)
+        workflow.triggers.add(trigger)
+        workflow.actions.add(action)
+        return workflow
+
+    def _run_workflow(self, parameters, documents=None):
+        return self.client.post(
+            "/api/documents/bulk_edit/",
+            json.dumps(
+                {
+                    "documents": documents or [self.doc1.id],
+                    "method": "run_workflow",
+                    "parameters": parameters,
+                },
+            ),
+            content_type="application/json",
+        )
+
+    @mock.patch("documents.views.bulk_edit.run_workflow")
+    def test_run_workflow(self, m) -> None:
+        """A valid run_workflow call passes the docs, workflow id and filter flag through."""
+        self.setup_mock(m, "run_workflow")
+        workflow = self._make_manual_workflow()
+
+        response = self._run_workflow({"workflow": workflow.id})
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        args, kwargs = m.call_args
+        self.assertEqual(args[0], [self.doc1.id])
+        self.assertEqual(kwargs, {"workflow": workflow.id, "filter_documents": True})
+
+        self._run_workflow({"workflow": workflow.id, "filter_documents": False})
+        self.assertFalse(m.call_args.kwargs["filter_documents"])
+
+    @mock.patch("documents.views.bulk_edit.run_workflow")
+    def test_run_workflow_invalid_parameters(self, m) -> None:
+        """Invalid run_workflow parameters are rejected before dispatch."""
+        self.setup_mock(m, "run_workflow")
+        manual = self._make_manual_workflow()
+        non_manual = Workflow.objects.create(name="Non-manual", order=0)
+        non_manual.triggers.add(
+            WorkflowTrigger.objects.create(
+                type=WorkflowTrigger.WorkflowTriggerType.DOCUMENT_ADDED,
+            ),
+        )
+        disabled = Workflow.objects.create(
+            name="Disabled manual",
+            order=0,
+            enabled=False,
+        )
+        disabled.triggers.add(
+            WorkflowTrigger.objects.create(
+                type=WorkflowTrigger.WorkflowTriggerType.MANUAL,
+            ),
+        )
+        for label, parameters in (
+            ("missing workflow", {}),
+            ("nonexistent workflow", {"workflow": 9999}),
+            ("no manual trigger", {"workflow": non_manual.id}),
+            ("disabled workflow", {"workflow": disabled.id}),
+            ("non-bool filter", {"workflow": manual.id, "filter_documents": "nope"}),
+        ):
+            with self.subTest(label):
+                response = self._run_workflow(parameters)
+                self.assertEqual(
+                    response.status_code,
+                    status.HTTP_400_BAD_REQUEST,
+                )
+        m.assert_not_called()
+
+    @mock.patch("documents.views.bulk_edit.run_workflow")
+    def test_run_workflow_requires_ownership(self, m) -> None:
+        """A non-owner without document ownership is forbidden (actions mutate docs)."""
+        self.setup_mock(m, "run_workflow")
+        user = UserFactory(username="no_perms")
+        grant_all_global(user)
+        doc = DocumentFactory(owner=UserFactory(username="other"))
+        workflow = self._make_manual_workflow()
+        self.client.force_authenticate(user=user)
+
+        response = self._run_workflow({"workflow": workflow.id}, documents=[doc.id])
+
+        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+        m.assert_not_called()
+
+    @mock.patch("documents.views.bulk_edit.run_workflow")
+    def test_run_workflow_requires_workflow_permission(self, m) -> None:
+        """Owning the documents is not enough without view_workflow permission."""
+        self.setup_mock(m, "run_workflow")
+        user = UserFactory(username="no_wf_perms")
+        grant_global(user, "change_document")
+        doc = DocumentFactory(owner=user)
+        workflow = self._make_manual_workflow()
+        self.client.force_authenticate(user=user)
+
+        response = self._run_workflow({"workflow": workflow.id}, documents=[doc.id])
+
+        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+        m.assert_not_called()
+
     @mock.patch("documents.serialisers.bulk_edit.set_storage_path")
     def test_api_set_storage_path(self, m) -> None:
         """

src/documents/tests/test_api_workflows.py

@@ -100,6 +100,47 @@ class TestApiWorkflows(DirectoriesMixin, APITestCase):
             self.action.assign_correspondent.pk,
         )
 
+    def test_api_get_workflows_filter_trigger_type(self) -> None:
+        """
+        GIVEN:
+            - A consumption workflow and a manual workflow
+        WHEN:
+            - Workflows are requested filtered by trigger_type
+        THEN:
+            - Only workflows with a matching trigger are returned
+        """
+        manual_trigger = WorkflowTrigger.objects.create(
+            type=WorkflowTrigger.WorkflowTriggerType.MANUAL,
+        )
+        manual_workflow = Workflow.objects.create(name="Manual", order=1)
+        manual_workflow.triggers.add(manual_trigger)
+
+        response = self.client.get(
+            f"{self.ENDPOINT}?trigger_type={WorkflowTrigger.WorkflowTriggerType.MANUAL}",
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["count"], 1)
+        self.assertEqual(response.data["results"][0]["id"], manual_workflow.id)
+
+    def test_api_get_workflows_filter_enabled(self) -> None:
+        """
+        GIVEN:
+            - An enabled workflow and a disabled workflow
+        WHEN:
+            - Workflows are requested filtered by enabled
+        THEN:
+            - Only enabled workflows are returned
+        """
+        Workflow.objects.create(name="Disabled", order=1, enabled=False)
+
+        response = self.client.get(f"{self.ENDPOINT}?enabled=true", format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["count"], 1)
+        self.assertEqual(response.data["results"][0]["id"], self.workflow.id)
+
     def test_api_get_workflow_actions_ordered(self) -> None:
         """
         GIVEN:

src/documents/tests/test_workflows.py

@@ -2288,6 +2288,83 @@ class TestWorkflows(
         doc.refresh_from_db()
         self.assertEqual(doc.owner, self.user2)
 
+    def _make_manual_workflow(self, *, require_tag: Tag | None = None) -> Workflow:
+        trigger = WorkflowTrigger.objects.create(
+            type=WorkflowTrigger.WorkflowTriggerType.MANUAL,
+        )
+        if require_tag is not None:
+            trigger.filter_has_all_tags.add(require_tag)
+        action = WorkflowAction.objects.create(assign_owner=self.user2)
+        workflow = Workflow.objects.create(name="Manual workflow", order=0)
+        workflow.triggers.add(trigger)
+        workflow.actions.add(action)
+        return workflow
+
+    @mock.patch("documents.tasks.send_websocket_document_updated")
+    def test_manual_workflow_run_applies_and_notifies(self, mock_ws) -> None:
+        """A manual run applies the workflow's actions and pushes a websocket update."""
+        workflow = self._make_manual_workflow()
+        doc = DocumentFactory()
+
+        tasks.run_workflows_for_documents([doc.pk], workflow.pk)
+
+        doc.refresh_from_db()
+        self.assertEqual(doc.owner, self.user2)
+        self.assertEqual(mock_ws.call_args.kwargs["document"].pk, doc.pk)
+
+    def test_manual_workflow_run_respects_filters(self) -> None:
+        """With filter_documents=True, a document failing the trigger filters is skipped."""
+        workflow = self._make_manual_workflow(require_tag=self.t1)
+        doc = DocumentFactory()
+
+        tasks.run_workflows_for_documents([doc.pk], workflow.pk, filter_documents=True)
+
+        doc.refresh_from_db()
+        self.assertIsNone(doc.owner)
+
+    def test_manual_workflow_run_force_ignores_filters(self) -> None:
+        """With filter_documents=False, actions run regardless of the trigger filters."""
+        workflow = self._make_manual_workflow(require_tag=self.t1)
+        doc = DocumentFactory()
+
+        tasks.run_workflows_for_documents([doc.pk], workflow.pk, filter_documents=False)
+
+        doc.refresh_from_db()
+        self.assertEqual(doc.owner, self.user2)
+
+    def test_manual_workflow_run_missing_workflow(self) -> None:
+        """A missing workflow id logs a warning rather than raising."""
+        doc = DocumentFactory()
+        with self.assertLogs("paperless.tasks", level="WARNING"):
+            tasks.run_workflows_for_documents([doc.pk], 9999)
+
+    @mock.patch("documents.tasks.send_websocket_document_updated")
+    @mock.patch("documents.tasks.run_workflows")
+    def test_manual_workflow_run_continues_after_error(
+        self,
+        mock_run_workflows,
+        mock_ws,
+    ) -> None:
+        """A failure on one document does not abort the run for the others."""
+        workflow = self._make_manual_workflow()
+        doc1 = DocumentFactory()
+        doc2 = DocumentFactory()
+
+        def side_effect(*args, document, **kwargs):
+            if document.pk == doc1.pk:
+                raise Exception("boom")
+
+        mock_run_workflows.side_effect = side_effect
+
+        with self.assertLogs("paperless.tasks", level="ERROR"):
+            tasks.run_workflows_for_documents([doc1.pk, doc2.pk], workflow.pk)
+
+        # Both documents were attempted; the websocket update only fired for the
+        # one that did not raise.
+        self.assertEqual(mock_run_workflows.call_count, 2)
+        ws_doc_ids = [c.kwargs["document"].pk for c in mock_ws.call_args_list]
+        self.assertEqual(ws_doc_ids, [doc2.pk])
+
     @mock.patch("documents.tasks.send_websocket_document_updated")
     def test_workflow_scheduled_trigger_sends_websocket_update(
         self,