A Django workflow engine runs a multi-step business process inside your Django application. It tracks where each process is, decides what happens next, and holds the state between steps — approvals, hand-offs, parallel tasks, and long waits for a human or an external event.
Plain Django models and views handle one request at a time. A workflow engine handles the flow across many requests, days, and people. This guide covers when you need one, how it compares to the alternatives, and how to add it.
Not every app does. Reach for one when the process, not the form, is the hard part. Three questions decide it:
If you answered yes to any of these, hand-rolled status fields and if
branches will sprawl fast. That is the job a workflow engine removes.
“Workflow” covers three different Django tools. Picking the wrong one is the common mistake.
| Tool | Use it for | Example |
|---|---|---|
| State machine (FSM) | One object moving through states, guarded transitions | An invoice: draft → sent → paid |
| Workflow engine (BPMN) | Multi-step processes with people, branches, and waits | A loan application across three departments |
| Task queue (Celery) | Running background jobs off the request cycle | Sending email, resizing an image |
They compose. Viewflow ships the first two — viewflow.fsm for state machines and viewflow.workflow for BPMN — and calls Celery for the background jobs a workflow step needs.
Use a state machine when a single object walks through a fixed set of states, and each transition needs only a rule. It is a light layer on one model. See viewflow.fsm.
Use a workflow engine when the process spans several tasks, branches on data, runs steps in parallel, or waits for people and events. This is where BPMN earns its keep: it models gateways, parallel splits, and joins that a state machine cannot express.
The line is parallelism and hand-off. One object changing state is a machine. Work moving between actors is a workflow.
Viewflow is an open-source workflow engine for Django. You define the process
as a Flow class in Python, and Viewflow runs it — persisting state,
assigning tasks, and driving the branches.
from viewflow import this
from viewflow.workflow import flow
from . import models, views
class LeaveRequestFlow(flow.Flow):
process_class = models.LeaveRequestProcess
start = flow.Start(views.RequestView.as_view()).Next(this.approve)
approve = flow.View(views.ApproveView.as_view()).Next(this.check)
check = (
flow.If(cond=lambda activation: activation.process.approved)
.Then(this.notify)
.Else(this.start)
)
notify = flow.Function(this.send_email).Next(this.end)
end = flow.End()
def send_email(self, activation):
...
Each node is a step. Gateways route the process; the engine keeps the state in the database, so a request can sit for a week and pick up exactly where it stopped.
A Django workflow engine is a library that runs multi-step business processes inside a Django project. It records the state of each running process, decides the next step, assigns tasks to users, and survives restarts because the state lives in the database.
Use one once a process has more than a couple of steps, branches on data, waits
for people or events, or runs steps in parallel. Status fields and if
branches work for simple cases but sprawl into unmaintainable code as the
process grows.
A state machine guards the transitions of one object through a set of states. A workflow engine coordinates a whole process — several tasks, branches, parallel work, and waits — across many objects and people. Viewflow provides both.
Yes. Viewflow is an open-source BPMN workflow engine for Django. You define the process as Python code and run it in production with parallel tasks, persistence, and Celery. The PRO edition adds a visual frontend.