This tutorial shows how to create basic Hello World application where one person starts “Hello, world” request, another one approves it, and when approved the request sent out.
To follow the tutorial, you need to use Python>=3.4, but since 1.0 django-viewflow works also with Python 2.7
Let’s create a fresh virtual environment for the demo project. In an empty directory run the following commands.
python3 -m venv env source env/bin/activate
At first install viewflow package and django-material to enable pre-build frontend interface.
pip install django django-material django-viewflow
In the current directory, scaffold a new django project:
django-admin startproject demo .
Create an app:
./manage.py startapp helloworld
Now you should have following file structure:
demo/ ├── asgi.py ├── __init__.py ├── settings.py ├── urls.py └── wsgi.py helloworld ├── admin.py ├── apps.py ├── __init__.py ├── migrations │ └── __init__.py ├── models.py ├── tests.py └── views.py manage.py
Open the demo/settings.py and add viewflow and demo.helloworld into INSTALLED_APPS setting
INSTALLED_APPS = [ ... 'viewflow', 'helloworld', ]
Open helloworld/models.py file and define a process model with text and approved fields, to capture the process state during execution.
from django.db import models from viewflow.models import Process class HelloWorldProcess(Process): text = models.CharField(max_length=150) approved = models.BooleanField(default=False)
Let’s take a look at the flow BPMN diagram. We are going to map each shape to the corresponding flow node definition.
Open the demo/helloworld/flows.py file and define:
from viewflow import flow from viewflow.base import this, Flow from viewflow.flow.views import CreateProcessView, UpdateProcessView from .models import HelloWorldProcess class HelloWorldFlow(Flow): process_class = HelloWorldProcess start = ( flow.Start( CreateProcessView, fields=["text"] ).Permission( auto_create=True ).Next(this.approve) ) approve = ( flow.View( UpdateProcessView, fields=["approved"] ).Permission( auto_create=True ).Next(this.check_approve) ) check_approve = ( flow.If(lambda activation: activation.process.approved) .Then(this.send) .Else(this.end) ) send = ( flow.Handler( this.send_hello_world_request ).Next(this.end) ) end = flow.End() def send_hello_world_request(self, activation): print(activation.process.text)
Viewflow proceeds all application flows from the flows.py file.
Each flow is a Python class that subclasses viewflow.base.Flow
Each attribute represents a flow task
To connect flow tasks altogether, the special this object can be used to make forward references
flow.Start represents a task that is performed by a person in a Django view. For the tutorial purpose, we use built-in CreateProcessView. But any class or functional based view annotated with @flow.flow_start_view decorator can be used here.
flow.Task is a user task for an existing process.
Tasks execution rights could be restricted by the Django permission system. You can specify a permission name here or set auto_create=True that leads to creating special permission for the task. In our case, we will have helloworld.can_start_helloworldprocess and helloworld.can_approve_helloworldprocess permissions created. In addition, two standard permissions would be created helloworld.view_helloworldprocess and helloworld.manage_helloworldprocess for flow list and administrative actions views.
flow.If is the simple exclusive gateway. It selects an outcome depending on a callable result. For the input, callable gets a task activation - an object that handles current task processing logic, and that has an activation.process and activation.task fields initialized with the corresponding model instances.
If the request is approved, the flow.Handler will be executed. flow.Handler is the task performed by synchronous Python code call. Here a this reference could be used to point to a flow instance method, or any Python callable.
flow.End finalizes the process and marks it as completed.
Here we could start to write a lot of templates for flow list, actions, task details and task execution views. Viewflow comes with pre-build frontend module, which provides ready to use UI, let’s just enable it.
First, adds the required apps to the INSTALLED_APPS
INSTALLED_APPS = [ ... 'material', 'material.frontend', 'viewflow', 'viewflow.frontend', 'demo.helloworld', ]
Add frontend URLs into global URL conf module at demo/urls.py
from django.urls import include, path from django.views import generic from material.frontend import urls as frontend_urls urlpatterns = [ path(r'', generic.RedirectView.as_view(url='/workflow/', permanent=False)), path(r'', include(frontend_urls)), ]
At the last step, register our flow in the viewflow.frontend.
from viewflow import frontend @frontend.register class HelloWorldFlow(Flow): ...
Run and explore¶
Create migrations for the helloworld app.
./manage.py makemigrations helloworld
Create an admin user to initial login
Run the server
Go to http://127.0.0.1:8000 and see the viewflow in action!
Themes - frontend colors customization