django-forms-workflows 0.42.2__tar.gz → 0.44.0__tar.gz

{django_forms_workflows-0.42.2 → django_forms_workflows-0.44.0}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.44.0] - 2026-03-31
+
+### Added
+- **Standalone `NotificationRuleAdmin`** — Full admin interface for NotificationRule with list display, filters, search, and fieldsets. Supports browsing notification rules across all workflows.
+
+### Changed
+- **Unified batching in `send_notification_rules`** — Cadence-aware dispatch now lives inside the unified task. Removed legacy `_queue_workflow_level_notifications` and `_queue_approval_request_notifications` functions. All batching (immediate, daily, weekly, monthly, form_field_date) flows through a single code path.
+- **Simplified `_notify_task_request`** — No longer has its own batching logic; delegates entirely to `_dispatch_notification_rules` + built-in `send_approval_request`.
+
+### Removed
+- **Legacy notification models** — Dropped `WorkflowNotification`, `StageFormFieldNotification`, and `WorkflowStage.notify_assignee_on_final_decision`. All configuration now uses `NotificationRule` exclusively. Legacy task stubs retained for in-flight Celery message compatibility.
+- **Legacy notification functions** — Removed `send_workflow_definition_notifications`, `send_stage_form_field_notifications`, `send_submission_form_field_notifications` implementations (stubs remain as no-ops for Celery compat).
+
+### Fixed
+- **Signature field border visibility** — Changed signature pad canvas border from `#dee2e6` (nearly invisible light gray) to `#adb5bd` (clearly visible medium gray) so users can see the signature area boundary.
+
+## [0.43.0] - 2026-03-31
+
+### Added
+- **Unified `NotificationRule` model** — Replaces `WorkflowNotification`, `StageFormFieldNotification`, and `WorkflowStage.notify_assignee_on_final_decision` with a single, generic model. All six recipient sources (submitter, email field, static emails, stage assignees, stage groups, arbitrary groups) are available on every event type, letting admins configure any combination they need.
+- **New event types** — `stage_decision` (fires when an individual stage completes), `workflow_approved`, `workflow_denied`, `form_withdrawn` replace the legacy `approval_notification`, `rejection_notification`, `withdrawal_notification` names.
+- **Group notifications** — `notify_stage_groups` includes all users in a stage's approval groups; `notify_groups` M2M allows notifying arbitrary Django groups independent of stage assignment.
+- **Stage-scoped vs. workflow-scoped rules** — Setting the optional `stage` FK scopes `notify_stage_assignees` and `notify_stage_groups` to a specific stage. Leaving it null includes all stages.
+- **Unified `send_notification_rules` Celery task** — Single dispatch entry point for all `NotificationRule` records, with full conditions evaluation, recipient resolution, and template rendering.
+- **Data migration `0075`** — Automatically migrates all existing `WorkflowNotification`, `StageFormFieldNotification`, and `notify_assignee_on_final_decision` records into `NotificationRule`.
+- **Comprehensive notification documentation** — `docs/NOTIFICATIONS.md` with architecture overview, model reference, 10 configuration scenarios, troubleshooting guide, and migration notes.
+
+### Changed
+- **Legacy models retained** — `WorkflowNotification` and `StageFormFieldNotification` remain for backward compatibility. The workflow engine dispatches both legacy and unified paths in parallel. Legacy models will be removed in a future release.
+- **Updated `PendingNotification` and `NotificationLog` event types** — Both models now include the new event names alongside legacy names for historical records.
+
 ## [0.42.2] - 2026-03-31
 
 ### Fixed

{django_forms_workflows-0.42.2 → django_forms_workflows-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-forms-workflows
-Version: 0.42.2
+Version: 0.44.0
 Summary: Enterprise-grade, database-driven form builder with approval workflows and external data integration
 License: LGPL-3.0-only
 License-File: LICENSE

{django_forms_workflows-0.42.2 → django_forms_workflows-0.44.0}/django_forms_workflows/admin.py

@@ -34,15 +34,14 @@ from .models import (
     LDAPGroupProfile,
     ManagedFile,
     NotificationLog,
+    NotificationRule,
     PostSubmissionAction,
     PrefillSource,
     StageApprovalGroup,
-    StageFormFieldNotification,
     SubWorkflowDefinition,
     SubWorkflowInstance,
     UserProfile,
     WorkflowDefinition,
-    WorkflowNotification,
     WorkflowStage,
 )
 
@@ -443,59 +442,49 @@ class StageApprovalGroupInline(nested_admin.NestedTabularInline):
     autocomplete_fields = ("group",)
 
 
-class StageFormFieldNotificationInline(nested_admin.NestedTabularInline):
-    """Inline for configuring stage-level notifications (static and/or form-field driven)."""
-
-    model = StageFormFieldNotification
-    extra = 0
-    fields = (
-        "notification_type",
-        "email_field",
-        "static_emails",
-        "subject_template",
-        "conditions",
-    )
-
-
 class WorkflowStageInline(nested_admin.NestedStackedInline):
     """Inline for defining ordered stages on a WorkflowDefinition."""
 
     model = WorkflowStage
     extra = 0
     ordering = ("order",)
-    inlines = [StageApprovalGroupInline, StageFormFieldNotificationInline]
+    inlines = [StageApprovalGroupInline]
     fields = (
         ("order", "name"),
         "approval_logic",
         "approve_label",
         "requires_manager_approval",
         ("assignee_form_field", "assignee_lookup_type"),
-        ("validate_assignee_group", "notify_assignee_on_final_decision"),
+        "validate_assignee_group",
         ("allow_reassign", "allow_send_back"),
         "allow_edit_form_data",
         "trigger_conditions",
     )
 
 
-class WorkflowNotificationInline(nested_admin.NestedStackedInline):
-    """Inline for configuring granular workflow-level notification rules.
+class NotificationRuleInline(nested_admin.NestedStackedInline):
+    """Unified notification rule inline.
 
-    Each rule fires at a workflow-conclusion event (submission received, final
-    approval, final rejection, or withdrawal) and can target dynamic recipients
-    (from a form field) and/or static addresses, with optional conditions.
-
-    Use one row per distinct recipient group / event combination.
+    Replaces WorkflowNotificationInline and StageFormFieldNotificationInline
+    with a single, generic inline that supports all event types and all
+    recipient sources.
     """
 
-    model = WorkflowNotification
+    model = NotificationRule
     extra = 0
     fieldsets = (
         (
             None,
             {
                 "fields": (
-                    ("notification_type", "notify_submitter"),
+                    ("event", "stage"),
+                    (
+                        "notify_submitter",
+                        "notify_stage_assignees",
+                        "notify_stage_groups",
+                    ),
                     ("email_field", "static_emails"),
+                    "notify_groups",
                     "subject_template",
                 )
             },
@@ -521,7 +510,7 @@ class WorkflowDefinitionInline(nested_admin.NestedStackedInline):
 
     model = WorkflowDefinition
     extra = 0
-    inlines = [WorkflowStageInline, WorkflowNotificationInline]
+    inlines = [WorkflowStageInline, NotificationRuleInline]
     fields = [
         "name_label",
         "requires_approval",
@@ -1398,7 +1387,6 @@ class WorkflowStageAdmin(nested_admin.NestedModelAdmin):
     ordering = ("workflow", "order")
     inlines = [
         StageApprovalGroupInline,
-        StageFormFieldNotificationInline,
         ChangeHistoryInline,
     ]
     fieldsets = (
@@ -1429,7 +1417,6 @@ class WorkflowStageAdmin(nested_admin.NestedModelAdmin):
                     "assignee_form_field",
                     "assignee_lookup_type",
                     "validate_assignee_group",
-                    "notify_assignee_on_final_decision",
                     "allow_reassign",
                     "allow_send_back",
                 ),
@@ -1466,7 +1453,11 @@ class WorkflowStageAdmin(nested_admin.NestedModelAdmin):
 
 @admin.register(WorkflowDefinition)
 class WorkflowDefinitionAdmin(nested_admin.NestedModelAdmin):
-    inlines = [WorkflowStageInline, WorkflowNotificationInline, ChangeHistoryInline]
+    inlines = [
+        WorkflowStageInline,
+        NotificationRuleInline,
+        ChangeHistoryInline,
+    ]
     list_display = (
         "form_definition",
         "requires_approval",
@@ -1549,23 +1540,32 @@ class WorkflowDefinitionAdmin(nested_admin.NestedModelAdmin):
         )
 
 
-@admin.register(WorkflowNotification)
-class WorkflowNotificationAdmin(admin.ModelAdmin):
-    """Standalone admin for WorkflowNotification — searchable across all workflows."""
+@admin.register(NotificationRule)
+class NotificationRuleAdmin(admin.ModelAdmin):
+    """Standalone admin for NotificationRule — searchable across all workflows."""
 
     list_display = (
         "workflow_form",
-        "notification_type",
+        "event",
+        "stage_name",
         "notify_submitter",
+        "notify_stage_assignees",
+        "notify_stage_groups",
         "email_field",
         "static_emails_truncated",
         "has_conditions",
-        "subject_template_truncated",
     )
-    list_filter = ("notification_type", "notify_submitter", "workflow__form_definition")
-    list_select_related = ("workflow__form_definition",)
+    list_filter = (
+        "event",
+        "notify_submitter",
+        "notify_stage_assignees",
+        "notify_stage_groups",
+        "workflow__form_definition",
+    )
+    list_select_related = ("workflow__form_definition", "stage")
     search_fields = (
         "workflow__form_definition__name",
+        "stage__name",
         "email_field",
         "static_emails",
     )
@@ -1576,8 +1576,14 @@ class WorkflowNotificationAdmin(admin.ModelAdmin):
             {
                 "fields": (
                     "workflow",
-                    ("notification_type", "notify_submitter"),
+                    ("event", "stage"),
+                    (
+                        "notify_submitter",
+                        "notify_stage_assignees",
+                        "notify_stage_groups",
+                    ),
                     ("email_field", "static_emails"),
+                    "notify_groups",
                     "subject_template",
                 )
             },
@@ -1601,6 +1607,10 @@ class WorkflowNotificationAdmin(admin.ModelAdmin):
     def workflow_form(self, obj):
         return obj.workflow.form_definition.name if obj.workflow_id else "—"
 
+    @admin.display(description="Stage", ordering="stage__name")
+    def stage_name(self, obj):
+        return obj.stage.name if obj.stage_id else "— (all stages)"
+
     @admin.display(description="Static emails")
     def static_emails_truncated(self, obj):
         if not obj.static_emails:
@@ -1611,14 +1621,6 @@ class WorkflowNotificationAdmin(admin.ModelAdmin):
     def has_conditions(self, obj):
         return bool(obj.conditions)
 
-    @admin.display(description="Subject template")
-    def subject_template_truncated(self, obj):
-        if not obj.subject_template:
-            return "—"
-        return obj.subject_template[:50] + (
-            "…" if len(obj.subject_template) > 50 else ""
-        )
-
 
 @admin.register(PostSubmissionAction)
 class PostSubmissionActionAdmin(admin.ModelAdmin):

{django_forms_workflows-0.42.2 → django_forms_workflows-0.44.0}/django_forms_workflows/diff_views.py

@@ -92,8 +92,12 @@ def _build_summary(forms_data):
                         diffs.append(
                             f"Stage '{key[1]}' {sk}: {bs.get(sk)!r} → {os_.get(sk)!r}"
                         )
-                b_notifs = bs.get("form_field_notifications", [])
-                o_notifs = os_.get("form_field_notifications", [])
+                b_notifs = bs.get(
+                    "notification_rules", bs.get("form_field_notifications", [])
+                )
+                o_notifs = os_.get(
+                    "notification_rules", os_.get("form_field_notifications", [])
+                )
                 if len(b_notifs) != len(o_notifs):
                     diffs.append(
                         f"Stage '{key[1]}' notifications: {len(b_notifs)} → {len(o_notifs)}"

django_forms_workflows-0.44.0/django_forms_workflows/migrations/0074_add_notification_rule.py

@@ -0,0 +1,136 @@
+# Generated by Django 6.0.3 on 2026-03-31 16:14
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("auth", "0012_alter_user_first_name_max_length"),
+        ("django_forms_workflows", "0073_add_stage_notify_assignee_on_final_decision"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="NotificationRule",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "event",
+                    models.CharField(
+                        choices=[
+                            ("submission_received", "Submission Received"),
+                            ("approval_request", "Approval Request (stage activated)"),
+                            (
+                                "stage_decision",
+                                "Stage Decision (individual stage completed)",
+                            ),
+                            ("workflow_approved", "Workflow Approved (final decision)"),
+                            ("workflow_denied", "Workflow Denied (final decision)"),
+                            ("form_withdrawn", "Form Withdrawn"),
+                        ],
+                        help_text="The workflow event that triggers this notification.",
+                        max_length=30,
+                    ),
+                ),
+                (
+                    "conditions",
+                    models.JSONField(
+                        blank=True,
+                        help_text="Optional conditions evaluated against form_data. Uses the same format as stage trigger_conditions. When set, the notification only fires if conditions are met.",
+                        null=True,
+                    ),
+                ),
+                (
+                    "subject_template",
+                    models.CharField(
+                        blank=True,
+                        default="",
+                        help_text="Custom email subject line. Supports {form_name} and {submission_id} placeholders. Leave blank for the default.",
+                        max_length=500,
+                    ),
+                ),
+                (
+                    "notify_submitter",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Include the person who submitted the form.",
+                    ),
+                ),
+                (
+                    "email_field",
+                    models.CharField(
+                        blank=True,
+                        default="",
+                        help_text="Form field slug whose submitted value is an email address. Resolved from form_data at send time (varies per submission).",
+                        max_length=200,
+                    ),
+                ),
+                (
+                    "static_emails",
+                    models.CharField(
+                        blank=True,
+                        default="",
+                        help_text="Comma-separated fixed email addresses.",
+                        max_length=1000,
+                    ),
+                ),
+                (
+                    "notify_stage_assignees",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Include dynamically-assigned approvers. When a stage is specified, only that stage's assignee is included. When no stage is specified, assignees from all stages are included.",
+                    ),
+                ),
+                (
+                    "notify_stage_groups",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Include all users in the stage's approval groups. When a stage is specified, only that stage's groups are included. When no stage is specified, groups from all stages are included.",
+                    ),
+                ),
+                (
+                    "notify_groups",
+                    models.ManyToManyField(
+                        blank=True,
+                        help_text="Additional groups to notify, independent of stage assignment. All users in these groups with a non-empty email will receive the notification.",
+                        related_name="notification_rules",
+                        to="auth.group",
+                    ),
+                ),
+                (
+                    "stage",
+                    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.",
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notification_rules",
+                        to="django_forms_workflows.workflowstage",
+                    ),
+                ),
+                (
+                    "workflow",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notification_rules",
+                        to="django_forms_workflows.workflowdefinition",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Notification Rule",
+                "verbose_name_plural": "Notification Rules",
+                "ordering": ["workflow", "event", "stage"],
+            },
+        ),
+    ]

django_forms_workflows-0.44.0/django_forms_workflows/migrations/0075_migrate_to_notification_rules.py

@@ -0,0 +1,98 @@
+"""
+Data migration: populate NotificationRule from the three legacy sources.
+
+1. WorkflowNotification  → NotificationRule (stage=null)
+2. StageFormFieldNotification → NotificationRule (stage=notif.stage)
+3. WorkflowStage.notify_assignee_on_final_decision=True
+     → two NotificationRule records (workflow_approved + workflow_denied)
+       with notify_stage_assignees=True, scoped to that stage.
+
+Event name mapping (old → new):
+  approval_notification  → workflow_approved
+  rejection_notification → workflow_denied
+  withdrawal_notification → form_withdrawn
+  submission_received    → submission_received  (unchanged)
+  approval_request       → approval_request     (unchanged)
+"""
+
+from django.db import migrations
+
+
+EVENT_MAP = {
+    "approval_notification": "workflow_approved",
+    "rejection_notification": "workflow_denied",
+    "withdrawal_notification": "form_withdrawn",
+    "submission_received": "submission_received",
+    "approval_request": "approval_request",
+}
+
+
+def forwards(apps, schema_editor):
+    NotificationRule = apps.get_model("django_forms_workflows", "NotificationRule")
+    WorkflowNotification = apps.get_model(
+        "django_forms_workflows", "WorkflowNotification"
+    )
+    StageFormFieldNotification = apps.get_model(
+        "django_forms_workflows", "StageFormFieldNotification"
+    )
+    WorkflowStage = apps.get_model("django_forms_workflows", "WorkflowStage")
+
+    # 1. WorkflowNotification → NotificationRule (workflow-scoped)
+    for wn in WorkflowNotification.objects.all():
+        NotificationRule.objects.create(
+            workflow_id=wn.workflow_id,
+            stage=None,
+            event=EVENT_MAP.get(wn.notification_type, wn.notification_type),
+            conditions=wn.conditions,
+            subject_template=wn.subject_template or "",
+            notify_submitter=wn.notify_submitter,
+            email_field=wn.email_field or "",
+            static_emails=wn.static_emails or "",
+            notify_stage_assignees=False,
+            notify_stage_groups=False,
+        )
+
+    # 2. StageFormFieldNotification → NotificationRule (stage-scoped)
+    for sfn in StageFormFieldNotification.objects.select_related("stage").all():
+        NotificationRule.objects.create(
+            workflow_id=sfn.stage.workflow_id,
+            stage_id=sfn.stage_id,
+            event=EVENT_MAP.get(sfn.notification_type, sfn.notification_type),
+            conditions=sfn.conditions,
+            subject_template=sfn.subject_template or "",
+            notify_submitter=False,
+            email_field=sfn.email_field or "",
+            static_emails=sfn.static_emails or "",
+            notify_stage_assignees=False,
+            notify_stage_groups=False,
+        )
+
+    # 3. WorkflowStage.notify_assignee_on_final_decision → two rules
+    for stage in WorkflowStage.objects.filter(
+        notify_assignee_on_final_decision=True
+    ):
+        for event in ("workflow_approved", "workflow_denied"):
+            NotificationRule.objects.create(
+                workflow_id=stage.workflow_id,
+                stage_id=stage.id,
+                event=event,
+                conditions=None,
+                subject_template="",
+                notify_submitter=False,
+                email_field="",
+                static_emails="",
+                notify_stage_assignees=True,
+                notify_stage_groups=False,
+            )
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0074_add_notification_rule"),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards, migrations.RunPython.noop),
+    ]
+

django_forms_workflows-0.44.0/django_forms_workflows/migrations/0076_update_notification_event_choices.py

@@ -0,0 +1,55 @@
+# Generated by Django 6.0.3 on 2026-03-31 16:29
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0075_migrate_to_notification_rules"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="notificationlog",
+            name="notification_type",
+            field=models.CharField(
+                choices=[
+                    ("submission_received", "Submission Received"),
+                    ("approval_request", "Approval Request"),
+                    ("stage_decision", "Stage Decision"),
+                    ("workflow_approved", "Workflow Approved"),
+                    ("workflow_denied", "Workflow Denied"),
+                    ("form_withdrawn", "Form Withdrawn"),
+                    ("approval_reminder", "Approval Reminder"),
+                    ("escalation", "Escalation"),
+                    ("batched", "Batched Digest"),
+                    ("submission_created", "Submission Received (legacy)"),
+                    ("approval_notification", "Approved (legacy)"),
+                    ("rejection_notification", "Rejected (legacy)"),
+                    ("other", "Other"),
+                ],
+                db_index=True,
+                default="other",
+                max_length=50,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="pendingnotification",
+            name="notification_type",
+            field=models.CharField(
+                choices=[
+                    ("submission_received", "Submission Received"),
+                    ("approval_request", "Approval Request"),
+                    ("stage_decision", "Stage Decision"),
+                    ("workflow_approved", "Workflow Approved"),
+                    ("workflow_denied", "Workflow Denied"),
+                    ("form_withdrawn", "Form Withdrawn"),
+                    ("approval_notification", "Approval Notification (legacy)"),
+                    ("rejection_notification", "Rejection Notification (legacy)"),
+                    ("withdrawal_notification", "Withdrawal Notification (legacy)"),
+                ],
+                max_length=30,
+            ),
+        ),
+    ]

django_forms_workflows-0.44.0/django_forms_workflows/migrations/0077_drop_legacy_notification_models.py

@@ -0,0 +1,27 @@
+# Generated by Django 6.0.3 on 2026-03-31 16:50
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0076_update_notification_event_choices"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="workflownotification",
+            name="workflow",
+        ),
+        migrations.RemoveField(
+            model_name="workflowstage",
+            name="notify_assignee_on_final_decision",
+        ),
+        migrations.DeleteModel(
+            name="StageFormFieldNotification",
+        ),
+        migrations.DeleteModel(
+            name="WorkflowNotification",
+        ),
+    ]