django-fsm-ticket 1.4.0

Simple ticketing and workflow engine based on django-fsm-2

Introduction

django_fsm_ticket is a customizable workflow and ticketing framework, built on top of django-fsm-2.

The goal of django-fsm-ticket is to provide a low-code tool for creating web applications to manage workflows in Django. The user interface (i.e., Django views) is automatically generated by the framework, using the familiar metaphor of "tickets" (similar to GitHub's issues). The developer can fully customize:

• Data involved in a ticket life cycle by defining plain Django models.
• How data is shown within the ticket by defining Django templates.
• The workflow itself (ticket states, state transitions, user permissions, ticket visibility), relying on the simple and rock-solid django-fsm-2 library.

Ticket list page, with the Bootstrap Italia theme

A workflow instance is a ticket

You can think of django-fsm-ticket as a blend of a workflow system and a GitHub-like ticketing system. Each workflow instance is a ticket, with a current state and some ticket-related data.

Each ticket is visualized on a single web page, along with its history. Like comments in GitHub, ticket history is a sequence of ticket updates, showing how the ticket changed over time. Usually, a ticket update is the result of an action performed by an authorized user, but updates can also be triggered programmatically. Each ticket update may change the current ticket state and data; a ticket update may also hold data related to the update itself, such as a comment, some uploaded files, or any other piece of information that you may wish to store in a Django model instance.

A ticket's behavior is defined through Django models:

• To define the shape of tickets, you can subclass the Ticket class (or you may just use the base class Ticket, which provides the bare minimum ticket data, i.e., a title, opening time, current state, the user that opened the ticket, etc.)
• For each kind of ticket update (you may have several of them, corresponding to different kinds of actions that users may perform), you may define a subclass of TicketUpdate; or you may use the base class, which provides the bare minimum fields for an update, such as the update author, a timestamp, and optional notes.

Details page of a ticket

Users perform actions

Users perform actions. An action has a name (e.g., "add a comment", "close the ticket", "approve the request") and causes a ticket update. Thus, an action may:

• Change the ticket state.
• Alter ticket data.
• Create a TicketUpdate instance, with data related to the performed action.
• Execute arbitrary Python code.

The set of actions that are currently allowed depends on the current Ticket state and the currently logged-in user. They are defined through a finite state machine.

django_fsm_ticket takes care of automatically generating a fully-working UI from your definitions of Ticket and TicketUpdate subclasses. It displays the proper forms and actions. You can fully customize the templates, models, and views if you wish.

Getting started

Installation

Install the library from PyPI:

pip install django-fsm-ticket

If you also plan to expose a REST API for the ticketing system, include the [api] extra:

pip install django-fsm-ticket[api]

In settings.py, add polymorphic and django_fsm_ticket to your INSTALLED_APPS list:

# settings.py

INSTALLED_APPS = [
  # ...
  "polymorphic",
  "django_fsm_ticket",
  # ...
]

Also, in settings.py, add a configuration class:

# settings.py

class FSM_TICKET_CONFIG:
    URL_PREFIX = "https://my.fsm.tickets.com"
    NOTIFICATION_LEVEL = 2

Here, we are specifying the base url and telling django_fsm_ticket to send email notifications to users in charge of taking actions on tickets unless they opted-out from email notifications.

You may want to be able to configure django_fsm_ticket via the Django admin interface by using django-constance.

Finally, in your project-level urls.py file, add a urlconf for django-fsm-ticket:

# urls.py

from django.urls import path, include

# ...

urlpatterns = [
    # ...
    path("ticket/", include('django_fsm_ticket.urls')),
    # ...
]

Tutorial

New to django-fsm-ticket? We recommend starting with our beginner-friendly tutorial:

👉 Read the docs/TUTORIAL.md

Example project

If you'd like to explore a fully working example, we offer a demo Django project.

You can run the project locally by cloning the repository and executing the following commands:

# Make sure poetry is installed
pip install --user poetry

poetry install --extras "dev"
eval "$(poetry env activate)"
# or, if you use `fish`:
# eval (poetry env activate)

cd example_project

# Setup database
python manage.py migrate
python manage.py createsuperuser

# Start server
python manage.py runserver

Contributing

Want to contribute or submit improvements?

👉 Read the CONTRIBUTING.md