v0.20.0: Customizable sub-workflow section labels

- Add section_label field to SubWorkflowDefinition for user-facing
  heading (e.g. 'Payment Approvals' instead of 'Sub-Workflow Approvals')
- Falls back to sub-workflow form name, then 'Additional Approvals'
- Add section_label to workflow builder properties panel, load/save,
  and sync API
- Use list-check icon instead of diagram-2 for cleaner end-user UX

Author: matteius

django_forms_workflows/migrations/0042_add_sub_workflow_section_label.py

@@ -0,0 +1,22 @@
+# Generated by Django 5.2.7 on 2026-03-12 20:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0041_remove_deprecated_fields"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="subworkflowdefinition",
+            name="section_label",
+            field=models.CharField(
+                blank=True,
+                help_text="Heading shown to end users in the approval history (e.g. 'Payment Approvals'). If blank, defaults to the sub-workflow form name.",
+                max_length=100,
+            ),
+        ),
+    ]

django_forms_workflows/models.py

@@ -2126,6 +2126,12 @@ class SubWorkflowDefinition(models.Model):
         max_length=100,
         help_text="Form field name whose integer value determines how many sub-workflows to spawn (e.g. 'number_of_payments')",
     )
+    section_label = models.CharField(
+        max_length=100,
+        blank=True,
+        help_text="Heading shown to end users in the approval history (e.g. 'Payment Approvals'). "
+        "If blank, defaults to the sub-workflow form name.",
+    )
     label_template = models.CharField(
         max_length=100,
         default="Sub-workflow {index}",

django_forms_workflows/static/django_forms_workflows/js/workflow-builder.js

@@ -378,6 +378,7 @@ class WorkflowBuilder {
                     sub_workflow_def_id: null,
                     sub_workflow_id: null,
                     sub_workflow_name: '',
+                    section_label: '',
                     count_field: '',
                     label_template: 'Sub-workflow {index}',
                     trigger: 'on_approval',
@@ -957,6 +958,15 @@ class WorkflowBuilder {
                 <small class="text-muted">The workflow definition used for each sub-workflow instance</small>
             </div>
 
+            <div class="mb-3">
+                <label class="form-label"><strong>Section Label</strong></label>
+                <input type="text" class="form-control" name="section_label"
+                       value="${this.escapeHtml(data.section_label || '')}"
+                       placeholder="e.g. Payment Approvals"
+                       onchange="workflowBuilder.updateSubWorkflowConfig('${node.id}')" />
+                <small class="text-muted">Heading shown to end users in approval history. If blank, uses the workflow name.</small>
+            </div>
+
             <div class="mb-3">
                 <label class="form-label"><strong>Count Field</strong></label>
                 <select class="form-select" name="count_field"
@@ -1027,6 +1037,7 @@ class WorkflowBuilder {
         const selectedOption = subWfSelect.selectedOptions[0];
         node.data.sub_workflow_name = selectedOption && selectedOption.value ? selectedOption.text : '';
 
+        node.data.section_label = container.querySelector('input[name="section_label"]').value;
         node.data.count_field = container.querySelector('select[name="count_field"]').value;
         node.data.label_template = container.querySelector('input[name="label_template"]').value;
         node.data.trigger = container.querySelector('select[name="trigger"]').value;

django_forms_workflows/sync_api.py

@@ -241,6 +241,7 @@ def _serialize_sub_workflow_config(swc):
         return None
     return {
         "sub_workflow_form_slug": swc.sub_workflow.form_definition.slug,
+        "section_label": swc.section_label,
         "count_field": swc.count_field,
         "label_template": swc.label_template,
         "trigger": swc.trigger,
@@ -586,6 +587,7 @@ def import_form(form_data, conflict="update", category_cache=None):
                     parent_workflow=wf,
                     defaults={
                         "sub_workflow": sub_wf_form.workflow,
+                        "section_label": sub_wf_data.get("section_label", ""),
                         "count_field": sub_wf_data.get("count_field", ""),
                         "label_template": sub_wf_data.get(
                             "label_template", "Sub-workflow {index}"

django_forms_workflows/templates/django_forms_workflows/submission_detail.html

@@ -242,9 +242,11 @@ <h5 class="mb-3"><i class="bi bi-diagram-3"></i> Approval History</h5>
         {% endfor %}
 
         {% if sub_workflow_groups %}
-        {# ---- Sub-workflow tasks (detached child workflow stages) ---- #}
-        <h5 class="mb-3 mt-4"><i class="bi bi-diagram-2"></i> Sub-Workflow Approvals</h5>
+        {# ---- Sub-workflow tasks ---- #}
         {% for stage in sub_workflow_groups %}
+        {% if forloop.first %}
+        <h5 class="mb-3 mt-4"><i class="bi bi-list-check"></i> {{ stage.section_label|default:"Additional Approvals" }}</h5>
+        {% endif %}
         <div class="card mb-3
             {% if stage.rejected_count > 0 %}border-danger
             {% elif stage.approved_count == stage.total_count and stage.total_count > 0 %}border-success

django_forms_workflows/views.py

@@ -593,6 +593,17 @@ def submission_detail(request, submission_id):
             stage_groups = sorted(parent_groups.values(), key=lambda x: x["number"])
         if sub_groups:
             sub_workflow_groups = sorted(sub_groups.values(), key=lambda x: x["number"])
+            # Resolve the user-facing section label from SubWorkflowDefinition
+            if workflow:
+                sub_wf_config = getattr(workflow, "sub_workflow_config", None)
+                if sub_wf_config and sub_wf_config.section_label:
+                    for sg in sub_workflow_groups:
+                        sg["section_label"] = sub_wf_config.section_label
+                elif sub_wf_config:
+                    # Fall back to the sub-workflow's form definition name
+                    sg_name = sub_wf_config.sub_workflow.form_definition.name
+                    for sg in sub_workflow_groups:
+                        sg["section_label"] = sg_name
 
     # Resolve fresh presigned URLs for any file-upload fields
     form_data = _resolve_form_data_urls(submission.form_data)

django_forms_workflows/workflow_builder_views.py

@@ -450,6 +450,7 @@ def convert_workflow_to_visual(workflow, form_definition):
                 "sub_workflow_def_id": sub_wf_config.id,
                 "sub_workflow_id": sub_wf.form_definition_id,
                 "sub_workflow_name": sub_wf.form_definition.name,
+                "section_label": sub_wf_config.section_label,
                 "count_field": sub_wf_config.count_field,
                 "label_template": sub_wf_config.label_template,
                 "trigger": sub_wf_config.trigger,
@@ -670,6 +671,7 @@ def convert_visual_to_workflow(workflow_data, form_definition):
             if target_workflow:
                 sw_fields = {
                     "sub_workflow": target_workflow,
+                    "section_label": sw_data.get("section_label", ""),
                     "count_field": sw_data.get("count_field", ""),
                     "label_template": sw_data.get(
                         "label_template", "Sub-workflow {index}"

pyproject.toml

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