StateMachine audit trail

This plugin for the state machine gem (see github.com/pluginaweek/state_machine) adds support for keeping an audit trail for any state machine. Having an audit trail gives you a complete history of the state changes in your model. This history allows you to investigate incidents or perform analytics, like: “How long does it take on average to go from state a to state b?”, or “What percentage of cases goes from state a to b via state c?”

ORM support

Note: while the state_machine gem integrates with multiple ORMs, this plugin is currently limited to the following ORM backends:

• ActiveRecord

• Mongoid

It should be easy to add new backends by looking at the implementation of the current backends. Pull requests are welcome!

Usage

First, make the gem available by adding it to your Gemfile, and run bundle install:

gem 'state_machine-audit_trail'

Create a model/table that holds the audit trail. The table needs to have a foreign key to the original object, an “event” field, a “from” state field, a “to” state field, and a “created_at” timestamp that stores the timestamp of the transition. This gem comes with a Rails 3 generator to create a model and a migration like that.

rails generate state_machine:audit_trail <model> <state_attribute>

For a model called “Model”, and a state attribute “state”, this will generate the ModelStateTransition model and an accompanying migration.

Next, tell your state machine you want to store an audit trail:

class Model < ActiveRecord::Base
  state_machine :state, :initial => :start do
    store_audit_trail
    ...

If your audit trail model does not use the default naming scheme, provide it using the :to option:

class Model < ActiveRecord::Base
  state_machine :state, :initial => :start do
    store_audit_trail :to => 'ModelAuditTrail'
    ...

That’s it! The plugin will register an after_transition callback that is used to log all transitions. It will also log the initial state if there is one.

If you would like to store additional messages in the audit trail, you can do so with the following:

store_audit_trail :context_to_log => :state_message # Will grab the results of the state_message method on the model and store it in a field called state_message on the audit trail model

About

This plugin is written by Jesse Storimer and Willem van Bergen for Shopify. Mongoid support was contributed by Siddharth (github.com/svs). It is released under the MIT license (see LICENSE).