State-Based Workflow Reference

API, schema and command reference for the state-based (workflow_kind='state_based') workflow engine. Part of the Workflow series. Entry point: State-Based Workflows.

Table of Contents

1. Choices
2. Model Field Reference
3. Service Reference
4. Validation Rules S1–S20
5. design_data JSON Schema
6. URLs and Views
7. WorkflowMixin Reference
8. History Context
9. Management Commands
10. Settings and Migrations
11. Error Types
12. See Also
13. A Note on Testing

Choices

All defined in enezaworkflowengine/models/choices.py.

WorkflowExecutionType — choices.py:5

WorkflowKind — choices.py:14

StateLifecycle — choices.py:18

Used by both WorkflowInstance.state_status and WorkflowBranch.status.

WorkflowActionType — choices.py:23

creation, assignment, approval, precondition, notification, status_change, resubmission, completion. State-based history uses creation, assignment, status_change, completion and notification.

Backward-compatibility alias: WorflowActionType = WorkflowActionType (choices.py:34).

Model Field Reference

WorkflowTemplate — models/workflowtemplate.py:15

StepTemplate — workflowtemplate.py:83

StateTransition — workflowtemplate.py:127

Unique together: (workflowtemplate, source_state, target_state).

WorkflowInstance — workflowtemplate.py:165

WorkflowBranch — models/workflowinstance.py:70

WorkflowStepInstance.branch — workflowinstance.py:43

related_name='step_instances'; audit link from the executed step back to its token.

WorkflowApproverAction — workflowinstance.py:141

Unique constraint unique_approver_per_step_instance on (step_instance, approver).

WorkflowTransaction — workflowinstance.py:197

Service Reference

enezaworkflowengine/services/state_workflow.py

transition_display_name rules (:94-127): a state is named by its label or node name; a transition into a fork is named after the states the fork activates; a transition into a condition is named after its true/false destinations; a transition into a join is named after the node the join continues to; structural names are never shown. Depth is capped at 3, and duplicate names are collapsed.

enezaworkflowengine/services/state_choices.py — State Choices Resolution

Precedence chain, summarised:

flowchart LR
    A["WORKFLOW_STATE_CHOICES<br/>registry entry for workflowname"] -->|found| R["(value, label) list"]
    A -->|not found| B["WorkflowTemplate.state_choices_path"]
    B -->|found| R
    B -->|not found| C["discover_document_state_choices()<br/>any workflowstate field choices"]
    C --> R

Only explicit_state_choices_path is used by the validator for the S7 check (state_template_validator.py:238-244); the designer uses template_state_choices.

enezaworkflowengine/services/workflow_submission.py

enezaworkflowengine/services/workflow_versioning.py

enezaworkflowengine/services/workflow_template_validator.py

Validation Rules S1–S20

Source: enezaworkflowengine/services/state_template_validator.py. validate_state_workflow_template returns a list[str]; activation runs it through validate_template and refuses to activate when the list is non-empty.

Notes:

• S6 also tightens S2/S3: a START or END node carrying a state code is reported under S6.
• S9 also covers START/END assignees: any of them having assignees is reported under S9.
• S16 is evaluated with state_assignees(), so "listed but inactive" does not satisfy it.
• Rule numbers in the reference docstring (:13-49) are authoritative; a few checks are physically grouped by node kind rather than by rule number.

design_data JSON Schema

WorkflowTemplate.design_data stores the last designer snapshot. The save view writes exactly what the designer sent; the load view enriches it before returning it.

Stored shape

{
  "nodes": [
    {
      "id": "step-1",
      "type": "state",
      "x": 360,
      "y": 60,
      "name": "Reported",
      "zIndex": 1,
      "stateCode": "reported",
      "approvalThreshold": "majority",
      "stateAssignmentTemplateCode": "STATE_ASSIGNED",
      "notifyOriginatorOnAssignment": true,
      "assigneeUserIds": [1, 2],
      "assigneeGroupIds": [3]
    }
  ],
  "connections": [
    {
      "id": "conn-1",
      "source": "step-1",
      "target": "step-2",
      "type": "transition",
      "label": "Triage"
    },
    {
      "id": "conn-2",
      "source": "condition-1",
      "target": "step-3",
      "type": "true",
      "conditionResult": "true"
    }
  ]
}

nodes[] keys

connections[] keys

Loader enrichment

WorkflowDesignerLoadView (views/worflow_design.py:484-492) adds:

The stored snapshot is bypassed when _design_data_matches_steps finds it stale (worflow_design.py:281-316); see the architecture guide's Designer Load/Save Pipeline.

URLs and Views

Registered in enezaworkflowengine/urls.py (namespaced enezaworkflowengine).

Also relevant: workflow_history_ui (workflow/<uuid:instance_id>/history/ui/), used by the View History menu item.

workflow_state_transition_picker (GET)

• Unauthenticated → JSON {'error': 'Authentication required'}, status 401.
• Unknown instance/branch → 404 (get_object_or_404).
• Optional query parameter list_url is passed through to the template.
• Renders workflow_instance/partials/state_transition_form.html with:
• workflow_instance, branch, current_state
• transitions (raw StateTransition rows)
• transition_options — [{'id': target.id, 'name': transition_display_name(t), 'is_end': <bool>}]
• list_url, can_transition (user_can_transition(current_state, request.user, document))
• The form posts target_state, comment and list_url to workflow_state_transition.

workflow_state_transition (POST)

Request fields: target_state (UUID, required), comment (optional), list_url (optional). The view is csrf_exempt at the dispatch level; the picker's form still includes {% csrf_token %}.

Success responses by request shape:

Error handling:

• Missing/invalid target_state → JSON 400.
• WorkflowTransitionError subclass → status e.http_status; JSON {'error': str(e)} or an HTMX HX-Trigger payload with variant: "error" when HX-Request is set.
• Any other exception → JSON {'error': 'An unexpected error occurred'}, status 500 (logged with traceback).

WorkflowMixin Reference

Source: enezaframework/views/mixins.py.

State-based can_submit_to_workflow gate — :1229-1241

Returns (False, reason) in order when: the model lacks workflowstate; workflow_template_name is unset; no active template resolves; an active instance already exists; workflowstate is non-empty. Returns (True, '') otherwise. Note that the approval-engine draft-status requirement does not apply.

State-based get_workflow_menu_items — :1342-1381

1. Always appends View History → workflow_history_ui.
2. When workflow_instance.state_status == 'active', iterates get_transitionable_branches() and appends one item per branch: - name: Move to -> <transition_display_name(t)> when the state has exactly one allowed transition, otherwise Move to -> .... - url: workflow_state_transition_picker with (instance.id, branch.id). - method: GET, modal: True, hx_vals: {"list_url": "<app_name>:<list_view_name>"}.
3. Returns after the state branch; the approval action items are not produced for state-based documents.

History Context

WorkflowHistoryMainView (views/workflow_api.py:665-705) adds to the template context:

history_shell.html renders state_summary (falling back to state_status_display, then status_display) and, when is_state_based and active_branches, lists every active branch with its effective_assignees (workflow_instance/partials/history_shell.html:10-50).

Management Commands

All under enezaworkflowengine/management/commands/.

create_sample_state_workflow

Builds a ready-to-edit state-based template with a Fork/Join (START → reported → triage → assessment → fork → investigation/containment → join → notification → remediation → validation → closed/cancelled → END).

python manage.py create_sample_state_workflow
python manage.py create_sample_state_workflow --workflowname IncidentWorkflow --reset
python manage.py create_sample_state_workflow --entity ACME --activate --assignee admin

assign_state_users

Adds (or replaces) users/groups on every state of a template. The quickest way to make a workflow testable.

python manage.py assign_state_users --workflowname IncidentWorkflow --username admin
python manage.py assign_state_users --workflowname IncidentWorkflow --group Managers --replace

check_workflow_state_choices

Reports how the designer resolves state choices: the settings path, the registry, models with a workflowstate field, the discovery result, and per-template registry_path / explicit_path / choices.

python manage.py check_workflow_state_choices --workflowname IncidentWorkflow
python manage.py check_workflow_state_choices --json

workflow_instance_status

Prints instances with their kind, state_status, document workflowstate, every branch (id, status, state, fork_scope), the resolved assignees and — with --user — whether that user can move each state. Warns when an active instance has no active branches.

python manage.py workflow_instance_status --workflowname IncidentWorkflow --user admin

workflow_task_status

Shows recent django_tasks DBTaskResult rows (workflow tasks only unless --all), including status, queue, args and the last traceback line for failures, plus a status count.

python manage.py workflow_task_status --all --limit 50

delete_workflow_template

Deletes a template (all versions by default) and everything attached to it in the correct order: instances (cascading to branches/steps/transactions) → transitions → steps → template. PROTECT FKs make a plain delete fail when runtime data exists.

python manage.py delete_workflow_template --workflowname IncidentWorkflow --yes

Settings and Migrations

Settings

Migrations

Error Types

Approval-engine siblings (StepHandlerNotFoundError, ConditionEvaluationError, ApproverAssignmentError, StepLockedError, WorkflowNotActiveError) share the same base class and are not raised by the state engine.

See Also

• State-Based Workflows — overview and quick start.
• State-Based Workflow Architecture — components, lifecycle and internals.
• State-Based Workflow Troubleshooting — symptom → cause → diagnostic → fix.
• Workflow — Developer Index

A Note on Testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the output described in this guide.