Overview #

River is an open source workflow framework for Django which implements state machine algorithm on the fly.

The main goal is to be able to edit any workflow item on the fly. This means that all the elements in a workflow like states, transitions or authorizations rules are editable at any time without re-deploying the server application.

Requirements #

• Python (2.7, 3.4, 3.5, 3.6)
• Django (1.7, 1.8, 1.9, 1.10, 1.11, 2.0, 2.1)
• Django >= 2.0 is supported for Python >= 3.5
• Django == 1.7 is only supported for Python == 2.7 and Python == 3.4

Setup #

We install it using pip package installer:

$ pip install django-river

Update settings file and add river to INSTALLED_APPS.

INSTALLED_APPS=[
    ...
    "river"
    ...
]

Usage #

Let's create our first state machine in our models.py.

from django.db import models
from river.models.fields.state import StateField

class MyModel(models.Model):
    my_state_field = StateField()

Migrate the DB.

$ python manage.py migrate

We can create our states as one of them will be initial state on python manage.py shell. We can create transition approval metadata with our model (MyModel - my_state_field) information and authorization rules along with their priority on the admin page

my_model=MyModel.objects.get(....)
my_model.river.my_state_field.approve(as_user=transactioner_user)    
my_model.river.my_state_field.approve(
    as_user=transactioner_user,next_state=State.objects.get(
        label='re-opened'))

Example scenarios #

Simple Issue Tracking System #

Re-Open case #

Closed without Re-Open case #

Closed with Re-Open case #

References #

1. https://github.com/javrasya/django-river
2. https://django-river.readthedocs.io/en/latest/