feat: add reviewer_groups permission level to FormDefinition

Adds a new reviewer_groups M2M field that grants read-only access to all
submissions and full approval history for a form, without admin privileges.

- reviewer_groups members see all non-draft submissions for their forms
  in My Submissions so they can navigate without needing a direct URL
- Full approval history always visible to reviewers (respects hide_approval_history
  the same way approvers and admins do)
- Permission enforced in submission_detail, sub_workflow_detail, submission_pdf,
  bulk_export_submissions, bulk_export_submissions_pdf, user_can_view_submission
- Django Admin: filter_horizontal widget in Access Control fieldset; preserved
  when cloning a form
- Migration 0064_add_reviewer_groups adds the join table

Bumps version to 0.37.0

Author: matteius

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-03-26
+
+### Added
+- **`reviewer_groups` permission level on `FormDefinition`** — a new M2M field that grants named groups read-only access to all submissions and their full approval history for a form, without the management capabilities of `admin_groups`.
+  - Members of a `reviewer_groups` group will see all submitted/pending/approved/rejected/withdrawn submissions for that form under **My Submissions** (alongside their own), so they can navigate to them without needing a direct URL.
+  - The full approval history is always visible to reviewers even when `hide_approval_history` is enabled on the workflow (matching the behaviour for approvers and admins).
+  - Access is enforced consistently across `submission_detail`, `sub_workflow_detail`, `submission_pdf`, `bulk_export_submissions`, `bulk_export_submissions_pdf`, and the `user_can_view_submission` utility.
+  - The field is exposed in Django Admin under the **Access Control** fieldset with a horizontal filter widget, and is preserved when cloning a form.
+  - Migration `0064_add_reviewer_groups` adds the underlying join table.
+
 ## [0.36.5] - 2026-03-26
 
 ### Fixed

django_forms_workflows/admin.py

@@ -398,7 +398,12 @@ class FormDefinitionAdmin(nested_admin.NestedModelAdmin):
     prepopulated_fields = {"slug": ("name",)}
     readonly_fields = ("created_at", "updated_at", "created_by")
     inlines = [FormFieldInline, WorkflowDefinitionInline]
-    filter_horizontal = ("submit_groups", "view_groups", "admin_groups")
+    filter_horizontal = (
+        "submit_groups",
+        "view_groups",
+        "admin_groups",
+        "reviewer_groups",
+    )
     change_form_template = "admin/django_forms_workflows/formdef_change_form.html"
     actions = ["clone_forms", "diff_forms", "export_as_json"]
 
@@ -424,6 +429,7 @@ class FormDefinitionAdmin(nested_admin.NestedModelAdmin):
                     "submit_groups",
                     "view_groups",
                     "admin_groups",
+                    "reviewer_groups",
                 ),
             },
         ),
@@ -614,6 +620,7 @@ def clone_forms(self, request, queryset):
                     cloned_form.submit_groups.set(form.submit_groups.all())
                     cloned_form.view_groups.set(form.view_groups.all())
                     cloned_form.admin_groups.set(form.admin_groups.all())
+                    cloned_form.reviewer_groups.set(form.reviewer_groups.all())
 
                     # Clone workflows, stages, and stage approval groups
                     for wf in form.workflows.all():

django_forms_workflows/migrations/0064_add_reviewer_groups.py

@@ -0,0 +1,27 @@
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0063_formdefinition_api_enabled_apitoken"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="formdefinition",
+            name="reviewer_groups",
+            field=models.ManyToManyField(
+                blank=True,
+                help_text=(
+                    "Groups that can view all submissions and full approval history "
+                    "for this form. Unlike admin groups, reviewers cannot manage the "
+                    "form itself."
+                ),
+                related_name="can_review_forms",
+                to="auth.group",
+            ),
+        ),
+    ]
+

django_forms_workflows/models.py

@@ -156,6 +156,15 @@ class FormDefinition(models.Model):
         blank=True,
         help_text="Groups that can view all submissions",
     )
+    reviewer_groups = models.ManyToManyField(
+        Group,
+        related_name="can_review_forms",
+        blank=True,
+        help_text=(
+            "Groups that can view all submissions and full approval history for this form. "
+            "Unlike admin groups, reviewers cannot manage the form itself."
+        ),
+    )
 
     # Behavior
     allow_save_draft = models.BooleanField(

django_forms_workflows/utils.py

@@ -264,6 +264,12 @@ def user_can_view_submission(user, submission: FormSubmission) -> bool:
     ).exists():
         return True
 
+    # Reviewers can view submissions and approval history
+    if user.groups.filter(
+        id__in=submission.form_definition.reviewer_groups.all()
+    ).exists():
+        return True
+
     return False
 
 

django_forms_workflows/views.py

@@ -417,7 +417,25 @@ def my_submissions(request):
     ``category_counts`` list so the UI can render a filter-pill bar showing
     how many submissions belong to each category.
     """
-    base_submissions = FormSubmission.objects.filter(submitter=request.user)
+    # Include submissions the user owns OR submissions for forms they can review.
+    reviewer_form_ids = (
+        FormDefinition.objects.filter(reviewer_groups__in=request.user.groups.all())
+        .values_list("id", flat=True)
+        .distinct()
+    )
+    base_submissions = FormSubmission.objects.filter(
+        models.Q(submitter=request.user)
+        | models.Q(
+            form_definition__in=reviewer_form_ids,
+            status__in=[
+                "submitted",
+                "pending_approval",
+                "approved",
+                "rejected",
+                "withdrawn",
+            ],
+        )
+    ).distinct()
 
     # --- Category counts (for the filter bar) ---
     raw_counts = (
@@ -542,14 +560,17 @@ def submission_detail(request, submission_id):
     """View submission details"""
     submission = get_object_or_404(FormSubmission, id=submission_id)
 
-    # Check permissions - user must be submitter, approver, or admin
+    # Check permissions - user must be submitter, approver, admin, or reviewer
+    form_def_early = submission.form_definition
+    is_reviewer = request.user.groups.filter(
+        id__in=form_def_early.reviewer_groups.all()
+    ).exists()
     can_view = (
         submission.submitter == request.user
         or request.user.is_superuser
         or user_can_approve(request.user, submission)
-        or request.user.groups.filter(
-            id__in=submission.form_definition.admin_groups.all()
-        ).exists()
+        or request.user.groups.filter(id__in=form_def_early.admin_groups.all()).exists()
+        or is_reviewer
     )
 
     if not can_view:
@@ -743,15 +764,17 @@ def submission_detail(request, submission_id):
         request.user.is_superuser
         or user_can_approve(request.user, submission)
         or request.user.groups.filter(id__in=form_def.admin_groups.all()).exists()
+        or is_reviewer
     )
 
     # Privacy: hide approval history from the submitter when configured.
-    # Approvers and admins always see the full history.
+    # Approvers, admins, and reviewers always see the full history.
     is_submitter_only = (
         submission.submitter == request.user
         and not request.user.is_superuser
         and not user_can_approve(request.user, submission)
         and not request.user.groups.filter(id__in=form_def.admin_groups.all()).exists()
+        and not is_reviewer
     )
     hide_approval_history = bool(
         workflow and workflow.hide_approval_history and is_submitter_only
@@ -1424,6 +1447,9 @@ def sub_workflow_detail(request, instance_id):
         or request.user.groups.filter(
             id__in=submission.form_definition.admin_groups.all()
         ).exists()
+        or request.user.groups.filter(
+            id__in=submission.form_definition.reviewer_groups.all()
+        ).exists()
     )
     if not can_view:
         messages.error(request, "You don't have permission to view this.")
@@ -1789,6 +1815,7 @@ def submission_pdf(request, submission_id):
         or request.user.is_superuser
         or user_can_approve(request.user, submission)
         or request.user.groups.filter(id__in=form_def.admin_groups.all()).exists()
+        or request.user.groups.filter(id__in=form_def.reviewer_groups.all()).exists()
     )
     if not can_view:
         return HttpResponseForbidden(
@@ -2555,6 +2582,9 @@ def bulk_export_submissions(request):
             or request.user.groups.filter(
                 id__in=sub.form_definition.admin_groups.all()
             ).exists()
+            or request.user.groups.filter(
+                id__in=sub.form_definition.reviewer_groups.all()
+            ).exists()
         )
         if can_view:
             allowed.append(sub)
@@ -2738,6 +2768,9 @@ def bulk_export_submissions_pdf(request):
             or request.user.groups.filter(
                 id__in=sub.form_definition.admin_groups.all()
             ).exists()
+            or request.user.groups.filter(
+                id__in=sub.form_definition.reviewer_groups.all()
+            ).exists()
         )
         if can_view:
             allowed.append(sub)
@@ -3145,7 +3178,24 @@ def my_submissions_ajax(request):
     category_slug = params.get("category", "").strip()
     form_slug = params.get("form", "").strip()
 
-    qs = FormSubmission.objects.filter(submitter=request.user)
+    reviewer_form_ids = (
+        FormDefinition.objects.filter(reviewer_groups__in=request.user.groups.all())
+        .values_list("id", flat=True)
+        .distinct()
+    )
+    qs = FormSubmission.objects.filter(
+        models.Q(submitter=request.user)
+        | models.Q(
+            form_definition__in=reviewer_form_ids,
+            status__in=[
+                "submitted",
+                "pending_approval",
+                "approved",
+                "rejected",
+                "withdrawn",
+            ],
+        )
+    ).distinct()
     records_total = qs.count()
 
     if category_slug:

pyproject.toml

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