feat: add role-based group separation for validation and reassignment

StageApprovalGroup now supports a `role` field (approval/validation/
reassignment) so stages can use different groups for assignee validation,
reassignment eligibility, and fallback approval. Falls back to approval
groups when no role-specific groups are configured (backward compatible).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: matteius

django_forms_workflows/admin.py

@@ -477,8 +477,9 @@ class StageApprovalGroupInline(nested_admin.NestedTabularInline):
 
     model = StageApprovalGroup
     extra = 1
-    ordering = ("position",)
+    ordering = ("role", "position")
     autocomplete_fields = ("group",)
+    fields = ("group", "role", "position")
 
 
 class WorkflowStageInline(nested_admin.NestedStackedInline):
@@ -963,11 +964,12 @@ def clone_forms(self, request, queryset):
                             )
                             for sag in StageApprovalGroup.objects.filter(
                                 stage=stage
-                            ).order_by("position"):
+                            ).order_by("role", "position"):
                                 StageApprovalGroup.objects.create(
                                     stage=cloned_stage,
                                     group=sag.group,
                                     position=sag.position,
+                                    role=sag.role,
                                 )
                         # Clone SubWorkflowDefinition if present
                         try:

django_forms_workflows/form_builder_views.py

@@ -187,12 +187,13 @@ def form_builder_clone(request, form_id):
                         trigger_conditions=stage.trigger_conditions,
                     )
                     for sag in StageApprovalGroup.objects.filter(stage=stage).order_by(
-                        "position"
+                        "role", "position"
                     ):
                         StageApprovalGroup.objects.create(
                             stage=cloned_stage,
                             group=sag.group,
                             position=sag.position,
+                            role=sag.role,
                         )
                 # Clone SubWorkflowDefinition if present
                 try:

django_forms_workflows/management/commands/seed_farm_demo.py

@@ -1784,6 +1784,7 @@ def _set_stage_groups(self, stage, groups, sequential=False):
                 StageApprovalGroup.objects.update_or_create(
                     stage=stage,
                     group=group,
+                    role="approval",
                     defaults={"position": position},
                 )
 

django_forms_workflows/migrations/0090_alter_stageapprovalgroup_options_and_more.py

@@ -0,0 +1,44 @@
+# Generated by Django 5.2.7 on 2026-04-13 17:37
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("auth", "0012_alter_user_first_name_max_length"),
+        ("django_forms_workflows", "0089_workflowstage_hide_comment_field"),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name="stageapprovalgroup",
+            options={
+                "ordering": ["role", "position"],
+                "verbose_name": "Stage Approval Group",
+                "verbose_name_plural": "Stage Approval Groups",
+            },
+        ),
+        migrations.AlterUniqueTogether(
+            name="stageapprovalgroup",
+            unique_together=set(),
+        ),
+        migrations.AddField(
+            model_name="stageapprovalgroup",
+            name="role",
+            field=models.CharField(
+                choices=[
+                    ("approval", "Approval (default)"),
+                    ("validation", "Assignee validation"),
+                    ("reassignment", "Reassignment pool"),
+                ],
+                default="approval",
+                help_text="Purpose of this group in the stage. 'Approval' groups receive fallback tasks and define the default pool. 'Validation' groups are checked when verifying a dynamic assignee's group membership (falls back to approval groups when none defined). 'Reassignment' groups define who may be reassigned to (falls back to approval groups when none defined).",
+                max_length=20,
+            ),
+        ),
+        migrations.AlterUniqueTogether(
+            name="stageapprovalgroup",
+            unique_together={("stage", "group", "role")},
+        ),
+    ]

django_forms_workflows/models.py

@@ -1249,15 +1249,68 @@ class Meta:
     def __str__(self) -> str:
         return f"Stage {self.order}: {self.name}"
 
+    # ------------------------------------------------------------------
+    # Helpers to retrieve groups by role (with fallback to approval)
+    # ------------------------------------------------------------------
+
+    def _groups_by_role(self, role: str):
+        """Return groups for *role*, falling back to approval groups if none."""
+        qs = Group.objects.filter(
+            stageapprovalgroup__stage=self,
+            stageapprovalgroup__role=role,
+        ).order_by("stageapprovalgroup__position")
+        if qs.exists():
+            return qs
+        # Fallback: approval groups
+        return Group.objects.filter(
+            stageapprovalgroup__stage=self,
+            stageapprovalgroup__role="approval",
+        ).order_by("stageapprovalgroup__position")
+
+    def get_validation_groups(self):
+        """Groups used to validate a dynamic assignee's membership."""
+        return self._groups_by_role("validation")
+
+    def get_reassignment_groups(self):
+        """Groups that define the eligible reassignment pool."""
+        return self._groups_by_role("reassignment")
+
+    def get_approval_groups(self):
+        """Groups used for fallback task assignment / approval logic."""
+        return Group.objects.filter(
+            stageapprovalgroup__stage=self,
+            stageapprovalgroup__role="approval",
+        ).order_by("stageapprovalgroup__position")
+
 
 class StageApprovalGroup(models.Model):
     """
     Through model for WorkflowStage ↔ Group M2M.
 
     Stores a ``position`` so admins can control the order groups are
     processed when approval_logic is ``"sequence"``.
+
+    The ``role`` field distinguishes the purpose of a group within the stage:
+
+    * **approval** – the default pool used for fallback task assignment and
+      approval logic (AND/OR/sequence).
+    * **validation** – used to check that a dynamically resolved assignee
+      belongs to an allowed group.  When no validation groups are configured,
+      approval groups are used instead.
+    * **reassignment** – defines the eligible pool of users for task
+      reassignment.  When no reassignment groups are configured, approval
+      groups are used instead.
+
+    The same Django ``Group`` may appear under multiple roles for a single
+    stage (e.g. both approval and reassignment).
     """
 
+    ROLE_CHOICES = [
+        ("approval", "Approval (default)"),
+        ("validation", "Assignee validation"),
+        ("reassignment", "Reassignment pool"),
+    ]
+
     stage = models.ForeignKey(
         WorkflowStage,
         on_delete=models.CASCADE,
@@ -1270,15 +1323,30 @@ class StageApprovalGroup(models.Model):
         default=0,
         help_text="Order in which this group is processed (lower = first)",
     )
+    role = models.CharField(
+        max_length=20,
+        choices=ROLE_CHOICES,
+        default="approval",
+        help_text=(
+            "Purpose of this group in the stage. "
+            "'Approval' groups receive fallback tasks and define the default pool. "
+            "'Validation' groups are checked when verifying a dynamic assignee's "
+            "group membership (falls back to approval groups when none defined). "
+            "'Reassignment' groups define who may be reassigned to "
+            "(falls back to approval groups when none defined)."
+        ),
+    )
 
     class Meta:
-        ordering = ["position"]
-        unique_together = [("stage", "group")]
+        ordering = ["role", "position"]
+        unique_together = [("stage", "group", "role")]
         verbose_name = "Stage Approval Group"
         verbose_name_plural = "Stage Approval Groups"
 
     def __str__(self) -> str:
-        return f"{self.group.name} (pos {self.position})"
+        label = self.get_role_display() if self.role != "approval" else ""
+        suffix = f" [{label}]" if label else ""
+        return f"{self.group.name} (pos {self.position}){suffix}"
 
 
 class NotificationRule(models.Model):

django_forms_workflows/sync_api.py

@@ -237,9 +237,9 @@ def _serialize_workflow_stage(stage):
     # Serialize approval groups with their sequence position so that
     # "sequence" stages are restored in the correct order on import.
     approval_groups = [
-        {"name": sag.group.name, "position": sag.position}
+        {"name": sag.group.name, "position": sag.position, "role": sag.role}
         for sag in stage.stageapprovalgroup_set.select_related("group").order_by(
-            "position"
+            "role", "position"
         )
     ]
     return {
@@ -792,11 +792,13 @@ def _import_single_workflow(
             if isinstance(entry, dict):
                 group = _get_or_create_group(entry["name"])
                 position = entry.get("position", pos)
+                role = entry.get("role", "approval")
             else:
                 group = _get_or_create_group(entry)
                 position = pos
+                role = "approval"
             StageApprovalGroup.objects.create(
-                stage=stage, group=group, position=position
+                stage=stage, group=group, position=position, role=role
             )
 
         stage.notification_rules.all().delete()

django_forms_workflows/views.py

@@ -1925,13 +1925,13 @@ def reassign_task(request, task_id):
         messages.error(request, "Reassignment is not enabled for this approval step.")
         return redirect("forms_workflows:approval_inbox")
 
-    # Permission: current assignee, any member of the stage's approval groups,
-    # or superuser can reassign.
-    stage_groups = list(stage.approval_groups.all())
-    stage_group_ids = {g.pk for g in stage_groups}
+    # Permission: current assignee, any member of the stage's reassignment
+    # groups (falls back to approval groups), or superuser can reassign.
+    reassign_groups = list(stage.get_reassignment_groups())
+    reassign_group_ids = {g.pk for g in reassign_groups}
     can_reassign = (
         task.assigned_to == request.user
-        or request.user.groups.filter(pk__in=stage_group_ids).exists()
+        or request.user.groups.filter(pk__in=reassign_group_ids).exists()
         or request.user.is_superuser
     )
     if not can_reassign:
@@ -1950,11 +1950,11 @@ def reassign_task(request, task_id):
             messages.error(request, "Selected user not found.")
             return redirect("forms_workflows:reassign_task", task_id=task_id)
 
-        # Validate the new assignee is in one of the stage's approval groups
-        if not new_assignee.groups.filter(pk__in=stage_group_ids).exists():
+        # Validate the new assignee is in one of the stage's reassignment groups
+        if not new_assignee.groups.filter(pk__in=reassign_group_ids).exists():
             messages.error(
                 request,
-                "The selected user is not a member of any approval group for this stage.",
+                "The selected user is not a member of any reassignment group for this stage.",
             )
             return redirect("forms_workflows:reassign_task", task_id=task_id)
 
@@ -1988,7 +1988,7 @@ def reassign_task(request, task_id):
 
     # GET — show reassignment form with eligible users
     eligible_users = (
-        user_model.objects.filter(groups__pk__in=stage_group_ids, is_active=True)
+        user_model.objects.filter(groups__pk__in=reassign_group_ids, is_active=True)
         .distinct()
         .order_by("last_name", "first_name", "username")
     )

django_forms_workflows/workflow_builder_views.py

@@ -129,9 +129,14 @@ def _normalize_trigger_conditions(raw_conditions):
 
 def _serialize_stage_approval_groups(stage):
     return [
-        {"id": sag.group_id, "name": sag.group.name, "position": sag.position}
+        {
+            "id": sag.group_id,
+            "name": sag.group.name,
+            "position": sag.position,
+            "role": sag.role,
+        }
         for sag in stage.stageapprovalgroup_set.select_related("group").order_by(
-            "position", "group__name"
+            "role", "position", "group__name"
         )
     ]
 
@@ -1245,6 +1250,7 @@ def convert_visual_to_workflow(workflow_data, form_definition, workflow=None):
                 stage=stage,
                 group_id=group_entry["id"],
                 position=group_entry.get("position", pos),
+                role=group_entry.get("role", "approval"),
             )
 
         stage_node_map[snode.get("id")] = stage

django_forms_workflows/workflow_engine.py

@@ -586,12 +586,14 @@ def _create_stage_tasks(
     # --- Dynamic assignment (form field → User lookup) ------------------------
     dynamic_assignee = _resolve_dynamic_assignee(submission, stage)
     if dynamic_assignee is not None:
-        # Optionally validate the resolved user belongs to a stage approval group
+        # Optionally validate the resolved user belongs to the stage's
+        # validation groups (falls back to approval groups when none defined).
         if stage.validate_assignee_group and groups:
-            group_ids = {g.pk for g in groups}
-            if not dynamic_assignee.groups.filter(pk__in=group_ids).exists():
+            validation_groups = list(stage.get_validation_groups())
+            validation_group_ids = {g.pk for g in validation_groups}
+            if not dynamic_assignee.groups.filter(pk__in=validation_group_ids).exists():
                 logger.warning(
-                    "Dynamic assignee '%s' is not a member of any approval group "
+                    "Dynamic assignee '%s' is not a member of any validation group "
                     "for stage '%s' (submission %s); falling back to group assignment.",
                     dynamic_assignee.username,
                     stage.name,

pyproject.toml

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