fix: stage group dedup, sub-workflow final notifications, README credits

- notify_stage_groups skipped when use_triggering_stage=True and the
  task has assigned_to set — prevents duplicate notifications when
  an individual was resolved via assignee_form_field
- _promote_parent_if_complete now fires _notify_final_approval when
  all sub-workflows finish and parent is promoted to approved
- _reject_sub_workflow fires _notify_rejection when a rejected child
  propagates rejection to the parent
- Added Logan Nickerson to README Credits

Bump version to 0.62.1.

Author: matteius

CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.62.1] - 2026-04-02
+
+### Fixed
+- **`notify_stage_groups` no longer duplicates when `assigned_to` is resolved** —
+  when `use_triggering_stage=True` and the task has a specific individual assigned
+  (via `assignee_form_field`), stage approval groups are now skipped. The individual
+  was already resolved so the fallback group should not also be notified.
+- **Sub-workflow completion now fires final-decision notifications** —
+  `_promote_parent_if_complete` calls `_notify_final_approval` when all sub-workflows
+  finish and the parent is promoted to approved. Similarly, `_reject_sub_workflow`
+  calls `_notify_rejection` when a rejected child propagates to the parent.
+  Previously, no notification was dispatched at either of these lifecycle points.
+
+### Changed
+- Added Logan Nickerson to README Credits for testing and business requirements.
+
+## [0.62.0] - 2026-04-02
+
+### Changed
+- **NotificationRule is now the single notification system.** The built-in
+  `send_approval_request` task is no longer dispatched from the workflow engine.
+  All notification behaviour is configured exclusively through NotificationRule
+  records.
+- **Reminders ported to rules.** `check_approval_deadlines` now dispatches
+  `approval_reminder` via `send_notification_rules` instead of calling the
+  hardcoded `send_approval_reminder` task.
+
+### Added
+- **New event types**: `approval_reminder` and `escalation` added to
+  NotificationRule.EVENT_TYPES.
+- **`body_template` field** on NotificationRule — custom HTML email body
+  rendered as a Django template string. When set, overrides the built-in
+  file-based template for that event. Supports all context variables
+  (submission, form_data, approver, task, approval_url, etc.).
+- **Data migration 0088** — auto-creates `approval_request` NotificationRule
+  records (with `use_triggering_stage=True`, `notify_stage_assignees=True`,
+  `notify_stage_groups=True`) for every workflow that doesn't already have one,
+  preserving the behaviour of the removed built-in email. Also creates
+  `approval_reminder` rules for workflows with `send_reminder_after_days` set.
+- `_send_html_email_from_string` helper for rendering inline template strings.
+
 ## [0.61.2] - 2026-04-02
 
 ### Fixed

README.md

@@ -421,6 +421,7 @@ See [docs/ROADMAP.md](docs/ROADMAP.md) for the full prioritized roadmap with rat
 Built with ❤️ by the Django community.
 
 Special thanks to:
+- Logan Nickerson for his time spent testing and helping with business requirements
 - [Django Crispy Forms](https://github.com/django-crispy-forms/django-crispy-forms)
 - [Celery](https://github.com/celery/celery)
 - [django-auth-ldap](https://github.com/django-auth-ldap/django-auth-ldap)

django_forms_workflows/admin.py

@@ -528,6 +528,18 @@ class NotificationRuleInline(nested_admin.NestedStackedInline):
                 )
             },
         ),
+        (
+            "Email body (optional)",
+            {
+                "classes": ("collapse",),
+                "description": (
+                    "Custom HTML email body. Rendered as a Django template "
+                    "with the full notification context. Leave blank to use "
+                    "the built-in template for this event type."
+                ),
+                "fields": ("body_template",),
+            },
+        ),
         (
             "Conditions (optional)",
             {
@@ -1748,6 +1760,18 @@ class NotificationRuleAdmin(admin.ModelAdmin):
                 )
             },
         ),
+        (
+            "Email body (optional)",
+            {
+                "classes": ("collapse",),
+                "description": (
+                    "Custom HTML email body. Rendered as a Django template "
+                    "with the full notification context. Leave blank to use "
+                    "the built-in template for this event type."
+                ),
+                "fields": ("body_template",),
+            },
+        ),
         (
             "Conditions (optional)",
             {

django_forms_workflows/migrations/0088_notificationrule_body_template_and_events.py

@@ -0,0 +1,91 @@
+# Generated by Django 5.2.7 on 2026-04-02
+
+from django.db import migrations, models
+
+
+def create_default_notification_rules(apps, schema_editor):
+    """Auto-create NotificationRule records for workflows that relied on
+    the built-in send_approval_request and send_approval_reminder tasks.
+
+    This ensures that removing the hardcoded email dispatch does not
+    silently break existing workflows.
+    """
+    WorkflowDefinition = apps.get_model(
+        "django_forms_workflows", "WorkflowDefinition"
+    )
+    NotificationRule = apps.get_model(
+        "django_forms_workflows", "NotificationRule"
+    )
+
+    for wf in WorkflowDefinition.objects.all():
+        # approval_request: replaces built-in send_approval_request
+        if not NotificationRule.objects.filter(
+            workflow=wf, event="approval_request"
+        ).exists():
+            NotificationRule.objects.create(
+                workflow=wf,
+                event="approval_request",
+                use_triggering_stage=True,
+                notify_stage_assignees=True,
+                notify_stage_groups=True,
+            )
+
+        # approval_reminder: replaces built-in send_approval_reminder
+        if (
+            getattr(wf, "send_reminder_after_days", None)
+            and not NotificationRule.objects.filter(
+                workflow=wf, event="approval_reminder"
+            ).exists()
+        ):
+            NotificationRule.objects.create(
+                workflow=wf,
+                event="approval_reminder",
+                use_triggering_stage=True,
+                notify_stage_assignees=True,
+            )
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0087_notificationrule_use_triggering_stage"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="notificationrule",
+            name="body_template",
+            field=models.TextField(
+                blank=True,
+                default="",
+                help_text=(
+                    "Custom email body (HTML). Rendered as a Django template with "
+                    "the full notification context (submission, form_data, approver, "
+                    "task, approval_url, submission_url, site_name, etc.). "
+                    "Leave blank to use the built-in template for this event type."
+                ),
+            ),
+        ),
+        migrations.AlterField(
+            model_name="notificationrule",
+            name="event",
+            field=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"),
+                    ("approval_reminder", "Approval Reminder"),
+                    ("escalation", "Escalation"),
+                ],
+                help_text="The workflow event that triggers this notification.",
+                max_length=30,
+            ),
+        ),
+        migrations.RunPython(
+            create_default_notification_rules,
+            reverse_code=migrations.RunPython.noop,
+        ),
+    ]

django_forms_workflows/models.py

@@ -1301,6 +1301,8 @@ class NotificationRule(models.Model):
         ("workflow_approved", "Workflow Approved (final decision)"),
         ("workflow_denied", "Workflow Denied (final decision)"),
         ("form_withdrawn", "Form Withdrawn"),
+        ("approval_reminder", "Approval Reminder"),
+        ("escalation", "Escalation"),
     ]
 
     workflow = models.ForeignKey(
@@ -1354,6 +1356,16 @@ class NotificationRule(models.Model):
             "{submission_id} placeholders. Leave blank for the default."
         ),
     )
+    body_template = models.TextField(
+        blank=True,
+        default="",
+        help_text=(
+            "Custom email body (HTML). Rendered as a Django template with "
+            "the full notification context (submission, form_data, approver, "
+            "task, approval_url, submission_url, site_name, etc.). "
+            "Leave blank to use the built-in template for this event type."
+        ),
+    )
 
     # ── Recipient sources (all optional, combined additively) ──
 

django_forms_workflows/tasks.py

@@ -149,6 +149,71 @@ def _send_html_email(
             )
 
 
+def _send_html_email_from_string(
+    subject: str,
+    to: Iterable[str],
+    body_template_string: str,
+    context: dict,
+    from_email: str | None = None,
+    *,
+    notification_type: str = "other",
+    submission_id: int | None = None,
+) -> None:
+    """Like _send_html_email but renders an inline Django template string
+    instead of loading a template file.  Used when a NotificationRule has a
+    custom ``body_template``.
+    """
+    from django.template import Context, Template
+
+    to_list = [e for e in to if e]
+    if not to_list:
+        logger.info("Skipping email '%s' (no recipients)", subject)
+        _write_notification_log(
+            notification_type=notification_type,
+            submission_id=submission_id,
+            recipient_email="(none)",
+            subject=subject,
+            status="skipped",
+        )
+        return
+
+    context.setdefault("site_name", _site_name())
+
+    tpl = Template(body_template_string)
+    html_body = tpl.render(Context(context))
+    text_body = strip_tags(html_body)
+    from_addr = from_email or getattr(
+        settings, "DEFAULT_FROM_EMAIL", "no-reply@localhost"
+    )
+
+    msg = EmailMultiAlternatives(
+        subject=subject, body=text_body, from_email=from_addr, to=to_list
+    )
+    msg.attach_alternative(html_body, "text/html")
+    try:
+        msg.send(fail_silently=False)
+        logger.info("Sent email '%s' to %s", subject, to_list)
+        for recipient in to_list:
+            _write_notification_log(
+                notification_type=notification_type,
+                submission_id=submission_id,
+                recipient_email=recipient,
+                subject=subject,
+                status="sent",
+            )
+    except Exception as e:  # pragma: no cover
+        logger.exception("Failed sending email '%s' to %s: %s", subject, to_list, e)
+        for recipient in to_list:
+            _write_notification_log(
+                notification_type=notification_type,
+                submission_id=submission_id,
+                recipient_email=recipient,
+                subject=subject,
+                status="failed",
+                error_message=str(e),
+            )
+
+
 def _write_notification_log(
     *,
     notification_type: str,
@@ -726,10 +791,12 @@ def check_approval_deadlines() -> str:
             )
             if now > reminder_time:
                 try:
-                    send_approval_reminder.delay(task.id)
+                    send_notification_rules.delay(
+                        submission.id, "approval_reminder", task_id=task.id
+                    )
                 except Exception:
                     logger.debug(
-                        "Could not enqueue send_approval_reminder for task %s",
+                        "Could not enqueue approval_reminder for task %s",
                         task.id,
                         exc_info=True,
                     )
@@ -1035,7 +1102,20 @@ def _effective_stage_id():
             _add(email)
 
     # 5. Stage approval groups (NotificationRule only)
-    if getattr(notif, "notify_stage_groups", False) and submission is not None:
+    #    When using the triggering stage and the task already has a specific
+    #    individual assigned (assigned_to), skip the group notification —
+    #    the individual was resolved via assignee_form_field so the fallback
+    #    group should not also be notified.
+    _skip_stage_groups = (
+        getattr(notif, "use_triggering_stage", False)
+        and task is not None
+        and getattr(task, "assigned_to_id", None) is not None
+    )
+    if (
+        getattr(notif, "notify_stage_groups", False)
+        and submission is not None
+        and not _skip_stage_groups
+    ):
         from django.contrib.auth import get_user_model
 
         user_model = get_user_model()
@@ -1117,6 +1197,8 @@ def _build_form_field_notification_context(
     "workflow_approved": "emails/approval_notification.html",
     "workflow_denied": "emails/rejection_notification.html",
     "form_withdrawn": "emails/withdrawal_notification.html",
+    "approval_reminder": "emails/approval_reminder.html",
+    "escalation": "emails/escalation_notification.html",
 }
 
 _EVENT_DEFAULT_SUBJECTS: dict[str, str] = {
@@ -1126,6 +1208,8 @@ def _build_form_field_notification_context(
     "workflow_approved": "Submission Approved: {form_name} (ID {submission_id})",
     "workflow_denied": "Submission Rejected: {form_name} (ID {submission_id})",
     "form_withdrawn": "Submission Withdrawn: {form_name} (ID {submission_id})",
+    "approval_reminder": "Reminder: Approval Pending for {form_name} (ID {submission_id})",
+    "escalation": "Escalation: {form_name} (ID {submission_id})",
 }
 
 
@@ -1150,8 +1234,8 @@ def send_notification_rules(
         event: The NotificationRule event type (e.g. ``workflow_approved``).
         task_id: Optional ApprovalTask ID (used for approval_request context).
     """
-    template = _EVENT_TEMPLATE_MAP.get(event)
-    if not template:
+    default_template = _EVENT_TEMPLATE_MAP.get(event)
+    if not default_template:
         logger.warning("send_notification_rules: unknown event '%s'", event)
         return
 
@@ -1298,16 +1382,28 @@ def send_notification_rules(
                 scheduled_for,
             )
         else:
+            # Determine template: per-rule body_template overrides file.
+            rule_body = getattr(rule, "body_template", "") or ""
             for recipient in recipients:
                 ctx = {**base_context}
                 recipient_user = _users_by_email.get(recipient)
                 if recipient_user:
                     ctx["approver"] = recipient_user
-                _send_html_email(
-                    subject,
-                    [recipient],
-                    template,
-                    ctx,
-                    notification_type=event,
-                    submission_id=submission_id,
-                )
+                if rule_body.strip():
+                    _send_html_email_from_string(
+                        subject,
+                        [recipient],
+                        rule_body,
+                        ctx,
+                        notification_type=event,
+                        submission_id=submission_id,
+                    )
+                else:
+                    _send_html_email(
+                        subject,
+                        [recipient],
+                        default_template,
+                        ctx,
+                        notification_type=event,
+                        submission_id=submission_id,
+                    )