Django Workflow Application v0.1 (alpha)

(c) 2009 Nicholas H.Tollervey (http://ntoll.org/contact)

See the file LICENSE.txt for the licensing terms and conditions.

This Django application provides a workflow engine for use in your 
web-application. This work is an abstraction of / extraction from a workflow
engine built for an HR application.

Currently only the models have been "extracted". Commented doctests can be 
found in tests.py. I've also created some templates for generating .dot files
for processing by Graphviz. See: http://twitpic.com/7xiz7 for example output.
See the urls.py for paths to use to display the .dot file and resulting .png
image.

To make things easy I've described each model below and made up a couple of 
"user stories" to illustrate how stuff fits together (an Applicant Tracking 
System used by HR and a simple issue tracker for filing bugs, feature requests 
and whatnot). 

I realise the examples might be a tad contrived but I always find that thinking
about tangible examples relating to data models is always helpful.

The order that I describe the tables follows the code outline.

Role - defines what sort of users are associated with different aspects of the
workflow. In the HR project these roles might include: 'HR Consultant', 'Hiring
Manager', 'Interviewer' or 'Assessor'. In the issue tracker these might simply 
be 'Core Developer', 'Release Manager' or 'Tester'. The State and Transition 
models have a many-to-many relationship with Role to indicate what sort of 
person has permission to view a state or use a transition. The Event model has a
many-to-many relationship with Role to indicate who is participating in the
event.

Workflow - names / describes a workflow. In the HR project workflows might be:
'Generic Hiring Process', 'Executive Hiring Process' or 'Employee Appraisal'. In
the issue tracker these might include: 'Bug Report', 'Feature Request' or
'Release Lifecycle'. A workflow can be in one of three states that defines the
life of a workflow: definition -> active -> retired. A workflow can only be
changed when it has the state 'definition' (where changed means states and
transitions added or removed). A workflow can only be used when it has the state
'active'. When a workflow is no longer useful, or is found to contain errors
then it is marked as 'retired'. Why take so much trouble over this? Imagine the
mess that could ensue if a 'live' workflow were changed and states were deleted
or orphaned. Furthermore, retired workflows could be "cloned" as the basis of
new workflows in the 'definition' state. 

State - represents a specific state that a thing can be in. In the HR project
examples might be: 'Open for applications', 'Final shortlisting', 'Employee
Interviews'. In the issue tracker we might have: 'Open', 'Rejected', 'Awaiting
Approval'. Put simply a state is a description of a node in a directed graph. 
Only one state can be marked as 'is_start_state' for each workflow but many can
be marked as 'is_end_state' (indicating the workflow has been completed). Roles
associated with each state indicate *who* has access to the thing when in this
state.

Transition - defines how a workflow can move between states. They *should* be
given "active" names. For example, in the HR project transitions might be:
'Publish Vacancy' (leading to the 'Open for applications' state), 'Publish
applications' (leading to the 'Final shortlisting' state) or 'Publish
meeting slots' (leading to 'Employee Interviews'). The issue tracker transitions
are probably more obvious 'Submit issue' (leads to 'Open' state), 'Reject'
(leads to 'Rejected') and 'Propose new feature' (leads to 'Awaiting Approval').
Put simply, a transition is an edge in a directed graph. Roles associated with
each transition indicate *who* can use the transition to move the workflow to a
new state.

EventType - just defines the name of a type of event. Examples might be:
meeting, assessment, interview, deployment test, feature freeze and so on.

Event - is a specification for something that is supposed to happen whilst in
a state. In the HR project events might be: 'Meeting to approve job
specification', 'Meeting of review board' or 'Contact all managers conducting
employee interviews'. The issue tracker might have: 'Check for duplicate issue',
'Check unit tests pass on staging server'. The roles field indicates *who* is to
participate in the event. I've also included an is_mandatory flag. An event can
be associated with many EventTypes.

WorkflowActivity - is a core model to link "things" to workflows in a similar way
to User objects having a profile. Vacancy and Issue instances in the HR and
issue tracker examples should reference a WorkflowManager. The WorkflowManager
simply references an active Workflow and contains created_on and completed_on
timestamps. The various methods associated with this model should be used move
through the life of the workflow.

Participant - links django.contrib.auth.models.User instances to a Role and 
WorkflowManager. This way we know that user 'Joe Blogs' has the role 'Hiring 
Manager' for the duration of the WorkflowManager that is using the 'Executive
Hiring Process' workflow. We might also know that jtauber is Release Manager 
during the lifetime of the WorkflowManager for Pinax1.0 that follows the Release 
Lifecycle workflow.

WorkflowHistory - simply links up the WorkflowManager, State, Transition and
Events to the State, Participant, a descriptive note and a timestamp enabling 
us to track how the workflow has progressed (with the most recent being the 
current state). Examples might be: Pinax1.0 WorkflowManager, "RC1" state, 
"Prepare Release Candidate" transition, jtauber, 2009-11-5.

As always, comments, ideas, suggestions and improvements are most welcome.