Skip to main content

Module workflow

Module workflow 

Source
Expand description

Multi-step approval workflows.

Editors compose a Workflow from ordered WorkflowTasks. When they submit a page for review, a WorkflowState row tracks “where in the workflow this page is right now,” and a TaskState row records the verdict on each step.

This module holds the data model + admin CRUD; the page-editor UI (Submit / Approve / Reject buttons), notifications and reapproval-on-edit build on it.

§Shape

Workflow ─< WorkflowTask (ordered by sort_order)
    │
    └─< WorkflowState (one per page-in-flight)
            │
            └─< TaskState (one per step decision)

§States

WorkflowState.status is one of: in_progress, approved, needs_changes, cancelled. TaskState.status is one of: in_progress, approved, rejected, skipped. The string representation is stable on disk so future ALTERs don’t break existing rows.

Structs§

TaskState
Workflow
WorkflowState
WorkflowTask

Enums§

ApproveOutcome
Outcome of approving the current task. Advanced means the workflow moved to the next task; Finished means every task approved and the workflow ended (the caller flips the page to Published).
TaskStatus
WorkflowStatus

Functions§

active_state_for_page
Look up the active (non-finished, non-cancelled) WorkflowState for a page. Returns at most one row — a page is in at most one active workflow at a time. Historical rows (approved / cancelled) are filtered out.
approve_current
Approve the current task on a WorkflowState. Marks the in-flight TaskState Approved, advances to the next task (or finishes the workflow when no next task exists).
cancel
Cancel an in-flight workflow. Marks the WorkflowState Cancelled and any in-progress TaskState Skipped. Used when an editor pulls the page out of review entirely.
find_by_name
Look up a workflow by its (case-sensitive) name. The name acts as the slug returned from PageTypeHandler::workflow_slug(). Only returns active workflows; inactive ones are treated as missing so editors can disable a workflow without invalidating every page-type binding.
has_prior_approval
True when this page has been through a workflow that finished approved (i.e. it’s a published-via-workflow page). Editors with Workflow.require_reapproval_on_edit set use this signal to decide whether the next edit kicks off a new review cycle.
history_for_page
Every decision on the page across all its review rounds, oldest first — a rejection’s reason stays visible after the resubmission.
latest_state_for_page
The page’s most recent review round, whatever its outcome.
page_types_using
The page types chosen in the admin to go through the workflow name.
rebind_page_types
Point the page types that use workflow old at its new name new (page types store the name). Returns how many moved.
reject_current
Reject the current task. Flips the TaskState to Rejected and the WorkflowState to NeedsChanges. The submitter can edit and re-submit; the workflow restarts from the first task on next submit. Returns false, changing nothing, when the step was already decided.
review_workflow_for_type
The active workflow pages of page_type_id go through before they are published, if any: the type’s handler slug or the one chosen in the admin, resolved to an active workflow with at least one step. Pages of such a type go live only through review — except for superusers (the callers check).
submit_for_review
Submit a page for review: create a new WorkflowState pinned to the first task + an in_progress TaskState. Caller must have already verified the page is in Draft or NeedsChanges state and the workflow has at least one task.
tasks_for
Fetch the ordered task list for a workflow id.