Guide to Managing Finite State Machine Using Django FSM | HashedIn

A Guide to Managing Finite State Machine Using Django FSM

Technology - 30 May 2017
Nagesh Dhope

Imagine an application like JIRA with complex workflow. Building such application needs a support for managing finite state machine.

Well, if you are building your application with Django, Django FSM provides you out of the box support for managing finite state machine.

Let’s assume that our application has the following workflow for a Task.


Basic model for a Task is as follows:

Now, let’s see how can we build this using Django FSM.

Installation Process

Or, you can install latest git version

Define States and State Field in Model

We need to define an FSMState field. On this field, django FSM will perform transitions. We can define FSMState field using FSMField.

We defined FSMState field but we didn’t associate any states to that field. We can do that as follows:

Creating Transitions

Django FSM provides a decorator called transition. Once you decorate model method with transitiondecorator, you can call model method to perform transition on each object of a model.

Source parameter accepts a list of states, or an individual state. You can use * for source, to allow switching to the target from any state. The field parameter accepts both the string attribute name or the actual field instance.

Changing State of Object

To change state of an object, call model method which is decorated with transition decorator.

If start() gets executed successfully without raising any exceptions, state of task object will get updated but it will not be saved into a database. Call save() method to save the object in database.

Adding Conditions on Transitions

There might be situations where in you want a check of certain condition prior to performing transition. You do so in django FSM using Conditions parameter of transition decorator. Conditions must be a list of functions taking one argument(model instance). The function/method must return True or False.

A condition method can be a normal python function.

or it can be a model method.

Use conditons like this:

Handling Exception in Transition Method

Django FSM provides a way to set a fallback state in case transition method raises an exception.

Permission Based Transition

Transition decorator has permission parameter that can be used to check permission prior to transition taking place. Permission accepts a permission string, or callable that expects instance and user arguments and returns True if user can perform the transition.


You can check permission with has_transition_permission method

State Transition Diagram

You can generate state transition diagram based on transition methods.

You need pip install graphviz>=0.4 library and add django_fsm to your INSTALLED_APPS

Now run following command.


Django FSM has everything that you need to manage finite state machine in your application. In addition to this if want to perform transitions from admin site use django-fsm-admin. Also you can maintain transition logs using django-fsm-log.

Free tag for commerce

E-book on Digital Business Transformation