feat: add notify_assignee_on_final_decision flag to WorkflowStage

Add a per-stage boolean that controls whether dynamically-assigned
approvers (resolved via assignee_form_field) are included as recipients
on final approval/rejection notifications. Defaults to False, making
this opt-in per stage rather than the previous unconditional inclusion.

- New field on WorkflowStage model with migration 0073
- Gate dynamic assignee email collection in _collect_notification_recipients
- Add field to both inline and standalone WorkflowStage admin
- Update existing test to set the flag explicitly

Author: matteius

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-03-31
+
+### Added
+- **Stage-level `notify_assignee_on_final_decision` flag** — New boolean field on `WorkflowStage` that controls whether a stage's dynamically-assigned approver (resolved via `assignee_form_field`) is included as a recipient on final approval/rejection notifications. Defaults to `False`, making dynamic assignee notification opt-in per stage rather than the previous unconditional inclusion. This gives administrators granular control over which stage assignees receive final decision emails.
+
 ## [0.38.6] - 2026-03-30
 
 ### Fixed

django_forms_workflows/admin.py

@@ -471,7 +471,7 @@ class WorkflowStageInline(nested_admin.NestedStackedInline):
         "approve_label",
         "requires_manager_approval",
         ("assignee_form_field", "assignee_lookup_type"),
-        "validate_assignee_group",
+        ("validate_assignee_group", "notify_assignee_on_final_decision"),
         ("allow_reassign", "allow_send_back"),
         "allow_edit_form_data",
         "trigger_conditions",
@@ -1430,6 +1430,7 @@ class WorkflowStageAdmin(nested_admin.NestedModelAdmin):
                     "assignee_form_field",
                     "assignee_lookup_type",
                     "validate_assignee_group",
+                    "notify_assignee_on_final_decision",
                     "allow_reassign",
                     "allow_send_back",
                 ),

django_forms_workflows/migrations/0073_add_stage_notify_assignee_on_final_decision.py

@@ -0,0 +1,21 @@
+# Generated by Django 6.0.3 on 2026-03-31 13:30
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0072_add_change_history"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="workflowstage",
+            name="notify_assignee_on_final_decision",
+            field=models.BooleanField(
+                default=False,
+                help_text="Include this stage's dynamically-assigned approver as a recipient on final approval/rejection notifications. Only effective when assignee_form_field is set and a user was successfully resolved.",
+            ),
+        ),
+    ]

django_forms_workflows/models.py

@@ -880,6 +880,14 @@ class WorkflowStage(models.Model):
             "for sites where SSO does not populate first/last name."
         ),
     )
+    notify_assignee_on_final_decision = models.BooleanField(
+        default=False,
+        help_text=(
+            "Include this stage's dynamically-assigned approver as a recipient "
+            "on final approval/rejection notifications. Only effective when "
+            "assignee_form_field is set and a user was successfully resolved."
+        ),
+    )
     allow_send_back = models.BooleanField(
         default=False,
         help_text=(
@@ -1070,11 +1078,14 @@ class WorkflowNotification(models.Model):
     Recipients are the union of:
 
     * ``notify_submitter`` — if True, the person who submitted the form is always included.
+    * ``notify_assignees`` — if True, all dynamically-assigned workflow approvers
+      (resolved via ``assignee_form_field`` on any stage) are included.
+      Only effective for approval and rejection notifications.
     * ``email_field`` — slug of the form field whose value is the recipient email
       (resolved from ``form_data`` at send time, varies per submission).
     * ``static_emails`` — comma-separated fixed addresses always included.
 
-    At least one of the three must be set.
+    At least one of the four must be set.
 
     ``conditions`` (same JSON format as ``WorkflowStage.trigger_conditions``)
     are evaluated against ``form_data`` before sending; leave blank to always send.
@@ -1155,18 +1166,21 @@ def clean(self):
 
         if (
             not self.notify_submitter
+            and not self.notify_assignees
             and not self.email_field
             and not self.static_emails
         ):
             raise ValidationError(
                 "At least one recipient source must be set: "
-                "'Notify submitter', 'Email field', or 'Static emails'."
+                "'Notify submitter', 'Notify assignees', 'Email field', or 'Static emails'."
             )
 
     def __str__(self) -> str:
         parts = []
         if self.notify_submitter:
             parts.append("submitter")
+        if self.notify_assignees:
+            parts.append("assignees")
         if self.email_field:
             parts.append(f"field:{self.email_field}")
         if self.static_emails:

django_forms_workflows/tasks.py

@@ -788,6 +788,7 @@ def _collect_notification_recipients(
             .filter(assigned_to__isnull=False)
             .exclude(workflow_stage__assignee_form_field__isnull=True)
             .exclude(workflow_stage__assignee_form_field="")
+            .filter(workflow_stage__notify_assignee_on_final_decision=True)
             .values_list("assigned_to__email", flat=True)
         )
         for email in dynamic_assignee_emails:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-forms-workflows"
-version = "0.41.1"
+version = "0.42.0"
 description = "Enterprise-grade, database-driven form builder with approval workflows and external data integration"
 license = "LGPL-3.0-only"
 readme = "README.md"

tests/test_notifications.py

@@ -37,6 +37,7 @@ def test_final_decision_notifications_include_dynamic_assignee(
         approval_logic="all",
         assignee_form_field="advisor_email",
         assignee_lookup_type="email",
+        notify_assignee_on_final_decision=True,
     )
     WorkflowNotification.objects.create(
         workflow=workflow,