Viewflow's quick start stops mid identifier and its changelog stops mid word
Reusable workflow library for Django
At a glance
- What is it?
- A Django library for BPMN style business workflows, shipped as an AGPL core package and a commercial PRO package. Release 2.4.0 adds database backed timers, boundary events and compensation, and two passages of the README stop before they finish.
- Who is it for?
- Viewflow earns its place in a Django shop that has to draw BPMN diagrams and hand the same flow to non developers, and the 2.4.0 notes are the most concrete part of the documentation, since they name nodes, fields and firing paths instead of adjectives. Four things to check before you commit.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 18 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- viewflow/viewflow2,873 ★ · -4
| Repository | 2026-10-04 | 2026-11-15 |
|---|---|---|
| viewflow/viewflow | 2.9k | 2.9k |
-4 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two distributions, and the PRO install line carries a placeholder licence id
Viewflow ships twice. Viewflow Core is the open source library with base classes, installed with `pip install django-viewflow`. Viewflow PRO is the full package with ready to use features and third party integrations, and its commercial license allows private forks and modifications. The PRO install line is the one with a decision in it:
pip install django-viewflow-pro --extra-index-url https://pypi.viewflow.io/<licence_id>/simple/The `<licence_id>` segment is a placeholder as printed, so the command cannot run until you substitute the id from your commercial license, and that extra index URL is what makes the package resolvable in the first place. Note the gap of two spaces between the package name and the flag, which is how the README has it.
Licensing is the other half of the split. Core is AGPL v3 with Additional Permissions described in `LICENSE_EXCEPTION`, and the README states that combination allows commercial use and distribution. The root directory carries four license files for this: `LICENSE`, `LICENSE.django`, `LICENSE_EXCEPTION` and `COMM-LICENSE`, the last holding the commercial terms. setup.py declares `license="AGPL"`, and its summary line is a different sentence from the repository description: Reusable library to build business applications fast.
The pizza flow stops inside the deliver step, halfway through an identifier
The quick start walks through four steps: a process model, flows.py, URLs, then migrations. The first is complete. The second is not. The flow class defines start with CreateProcessView over customer_name, address and toppings, then bake with UpdateProcessView over baking_time, and the third step opens like this:
deliver = flow.View(
UpdThat is where the code in the README ends. The identifier `Upd` is cut in half, no closing parenthesis appears, and the deliver step has no `.Next()` of its own even though bake chains to it. The section after it carries on regardless, registering `FlowAppViewset(PizzaFlow, icon="local_pizza")` and pointing a `Site` at a title, which means the URL layer expects a flow class with a finished set of steps. Anyone who copies the quick start gets a syntax error at the third step. The runnable version the README points to is the demo/helloworld directory, so that is the file to copy from.
Process data goes into jsonstore fields that ship as their own distribution
Step one asks for a model derived from `Process` and fills it with `jsonstore` fields, described as a way to store process data without extra database joins:
from viewflow import jsonstore
from viewflow.workflow.models import Process
class PizzaOrder(Process):
customer_name = jsonstore.CharField(max_length=250)
address = jsonstore.TextField()
toppings = jsonstore.TextField()
tips_received = jsonstore.IntegerField(default=0)
baking_time = jsonstore.IntegerField(default=10)
class Meta:
proxy = TrueThe pizza model uses a bounded char field for the customer name, two text fields for address and toppings, and integer fields for tips and baking time, the latter defaulting to 10. It declares `proxy = True` in Meta, so the process row is a proxy over the base table rather than a table of its own.
Those field types are not part of this distribution. setup.py carries the comment that `viewflow.jsonstore` is a re-export of another package, that 0.5.1 was the deprecated merged in release and should be pinned above it, then requires `django-jsonstore>=26.7.0`. Two version schemes meet inside one install_requires: viewflow sits at 2.4.0 while its field package counts on a calendar. Application code keeps the single import `from viewflow import jsonstore` whichever distribution supplies the fields.
Timers live on the task row, so a deadline outlives the broker
Release 2.4.0, dated 2026-07-30, adds database backed `flow.Timer` and `flow.StartTimer(interval=...)` nodes. The due moment goes on the task row in a new `Task.scheduled` field, and the release notes say a migration is included, so the timer survives a broker restart, which they set against `celery.Timer`. Firing is not left to the queue either: due timers come from the `workflow_timers` management command or from the `workflow_fire_timers` celery beat task.
That is a move of state rather than a new feature. A broker held timer exists only while the broker does, so a restart drops it and the deadline goes with it. Here the deadline is a column on a row the workflow already owns, and a periodic process still has to run somewhere to notice that it has passed. The gain is durability, and the cost is a scheduler dependency, whether that is a cron entry for the management command or a beat schedule. The README does not say which of the two to run in production.
Boundary events attach to the host task, declared before .Next()
Boundary events are declared on the host task before `.Next()`. `.OnTimeout(delay, then)` covers deadlines and escalation, and `.OnError(then, code=...)` catches a background task failure. Both interrupt by default, and `interrupting=False` starts a parallel path instead, which is how a timeout becomes a warning rather than a cancel.
Two end nodes sit at the far edge of the chain. `flow.TerminateEnd()` cancels all other active tasks and finishes the process, and `flow.ErrorEnd(code)` fails it. Inside a subprocess, `ErrorEnd` marks the parent task `ERROR`, so the parent's own `.OnError(..., code=...)` boundary catches it. That composition is the part worth planning around: the failure does not get handled where it happens, it travels up to a boundary on the parent, and the `code` argument is the only thing connecting the two. A handler written against a code that nothing ever raises will sit there and never fire, and the release notes do not list the codes that are raised by the library itself.
Compensation replays undo handlers in reverse completion order, each at most once
`.CompensateWith(this.handler)` registers an undo handler on any task, and `flow.CompensateThrow()` runs the handlers of completed tasks in reverse completion order, each at most once. Reverse order is the part that matters once real records are involved: the last thing that happened is the first thing undone, and the at most once rule keeps a retried compensation from double refunding.
The same release adds the intermediate events. `MessageCatch` pairs with `MessageThrow`, and `SignalCatch` with `SignalThrow`, where one throw releases every armed catch across processes and flow classes, which makes SignalThrow a broadcast rather than a targeted send. `EscalationThrow` pairs with a non interrupting `.OnEscalation` boundary, and `ConditionalCatch` waits until a condition over process data holds, so a step can park itself until the jsonstore fields say it may continue.
The BPMN export claims schema validation the changelog never finishes describing
The 2.4.0 notes call it the largest feature release of the 2.x line, with complete BPMN 2.0 node coverage, document oriented JSON Store fields, and a drop in replacement for django-fsm. New task types come with it: `flow.SendHandle`, `flow.BusinessRule`, and `flow.ManualTask` for work done outside any system, marked done with a no field confirmation. `NSubprocess(..., sequential=True)` runs one child process at a time.
The export bullet is where the changelog stops. It says exported files validate against the official OMG schema and open in bpmn.io and Camunda Modeler, names `Switch`, then writes `Subpro` and stops inside the second word. So the two node types named at the cut are the ones whose export behavior is left undescribed, in the same entry that claims complete node coverage. The older documentation is still reachable at v1-docs.viewflow.io if you need to see what the 1.x line exported, and the live documentation sits at docs.viewflow.io.
A Django library that carries a Node toolchain, and scripts that point outside the tree
The root holds `package.json`, `package-lock.json`, `tsconfig.json`, `tsconfig.node.json` and `vite.config.mts` next to `setup.py`, `setup.cfg`, `MANIFEST.in`, `tox.ini` and `manage.py`. Two details in the JavaScript manifest are worth a look. TypeScript is listed under `dependencies` rather than devDependencies, at `^6.0.3`, while the Solid compiler chain, meaning solid-js, solid-element, vite-plugin-solid and babel-preset-solid, sits in devDependencies and the runtime side carries Turbo, material-components-web and @material/web. The frontend also pulls swagger-ui-dist for API docs, vanilla-jsoneditor, which fits the document oriented store fields, vis-network for graph drawing, trix for rich text and shepherd.js for guided tours.
The scripts reach outside the repository. `python-integration-tests` sets `DATABASE_URL=postgres://viewflow:viewflow@localhost/viewflow` and `REDIS_CACHE_URL=redis://127.0.0.1:6379/1` before running tox, so the suite wants a Postgres and a Redis on fixed local addresses with those credentials. `workflow101-celery` and `workflow101-server` both invoke `cookbook/workflow101/manage.py`, and no cookbook directory exists in this tree, so the samples are a separate checkout.
Editorial conclusion
Viewflow earns its place in a Django shop that has to draw BPMN diagrams and hand the same flow to non developers, and the 2.4.0 notes are the most concrete part of the documentation, since they name nodes, fields and firing paths instead of adjectives. Four things to check before you commit. The PRO package is not on PyPI under its own name; the index URL carries a `<licence_id>` placeholder that has to be replaced, so budget for a sales conversation before the install works. The README's own quick start is incomplete, so use the demo/helloworld directory as your starting file. The integration suite wants a Postgres and a Redis on fixed local addresses, and two of the npm scripts invoke a cookbook directory that is a separate repository. And decide the license question early, because Core is AGPL v3 with Additional Permissions while private forks live in the commercial package.
Frequently asked questions
What does Viewflow require before it installs?
Python 3.10 or newer and Django 4.2 or newer. The core install line is `pip install django-viewflow`, and settings.py needs `viewflow` plus `viewflow.workflow` in INSTALLED_APPS when workflows are used. setup.py sets python_requires to >=3.10 and its classifiers cover Django 4.2 through 6.0 and Python 3.10 through 3.13.
How is the Viewflow PRO package installed?
With `pip install django-viewflow-pro --extra-index-url https://pypi.viewflow.io/<licence_id>/simple/`, where the licence id in the URL comes from the commercial license. The commercial terms live in COMM-LICENSE at the repository root and are described as allowing private forks and modifications of Viewflow.
What does Viewflow 2.4.0 say about django-fsm?
Release 2.4.0, dated 2026-07-30, is described as a drop-in replacement for django-fsm, alongside complete BPMN 2.0 node coverage and document-oriented JSON Store fields. The keywords in setup.py still carry fsm and bpmn.
Where are Viewflow timer due times kept?
On the task row, in the new Task.scheduled field, with a migration included in the release. Due timers fire from the workflow_timers management command or the workflow_fire_timers celery beat task, and the notes contrast this with celery.Timer, which does not survive a broker restart.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/viewflow-viewflow)Star history chart for your README
[](https://hysenlabs.com/projects/viewflow-viewflow)Was this useful?