feat: add triggering stage option and workflow-scoped notification rules

- Add use_triggering_stage boolean to NotificationRule that auto-scopes
  stage-based recipients to the triggering task's stage at runtime
- Scope notification rule dispatch to the specific workflow owning the
  triggering task instead of firing rules from all workflows on the form
- Add model validation: use_triggering_stage and explicit stage FK are
  mutually exclusive
- Update admin fieldsets to expose use_triggering_stage
- Add migration 0087
- Bump version to 0.61.0

Author: matteius

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.61.0] - 2026-04-02
+
+### Added
+- **Triggering Stage option** for notification rules — new `use_triggering_stage` boolean
+  auto-scopes the rule to whichever stage fired the event at runtime, eliminating
+  the need to create a separate rule per stage.
+- **Workflow-scoped notification rules** — when a notification event is associated with
+  a specific task, rules are now filtered to only the task's workflow instead of firing
+  rules from every workflow attached to the form definition.
+- Migration `0087`.
+
 ## [0.60.0] - 2026-04-02
 
 ### Added

django_forms_workflows/admin.py

@@ -516,7 +516,7 @@ class NotificationRuleInline(nested_admin.NestedStackedInline):
             None,
             {
                 "fields": (
-                    ("event", "stage"),
+                    ("event", "stage", "use_triggering_stage"),
                     (
                         "notify_submitter",
                         "notify_stage_assignees",
@@ -1736,7 +1736,7 @@ class NotificationRuleAdmin(admin.ModelAdmin):
             {
                 "fields": (
                     "workflow",
-                    ("event", "stage"),
+                    ("event", "stage", "use_triggering_stage"),
                     (
                         "notify_submitter",
                         "notify_stage_assignees",

django_forms_workflows/migrations/0087_notificationrule_use_triggering_stage.py

@@ -0,0 +1,45 @@
+# Generated by Django 5.2.7 on 2026-04-02
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0086_add_embed_enabled"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="notificationrule",
+            name="use_triggering_stage",
+            field=models.BooleanField(
+                default=False,
+                help_text=(
+                    "When checked, automatically scopes this rule to whichever "
+                    "stage triggered the event at runtime. This avoids needing "
+                    "to create a separate rule per stage. Overrides the Stage "
+                    "dropdown above."
+                ),
+            ),
+        ),
+        migrations.AlterField(
+            model_name="notificationrule",
+            name="stage",
+            field=models.ForeignKey(
+                blank=True,
+                help_text=(
+                    "Optional. When set, scopes this rule to a specific stage. "
+                    "Recipient sources like 'Notify stage assignees' and "
+                    "'Notify stage groups' will reference only this stage. "
+                    "When blank, they reference all stages in the workflow. "
+                    "Ignored when 'Use triggering stage' is checked."
+                ),
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="notification_rules",
+                to="django_forms_workflows.workflowstage",
+            ),
+        ),
+    ]

django_forms_workflows/models.py

@@ -1318,7 +1318,17 @@ class NotificationRule(models.Model):
             "Optional. When set, scopes this rule to a specific stage. "
             "Recipient sources like 'Notify stage assignees' and "
             "'Notify stage groups' will reference only this stage. "
-            "When blank, they reference all stages in the workflow."
+            "When blank, they reference all stages in the workflow. "
+            "Ignored when 'Use triggering stage' is checked."
+        ),
+    )
+    use_triggering_stage = models.BooleanField(
+        default=False,
+        help_text=(
+            "When checked, automatically scopes this rule to whichever "
+            "stage triggered the event at runtime. This avoids needing "
+            "to create a separate rule per stage. Overrides the Stage "
+            "dropdown above."
         ),
     )
     event = models.CharField(
@@ -1401,6 +1411,12 @@ class Meta:
     def clean(self):
         from django.core.exceptions import ValidationError
 
+        if self.use_triggering_stage and self.stage_id:
+            raise ValidationError(
+                "'Use triggering stage' and a specific 'Stage' are mutually "
+                "exclusive. Either pick a stage or check 'Use triggering stage'."
+            )
+
         has_recipients = (
             self.notify_submitter
             or self.email_field
@@ -1429,7 +1445,12 @@ def __str__(self) -> str:
         if self.notify_stage_groups:
             parts.append("stage-groups")
         target = ", ".join(parts) if parts else "groups"
-        stage_label = f" [{self.stage.name}]" if self.stage_id else ""
+        if self.use_triggering_stage:
+            stage_label = " [triggering stage]"
+        elif self.stage_id:
+            stage_label = f" [{self.stage.name}]"
+        else:
+            stage_label = ""
         return f"{self.get_event_display()}{stage_label} → {target}"
 
 

django_forms_workflows/tasks.py

@@ -971,7 +971,7 @@ def _get_form_field_email(form_data: dict, email_field: str) -> str | None:
 
 
 def _collect_notification_recipients(
-    notif, form_data: dict, submission=None
+    notif, form_data: dict, submission=None, task=None
 ) -> list[str]:
     """Return the deduplicated list of recipient emails for a notification rule.
 
@@ -983,6 +983,10 @@ def _collect_notification_recipients(
     4. notify_stage_assignees → ApprovalTask.assigned_to.email
     5. notify_stage_groups    → all users in the stage's approval groups
     6. notify_groups (M2M)    → all users in explicitly-listed groups
+
+    When ``use_triggering_stage`` is True and a *task* is provided, the
+    task's ``workflow_stage`` is used to scope stage-based recipients
+    instead of ``notif.stage``.
     """
     recipients: list[str] = []
 
@@ -1004,6 +1008,18 @@ def _add(email: str | None) -> None:
         if addr and "@" in addr:
             _add(addr)
 
+    # Resolve the effective stage for stage-scoped recipient sources.
+    # Priority: use_triggering_stage (from task) > explicit stage FK > all stages.
+    _triggering_stage_id = None
+    if getattr(notif, "use_triggering_stage", False) and task is not None:
+        _triggering_stage_id = getattr(task, "workflow_stage_id", None)
+
+    def _effective_stage_id():
+        """Return the stage ID to scope to, or None for all stages."""
+        if _triggering_stage_id:
+            return _triggering_stage_id
+        return getattr(notif, "stage_id", None)
+
     # 4. Stage assignees (NotificationRule only)
     if getattr(notif, "notify_stage_assignees", False) and submission is not None:
         qs = (
@@ -1012,9 +1028,9 @@ def _add(email: str | None) -> None:
             .exclude(workflow_stage__assignee_form_field__isnull=True)
             .exclude(workflow_stage__assignee_form_field="")
         )
-        # If rule is stage-scoped, limit to that stage
-        if getattr(notif, "stage_id", None):
-            qs = qs.filter(workflow_stage_id=notif.stage_id)
+        eff_stage = _effective_stage_id()
+        if eff_stage:
+            qs = qs.filter(workflow_stage_id=eff_stage)
         for email in qs.values_list("assigned_to__email", flat=True):
             _add(email)
 
@@ -1023,9 +1039,9 @@ def _add(email: str | None) -> None:
         from django.contrib.auth import get_user_model
 
         user_model = get_user_model()
-        # Determine which stages to include
-        if getattr(notif, "stage_id", None):
-            stage_ids = [notif.stage_id]
+        eff_stage = _effective_stage_id()
+        if eff_stage:
+            stage_ids = [eff_stage]
         else:
             # All stages in this workflow
             from .models import WorkflowStage
@@ -1152,15 +1168,29 @@ def send_notification_rules(
     workflow = getattr(submission.form_definition, "workflow", None)
     hide_approval_history = bool(getattr(workflow, "hide_approval_history", False))
 
-    rules = (
-        NotificationRule.objects.filter(
-            workflow__form_definition=submission.form_definition,
-            event=event,
-        )
+    # Resolve the task (if any) to scope rules to its workflow
+    task = None
+    if task_id:
+        try:
+            task = ApprovalTask.objects.select_related("workflow_stage").get(id=task_id)
+        except ApprovalTask.DoesNotExist:
+            pass
+
+    rules_qs = (
+        NotificationRule.objects.filter(event=event)
         .select_related("workflow", "stage")
         .prefetch_related("notify_groups")
     )
 
+    # Scope rules to the specific workflow that owns the triggering task,
+    # rather than firing rules from every workflow on the form.
+    if task and getattr(task, "workflow_stage_id", None):
+        rules_qs = rules_qs.filter(workflow_id=task.workflow_stage.workflow_id)
+    else:
+        rules_qs = rules_qs.filter(workflow__form_definition=submission.form_definition)
+
+    rules = rules_qs
+
     default_subject_tpl = _EVENT_DEFAULT_SUBJECTS.get(
         event, "{form_name} (ID {submission_id})"
     )
@@ -1190,7 +1220,7 @@ def send_notification_rules(
 
         # Resolve recipients
         recipients = _collect_notification_recipients(
-            rule, form_data, submission=submission
+            rule, form_data, submission=submission, task=task
         )
         if not recipients:
             logger.info(

pyproject.toml

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