From 7710848a25d9e0469e916e92bc1839b1db5f2c0e Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Thu, 15 Jan 2026 19:49:46 -0800
Subject: [PATCH] Enhancement: doc_id placeholder support in workflow templates

---
 docs/usage.md                         | 1 +
 src/documents/templating/workflows.py | 3 +++
 src/documents/tests/test_workflows.py | 7 +++++--
 src/documents/workflows/actions.py    | 6 ++++++
 src/documents/workflows/mutations.py  | 3 +++
 5 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index f5c99aeaf..096a64e2b 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -597,6 +597,7 @@ The following placeholders are only available for "added" or "updated" triggers
 -   `{{created_day}}`: created day
 -   `{{created_time}}`: created time in HH:MM format
 -   `{{doc_url}}`: URL to the document in the web UI. Requires the `PAPERLESS_URL` setting to be set.
+-   `{{doc_id}}`: Document ID
 
 ##### Examples
 
diff --git a/src/documents/templating/workflows.py b/src/documents/templating/workflows.py
index 67f3ac930..66fd97e01 100644
--- a/src/documents/templating/workflows.py
+++ b/src/documents/templating/workflows.py
@@ -40,6 +40,7 @@ def parse_w_workflow_placeholders(
     created: date | None = None,
     doc_title: str | None = None,
     doc_url: str | None = None,
+    doc_id: int | None = None,
 ) -> str:
     """
     Available title placeholders for Workflows depend on what has already been assigned,
@@ -79,6 +80,8 @@ def parse_w_workflow_placeholders(
         formatting.update({"doc_title": doc_title})
     if doc_url is not None:
         formatting.update({"doc_url": doc_url})
+    if doc_id is not None:
+        formatting.update({"doc_id": str(doc_id)})
 
     logger.debug(f"Parsing Workflow Jinja template: {text}")
     try:
diff --git a/src/documents/tests/test_workflows.py b/src/documents/tests/test_workflows.py
index deb40a165..d2f843a68 100644
--- a/src/documents/tests/test_workflows.py
+++ b/src/documents/tests/test_workflows.py
@@ -3298,7 +3298,7 @@ class TestWorkflows(
         )
         webhook_action = WorkflowActionWebhook.objects.create(
             use_params=False,
-            body="Test message: {{doc_url}}",
+            body="Test message: {{doc_url}} with id {{doc_id}}",
             url="http://paperless-ngx.com",
             include_document=False,
         )
@@ -3328,7 +3328,10 @@ class TestWorkflows(
 
         mock_post.assert_called_once_with(
             url="http://paperless-ngx.com",
-            data=f"Test message: http://localhost:8000/paperless/documents/{doc.id}/",
+            data=(
+                f"Test message: http://localhost:8000/paperless/documents/{doc.id}/"
+                f" with id {doc.id}"
+            ),
             headers={},
             files=None,
             as_json=False,
diff --git a/src/documents/workflows/actions.py b/src/documents/workflows/actions.py
index 040cbc127..a61b9930e 100644
--- a/src/documents/workflows/actions.py
+++ b/src/documents/workflows/actions.py
@@ -44,6 +44,7 @@ def build_workflow_action_context(
             "current_filename": document.filename or "",
             "added": timezone.localtime(document.added),
             "created": document.created,
+            "id": document.pk,
         }
 
     correspondent_obj = (
@@ -75,6 +76,7 @@ def build_workflow_action_context(
         "current_filename": filename,
         "added": timezone.localtime(timezone.now()),
         "created": overrides.created if overrides else None,
+        "id": "",
     }
 
 
@@ -109,6 +111,7 @@ def execute_email_action(
             context["created"],
             context["title"],
             context["doc_url"],
+            context["id"],
         )
         if action.email.subject
         else ""
@@ -125,6 +128,7 @@ def execute_email_action(
             context["created"],
             context["title"],
             context["doc_url"],
+            context["id"],
         )
         if action.email.body
         else ""
@@ -203,6 +207,7 @@ def execute_webhook_action(
                             context["created"],
                             context["title"],
                             context["doc_url"],
+                            context["id"],
                         )
                 except Exception as e:
                     logger.error(
@@ -221,6 +226,7 @@ def execute_webhook_action(
                 context["created"],
                 context["title"],
                 context["doc_url"],
+                context["id"],
             )
         headers = {}
         if action.webhook.headers:
diff --git a/src/documents/workflows/mutations.py b/src/documents/workflows/mutations.py
index ef85dba0f..b93a26781 100644
--- a/src/documents/workflows/mutations.py
+++ b/src/documents/workflows/mutations.py
@@ -55,6 +55,9 @@ def apply_assignment_to_document(
                 document.original_filename or "",
                 document.filename or "",
                 document.created,
+                "",  # dont pass the title to avoid recursion
+                "",  # no urls in titles
+                document.pk,
             )
         except Exception:  # pragma: no cover
             logger.exception(