state_machine audit_trail

= StateMachine audit trail {}[https://travis-ci.org/wvanbergen/state_machine-audit_trail]

== Superceded
This gem has been superceded by {state_machines-audit_trail}[https://github.com/state-machines/state_machines-audit_trail]. For more information, see {the wiki on converting to the new gem.}[https://github.com/state-machines/state_machines-audit_trail/wiki/Converting-from-former-state_machine-audit_trail-to-state_machines-audit_trail].

== Deprecated
This gem is deprecated and no longer maintained due to unmaintained, outdated, and conflicting depdencies.

This plugin for the state machine gem (see https://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 <state_attribute>

(For Rails 2, use rails generate state_machine_audit_trail <state_attribute> [note the underscore instead of the colon])

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
or
store_audit_trail :context_to_log => [:field1, :field2] # Will grab the results of the field1 and field2 methods on the model and store them in fields called field1 and field2 on the audit trail model

=== Store virtual attributes

Sometimes it can be useful to store dynamically computed information.

In these situations it’s just a matter of defining a new column on table DeploymentStateTransitions and configure context_to_log.

i.e.

class Model < ActiveRecord::Base
state_machine :state, :initial => :start do
store_audit_trail :context_to_log => :version
…

def version
  # Dynamically computed field e.g., based on other models
  ...

class AddVersionToDeploymentStateTransitions < ActiveRecord::Migration
def change
add_column :deployment_state_transitions, :version, :string
…

== About

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