Metadata-Version: 2.4
Name: django-fsm-ticket
Version: 1.4.0
Summary: Simple ticketing and workflow engine based on django-fsm-2
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: django,fsm,workflow,ticket,state-machine,bpm,low-code
Author: Luca Allulli
Author-email: lallulli@fub.it
Requires-Python: >=3.10,<4
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: api
Provides-Extra: dev
Requires-Dist: coverage (>=7.9.1) ; extra == "dev"
Requires-Dist: django (>=4.2)
Requires-Dist: django-constance ; extra == "dev"
Requires-Dist: django-filter (>=25.2) ; extra == "api"
Requires-Dist: django-fsm-2 (>=3.0.0)
Requires-Dist: django-polymorphic (>=3.0.0)
Requires-Dist: djangorestframework (>=3.16.1) ; extra == "api"
Requires-Dist: ruff (>=0.14.2,<0.15.0) ; extra == "dev"
Project-URL: Documentation, https://github.com/fondazionebordoni/django-fsm-ticket
Project-URL: Homepage, https://github.com/fondazionebordoni/django-fsm-ticket
Project-URL: Issues, https://github.com/fondazionebordoni/django-fsm-ticket/issues
Project-URL: Repository, https://github.com/fondazionebordoni/django-fsm-ticket
Description-Content-Type: text/markdown

# Introduction

`django_fsm_ticket` is a customizable workflow and ticketing framework, built on top of [`django-fsm-2`](https://github.com/pfouque/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.

<p align="center">
  <img src="docs/img/screenshot_ticket_list.png" width="600" alt="Ticket list">
</p>
<p align="center">
  <em>Ticket list page, with the Bootstrap Italia theme</em>
</p>

## 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.

<p align="center">
  <img src="docs/img/screenshot_ticket_details.png" width="600" alt="Ticket list">
</p>
<p align="center">
  <em>Details page of a ticket</em>
</p>

## 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.


# <a name="getting-started"></a>Getting started


## Installation

Install the library from PyPI:

```bash
pip install django-fsm-ticket
```

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

```bash
pip install django-fsm-ticket[api]
```

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

```python
# settings.py

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

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

```python
# 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](#constance) by using `django-constance`.

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

```python
# 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](docs/TUTORIAL.md)


## Example project

If you'd like to explore a fully working example, we offer a [demo Django project](./example_project/).

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

```bash
# 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](./CONTRIBUTING.md)
