feat: extend batching to all WorkflowNotification event types (v0.38.0)

Previously notification_cadence only batched submission_received and
approval_request. The other three conclusion events always fired
immediately. Now all four WorkflowNotification event types respect
the cadence setting.

workflow_engine.py:
- Add _notify_workflow_notification_with_cadence() shared helper that
  checks cadence, queues via _queue_workflow_level_notifications when
  non-immediate, and falls back to immediate on error
- _notify_submission_created: stage form-field notifications always
  fire immediately; WorkflowNotification path goes through new helper
- _notify_final_approval, _notify_rejection: same pattern via helper

views.py:
- Withdrawal routes through _notify_workflow_notification_with_cadence

tasks.py:
- Replace _queue_submission_notifications with generalized
  _queue_workflow_level_notifications(submission, workflow, type)
  resolving WorkflowNotification rules with full condition and
  recipient evaluation
- Add _dispatch_conclusion_digest for approval/rejection/withdrawal
- send_batched_notifications handles all five notification types

models.py:
- PendingNotification.NOTIFICATION_TYPES expanded

337 tests pass. Bump 0.37.17 to 0.38.0

Author: matteius

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-03-27
+
+### Added
+- **Batching for all WorkflowNotification event types** — `notification_cadence` now applies to every workflow-conclusion event (`approval_notification`, `rejection_notification`, `withdrawal_notification`) in addition to the existing `submission_received`. Previously only `submission_received` and `approval_request` were batched; the other three always fired immediately regardless of cadence.
+- **`_queue_workflow_level_notifications(submission, workflow, notification_type)`** — replaces the old `_queue_submission_notifications` helper. Resolves every matching `WorkflowNotification` rule (evaluating conditions and all three recipient sources — `notify_submitter`, `email_field`, `static_emails`) and creates one `PendingNotification` row per resolved recipient, correctly honouring per-rule conditions and the full recipient resolution logic.
+- **`_dispatch_conclusion_digest`** — new batch-dispatch function for `approval_notification`, `rejection_notification`, and `withdrawal_notification` digests, reusing the existing `notification_digest.html` template with a verb/label context (`approved`/`rejected`/`withdrawn`).
+- **`_notify_workflow_notification_with_cadence(submission, notification_type)`** — shared helper in `workflow_engine.py` that checks `notification_cadence` and either queues via `_queue_workflow_level_notifications` or fires `send_workflow_definition_notifications` immediately. Used by `_notify_submission_created`, `_notify_final_approval`, `_notify_rejection`, and the withdrawal view.
+
+### Changed
+- `PendingNotification.NOTIFICATION_TYPES` expanded with `approval_notification`, `rejection_notification`, `withdrawal_notification`.
+- `send_batched_notifications` dispatch block handles all five notification types; unknown types are logged and skipped rather than silently dropped.
+- Stage `StageFormFieldNotification` events always fire immediately regardless of cadence — this is unchanged and intentional.
+
 ## [0.37.17] - 2026-03-27
 
 ### Fixed

django_forms_workflows/models.py

@@ -1144,16 +1144,23 @@ class PendingNotification(models.Model):
     """
     Queue of notifications waiting to be sent as part of a batch digest.
 
-    When a WorkflowDefinition has a non-immediate notification_cadence, incoming
-    approval-request and submission-received events are stored here instead of
-    being emailed immediately.  The ``send_batched_notifications`` periodic task
-    finds due records, groups them by recipient + type, and sends a single digest
-    email per group.
+    When a WorkflowDefinition has a non-immediate notification_cadence, all
+    WorkflowNotification-level events (submission_received, approval_notification,
+    rejection_notification, withdrawal_notification) and approval_request events
+    are stored here instead of being emailed immediately.
+
+    The ``send_batched_notifications`` periodic task finds due records, groups them
+    by (recipient_email, notification_type, workflow_id), and sends one digest email
+    per group.  Stage form-field notifications (StageFormFieldNotification) always
+    fire immediately and are not stored here.
     """
 
     NOTIFICATION_TYPES = [
         ("submission_received", "Submission Received"),
         ("approval_request", "Approval Request"),
+        ("approval_notification", "Approval Notification"),
+        ("rejection_notification", "Rejection Notification"),
+        ("withdrawal_notification", "Withdrawal Notification"),
     ]
 
     workflow = models.ForeignKey(

django_forms_workflows/tasks.py

@@ -245,29 +245,58 @@ def _at_time(base_dt):
     return _at_time(now + timedelta(days=1))
 
 
-def _queue_submission_notifications(submission, workflow) -> None:
-    """Queue a submission_received PendingNotification for each recipient.
+def _queue_workflow_level_notifications(
+    submission, workflow, notification_type: str
+) -> None:
+    """Queue a PendingNotification row per resolved recipient for a WorkflowNotification event.
 
-    Recipients are resolved from WorkflowNotification rows with notify_submitter=True
-    or static_emails/email_field configured. The legacy notify_on_* flags and
-    additional_notify_emails have been removed; all submitter notifications are now
-    configured via WorkflowNotification rows (created by migration 0067).
+    Evaluates every WorkflowNotification rule attached to *workflow* for
+    *notification_type*, respects conditions, and resolves recipients via
+    ``_collect_notification_recipients`` (notify_submitter + email_field + static_emails).
+    One PendingNotification row is created per recipient per matching rule so that
+    ``send_batched_notifications`` can group them into a single digest email.
     """
+    from .conditions import evaluate_conditions
+
     scheduled_for = _compute_scheduled_for(workflow, submission)
-    submitter_email = getattr(getattr(submission, "submitter", None), "email", "")
-    recipients: list[str] = []
-    if submitter_email:
-        recipients.append(submitter_email)
-    for email in recipients:
-        PendingNotification.objects.create(
-            workflow=workflow,
-            notification_type="submission_received",
-            submission=submission,
-            recipient_email=email,
-            scheduled_for=scheduled_for,
+    form_data = submission.form_data or {}
+
+    notifications = WorkflowNotification.objects.filter(
+        workflow=workflow,
+        notification_type=notification_type,
+    )
+
+    queued = 0
+    for notif in notifications:
+        if notif.conditions:
+            try:
+                if not evaluate_conditions(notif.conditions, form_data):
+                    continue
+            except Exception:
+                logger.warning(
+                    "WorkflowNotification %s: condition error during batch queueing; skipping.",
+                    notif.id,
+                    exc_info=True,
+                )
+                continue
+
+        recipients = _collect_notification_recipients(
+            notif, form_data, submission=submission
         )
+        for email in recipients:
+            PendingNotification.objects.create(
+                workflow=workflow,
+                notification_type=notification_type,
+                submission=submission,
+                recipient_email=email,
+                scheduled_for=scheduled_for,
+            )
+            queued += 1
+
     logger.info(
-        "Queued submission_received batch notification for submission %s (due %s)",
+        "Queued %d %s batch notification(s) for submission %s (due %s)",
+        queued,
+        notification_type,
         submission.id,
         scheduled_for,
     )
@@ -575,6 +604,21 @@ def send_batched_notifications() -> str:
                 _dispatch_submission_digest(recipient_email, notifications)
             elif notification_type == "approval_request":
                 _dispatch_approval_digest(recipient_email, notifications)
+            elif notification_type in (
+                "approval_notification",
+                "rejection_notification",
+                "withdrawal_notification",
+            ):
+                _dispatch_conclusion_digest(
+                    recipient_email, notifications, notification_type
+                )
+            else:
+                logger.warning(
+                    "send_batched_notifications: unknown type %r for %s; skipping.",
+                    notification_type,
+                    recipient_email,
+                )
+                continue
             ids = [n.id for n in notifications]
             PendingNotification.objects.filter(id__in=ids).update(sent=True)
             sent_count += len(ids)
@@ -664,6 +708,50 @@ def _dispatch_approval_digest(recipient_email: str, notifications: list) -> None
     )
 
 
+_CONCLUSION_VERB: dict[str, tuple[str, str]] = {
+    "approval_notification": ("approved", "Approvals"),
+    "rejection_notification": ("rejected", "Rejections"),
+    "withdrawal_notification": ("withdrawn", "Withdrawals"),
+}
+
+
+def _dispatch_conclusion_digest(
+    recipient_email: str, notifications: list, notification_type: str
+) -> None:
+    """Send a digest of approval/rejection/withdrawal events to one recipient."""
+    sample = notifications[0]
+    workflow = sample.workflow
+    form_name = workflow.form_definition.name
+    count = len(notifications)
+    verb, label = _CONCLUSION_VERB.get(notification_type, ("processed", "Updates"))
+    submissions = [
+        {
+            "submission": n.submission,
+            "submission_url": _abs(
+                reverse("forms_workflows:submission_detail", args=[n.submission.id])
+            ),
+        }
+        for n in notifications
+        if n.submission
+    ]
+    subject = f"{count} submission{'s' if count != 1 else ''} {verb} — {form_name}"
+    context = {
+        "form_name": form_name,
+        "count": count,
+        "submissions": submissions,
+        "notification_type": notification_type,
+        "verb": verb,
+        "label": label,
+    }
+    _send_html_email(
+        subject,
+        [recipient_email],
+        "emails/notification_digest.html",
+        context,
+        notification_type="batched",
+    )
+
+
 # ---------------------------------------------------------------------------
 # Form-Field Conditional Notification Tasks
 # ---------------------------------------------------------------------------

django_forms_workflows/views.py

@@ -1745,11 +1745,13 @@ def withdraw_submission(request, submission_id):
             comments="Submission withdrawn by submitter",
         )
 
-        # Send withdrawal notifications via WorkflowNotification rules.
+        # Send withdrawal notifications — respects notification_cadence.
         try:
-            from .workflow_engine import _notify_workflow_level_recipients
+            from .workflow_engine import _notify_workflow_notification_with_cadence
 
-            _notify_workflow_level_recipients(submission, "withdrawal_notification")
+            _notify_workflow_notification_with_cadence(
+                submission, "withdrawal_notification"
+            )
         except Exception:
             logger.warning(
                 "Could not dispatch withdrawal notifications for submission %s",

django_forms_workflows/workflow_engine.py

@@ -52,7 +52,14 @@
 # ---- notification shims ----
 
 
-def _notify_submission_created(submission: FormSubmission) -> None:
+def _notify_workflow_notification_with_cadence(
+    submission: FormSubmission, notification_type: str
+) -> None:
+    """Route WorkflowNotification rules through the batch queue or fire immediately.
+
+    Stage form-field notifications (StageFormFieldNotification) are always dispatched
+    immediately by their own callers and are not affected by this function.
+    """
     workflow = getattr(submission.form_definition, "workflow", None)
     cadence = (
         getattr(workflow, "notification_cadence", "immediate")
@@ -62,22 +69,26 @@ def _notify_submission_created(submission: FormSubmission) -> None:
 
     if cadence != "immediate" and workflow is not None:
         try:
-            from .tasks import _queue_submission_notifications
+            from .tasks import _queue_workflow_level_notifications
 
-            _queue_submission_notifications(submission, workflow)
+            _queue_workflow_level_notifications(submission, workflow, notification_type)
         except Exception:
             logger.warning(
-                "Failed to queue batched submission notification; falling back to immediate"
+                "Failed to queue batched %s notification for submission %s; "
+                "falling back to immediate.",
+                notification_type,
+                submission.id,
             )
-            _notify_submission_created_immediate(submission)
+            _notify_workflow_level_recipients(submission, notification_type)
         return
 
-    _notify_submission_created_immediate(submission)
+    _notify_workflow_level_recipients(submission, notification_type)
 
 
-def _notify_submission_created_immediate(submission: FormSubmission) -> None:
+def _notify_submission_created(submission: FormSubmission) -> None:
+    # Stage form-field notifications always fire immediately regardless of cadence.
     _notify_form_field_recipients_for_submission(submission, "submission_received")
-    _notify_workflow_level_recipients(submission, "submission_received")
+    _notify_workflow_notification_with_cadence(submission, "submission_received")
 
 
 def _notify_task_request(task: ApprovalTask) -> None:
@@ -114,12 +125,12 @@ def _notify_task_request_immediate(task: ApprovalTask) -> None:
 
 def _notify_final_approval(submission: FormSubmission) -> None:
     _notify_form_field_recipients_for_submission(submission, "approval_notification")
-    _notify_workflow_level_recipients(submission, "approval_notification")
+    _notify_workflow_notification_with_cadence(submission, "approval_notification")
 
 
 def _notify_rejection(submission: FormSubmission) -> None:
     _notify_form_field_recipients_for_submission(submission, "rejection_notification")
-    _notify_workflow_level_recipients(submission, "rejection_notification")
+    _notify_workflow_notification_with_cadence(submission, "rejection_notification")
 
 
 def _notify_form_field_recipients_for_submission(

pyproject.toml

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