state_machine-audit_trail 0.1.0 → 0.1.1

data/.travis.yml

@@ -1,8 +1,7 @@
 rvm:
   - 1.8.7
-  - 1.9.1
   - 1.9.2
+  - 1.9.3  
   - ruby-head
   - ree
   - rbx
-  - jruby

data/README.rdoc

@@ -2,18 +2,25 @@
 
 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?"
 
-Note: while the state_machine gem integrates with multiple ORMs, this plugin currently only has an ActiveRecord backend. It should be easy to add support for other ActiveModel-based ORMs though.
+== 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 <tt>Gemfile</tt>, and run <tt>bundle install</tt>:
 
   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, am "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.
+
+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:
@@ -32,6 +39,9 @@ If your audit trail model does not use the default naming scheme, provide it usi
 
 That's it! The plugin will register an <tt>after_transition</tt> 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. It is released under the MIT license (see LICENSE)
+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).

data/lib/state_machine/audit_trail/backend/active_record.rb

@@ -1,9 +1,20 @@
 class StateMachine::AuditTrail::Backend::ActiveRecord < StateMachine::AuditTrail::Backend
+  attr_accessor :context_to_log
 
+  def initialize(transition_class, context_to_log)
+    self.context_to_log = context_to_log
+    super transition_class
+  end
   def log(object, event, from, to, timestamp = Time.now)
     # Let ActiveRecord manage the timestamp for us so it does the 
     # right thing with regards to timezones.
-    transition_class.create(foreign_key_field(object) => object.id, :event => event, :from => from, :to => to)
+    params = {foreign_key_field(object) => object.id, :event => event, :from => from, :to => to}
+
+    if context_to_log.is_a?(Array.class)
+    elsif !context_to_log.nil?
+      params[context_to_log] = object.send(context_to_log)
+    end
+    transition_class.create(params)
   end
 
   def foreign_key_field(object)

data/lib/state_machine/audit_trail/backend.rb

@@ -13,10 +13,13 @@ class StateMachine::AuditTrail::Backend < Struct.new(:transition_class)
   #
   # in order to adda new ORM here, copy audit_trail/mongoid.rb to whatever you want to call the new file and implement the #log function there
   # then, return from here the appropriate object based on which ORM the transition_class is using  
-  def self.create_for_transition_class(transition_class)
+  def self.create_for_transition_class(transition_class, context_to_log = nil)
     if Object.const_defined?('ActiveRecord') && transition_class.ancestors.include?(::ActiveRecord::Base)
-      return StateMachine::AuditTrail::Backend::ActiveRecord.new(transition_class)
+      return StateMachine::AuditTrail::Backend::ActiveRecord.new(transition_class, context_to_log)
     elsif Object.const_defined?('Mongoid') && transition_class.ancestors.include?(::Mongoid::Document)
+      # Mongoid implementation doesn't yet support additional context fields
+      raise NotImplemented, "Mongoid does not support additional context fields" if context_to_log.present?
+
       return StateMachine::AuditTrail::Backend::Mongoid.new(transition_class)
     else
       raise NotImplemented, "Only support for ActiveRecord and Mongoid is included at this time"

data/lib/state_machine/audit_trail/transition_auditing.rb

@@ -7,24 +7,25 @@ module StateMachine::AuditTrail::TransitionAuditing
   
   # Public tells the state machine to hook in the appropriate before / after behaviour
   #
-  # options: a Hash of options. keys that are used are :to => CustomTransitionClass 
+  # options: a Hash of options. keys that are used are :to => CustomTransitionClass,
+  #   :context_to_log => method(s) to call on object and store in transitions
   def store_audit_trail(options = {})
     state_machine = self
     state_machine.transition_class_name = (options[:to] || default_transition_class_name).to_s
     state_machine.after_transition do |object, transition|
-      state_machine.audit_trail.log(object, transition.event, transition.from, transition.to)
+      state_machine.audit_trail(options[:context_to_log]).log(object, transition.event, transition.from, transition.to)
     end
 
     state_machine.owner_class.after_create do |object|
       if !object.send(state_machine.attribute).nil?
-        state_machine.audit_trail.log(object, nil, nil, object.send(state_machine.attribute))
+        state_machine.audit_trail(options[:context_to_log]).log(object, nil, nil, object.send(state_machine.attribute))
       end
     end
   end
 
   # Public returns an instance of the class which does the actual audit trail logging
-  def audit_trail
-    @transition_auditor ||= StateMachine::AuditTrail::Backend.create_for_transition_class(transition_class)
+  def audit_trail(context_to_log = nil)
+    @transition_auditor ||= StateMachine::AuditTrail::Backend.create_for_transition_class(transition_class, context_to_log)
   end
 
   private

data/lib/state_machine/audit_trail.rb

@@ -2,7 +2,7 @@ require 'state_machine'
 
 module StateMachine::AuditTrail
     
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
     
   def self.setup
     StateMachine::Machine.send(:include, StateMachine::AuditTrail::TransitionAuditing)

data/spec/helpers/active_record.rb

@@ -10,6 +10,12 @@ ActiveRecord::Base.connection.create_table(:active_record_test_models) do |t|
   t.timestamps
 end
 
+ActiveRecord::Base.connection.create_table(:active_record_test_model_with_contexts) do |t|
+  t.string :state
+  t.string :type
+  t.timestamps
+end
+
 ActiveRecord::Base.connection.create_table(:active_record_test_model_with_multiple_state_machines) do |t|
   t.string :first
   t.string :second
@@ -21,6 +27,10 @@ class ActiveRecordTestModelStateTransition < ActiveRecord::Base
   belongs_to :test_model
 end
 
+class ActiveRecordTestModelWithContextStateTransition < ActiveRecord::Base
+  belongs_to :test_model
+end
+
 class ActiveRecordTestModelWithMultipleStateMachinesFirstTransition < ActiveRecord::Base
   belongs_to :test_model
 end
@@ -32,16 +42,34 @@ end
 class ActiveRecordTestModel < ActiveRecord::Base
 
   state_machine :state, :initial => :waiting do # log initial state?
-    store_audit_trail 
+    store_audit_trail
+
+    event :start do
+      transition [:waiting, :stopped] => :started
+    end
+
+    event :stop do
+      transition :started => :stopped
+    end
+  end
+end
+
+class ActiveRecordTestModelWithContext < ActiveRecord::Base
+  state_machine :state, :initial => :waiting do # log initial state?
+    store_audit_trail :context_to_log => :context
 
     event :start do
       transition [:waiting, :stopped] => :started
     end
-    
+
     event :stop do
       transition :started => :stopped
     end
   end
+
+  def context
+    "Some context"
+  end
 end
 
 class ActiveRecordTestModelDescendant < ActiveRecordTestModel
@@ -50,15 +78,15 @@ end
 class ActiveRecordTestModelWithMultipleStateMachines < ActiveRecord::Base
 
   state_machine :first, :initial => :beginning do
-    store_audit_trail 
+    store_audit_trail
 
     event :begin_first do
       transition :beginning => :end
     end
   end
-  
+
   state_machine :second do
-    store_audit_trail 
+    store_audit_trail
 
     event :begin_second do
       transition nil => :beginning_second
@@ -68,16 +96,18 @@ end
 
 def create_transition_table(owner_class, state)
   class_name = "#{owner_class.name}#{state.to_s.camelize}Transition"
-  
   ActiveRecord::Base.connection.create_table(class_name.tableize) do |t|
+    add_context = owner_class.instance_methods.include? :context
     t.integer owner_class.name.foreign_key
     t.string :event
     t.string :from
     t.string :to
+    t.string :context if add_context
     t.datetime :created_at
   end
 end
 
-create_transition_table(ActiveRecordTestModel, :state)  
-create_transition_table(ActiveRecordTestModelWithMultipleStateMachines, :first)  
+create_transition_table(ActiveRecordTestModel, :state)
+create_transition_table(ActiveRecordTestModelWithContext, :state)
+create_transition_table(ActiveRecordTestModelWithMultipleStateMachines, :first)
 create_transition_table(ActiveRecordTestModelWithMultipleStateMachines, :second)  

data/spec/state_machine/active_record_spec.rb

@@ -2,15 +2,15 @@ require 'spec_helper'
 require 'helpers/active_record'
 
 describe StateMachine::AuditTrail::Backend::ActiveRecord do
-  
+
   it "should create an ActiveRecord backend" do
     backend = StateMachine::AuditTrail::Backend.create_for_transition_class(ActiveRecordTestModelStateTransition)
     backend.should be_instance_of(StateMachine::AuditTrail::Backend::ActiveRecord)
-  end  
-  
+  end
+
   context 'on an object with a single state machine' do
     let!(:state_machine) { ActiveRecordTestModel.create! }
-    
+
     it "should log an event with all fields set correctly" do
       state_machine.start!
       last_transition = ActiveRecordTestModelStateTransition.where(:active_record_test_model_id => state_machine.id).last
@@ -18,21 +18,36 @@ describe StateMachine::AuditTrail::Backend::ActiveRecord do
       last_transition.event.to_s.should == 'start'
       last_transition.from.should == 'waiting'
       last_transition.to.should == 'started'
+      #last_transition.context.should_not be_nil
       last_transition.created_at.should be_within(10.seconds).of(Time.now.utc)
     end
-    
+
     it "should log multiple events" do
       lambda { state_machine.start && state_machine.stop && state_machine.start }.should change(ActiveRecordTestModelStateTransition, :count).by(3)
     end
-    
-    it "should do nothing when the transition is not exectuted successfully" do
+
+    it "should do nothing when the transition is not executed successfully" do
       lambda { state_machine.stop }.should_not change(ActiveRecordTestModelStateTransition, :count)
     end
   end
-  
+
+  context 'on an object with a single state machine that wants to log a single context' do
+    before do
+      backend = StateMachine::AuditTrail::Backend.create_for_transition_class(ActiveRecordTestModelWithContextStateTransition, :context)
+    end
+
+    let!(:state_machine) { ActiveRecordTestModelWithContext.create! }
+
+    it "should log an event with all fields set correctly" do
+      state_machine.start!
+      last_transition = ActiveRecordTestModelWithContextStateTransition.where(:active_record_test_model_with_context_id => state_machine.id).last
+      last_transition.context.should == state_machine.context
+    end
+  end
+
   context 'on an object with multiple state machines' do
     let!(:state_machine) { ActiveRecordTestModelWithMultipleStateMachines.create! }
-    
+
     it "should log a state transition for the affected state machine" do
       lambda { state_machine.begin_first! }.should change(ActiveRecordTestModelWithMultipleStateMachinesFirstTransition, :count).by(1)
     end
@@ -41,15 +56,15 @@ describe StateMachine::AuditTrail::Backend::ActiveRecord do
       lambda { state_machine.begin_first! }.should_not change(ActiveRecordTestModelWithMultipleStateMachinesSecondTransition, :count)
     end
   end
-  
+
   context 'on an object with a state machine having an initial state' do
     let(:state_machine_class) { ActiveRecordTestModelWithMultipleStateMachines }
     let(:state_transition_class) { ActiveRecordTestModelWithMultipleStateMachinesFirstTransition }
-    
+
     it "should log a state transition for the inital state" do
       lambda { state_machine_class.create! }.should change(state_transition_class, :count).by(1)
     end
-    
+
     it "should only set the :to state for the initial transition" do
       state_machine_class.create!
       initial_transition = state_transition_class.last
@@ -59,11 +74,11 @@ describe StateMachine::AuditTrail::Backend::ActiveRecord do
       initial_transition.created_at.should be_within(10.seconds).of(Time.now.utc)
     end
   end
-  
+
   context 'on an object with a state machine not having an initial state' do
     let(:state_machine_class) { ActiveRecordTestModelWithMultipleStateMachines }
     let(:state_transition_class) { ActiveRecordTestModelWithMultipleStateMachinesSecondTransition }
-    
+
     it "should not log a transition when the object is created" do
       lambda { state_machine_class.create! }.should_not change(state_transition_class, :count)
     end

data/state_machine-audit_trail.gemspec

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name        = "state_machine-audit_trail"
-  s.version     = "0.1.0"
+  s.version     = "0.1.1"
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Willem van Bergen", "Jesse Storimer"]
   s.email       = ["willem@shopify.com", "jesse@shopify.com"]

metadata

@@ -1,118 +1,103 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: state_machine-audit_trail
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 0
-  version: 0.1.0
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Willem van Bergen
 - Jesse Storimer
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-02-20 00:00:00 -05:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-07-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: state_machine
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  requirement: &70159599977080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: *70159599977080
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70159599976060 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    requirements: 
+  version_requirements: *70159599976060
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70159599992820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 2
-        version: "2"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: activerecord
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    requirements: 
+  version_requirements: *70159599992820
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &70159599991160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 3
-        version: "3"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: sqlite3
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: *70159599991160
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &70159599989960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: mongoid
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: *70159599989960
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: &70159599988580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: bson_ext
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+  version_requirements: *70159599988580
+- !ruby/object:Gem::Dependency
+  name: bson_ext
+  requirement: &70159600002560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id007
-description: Log transitions on a state machine to support auditing and business process analytics.
-email: 
+  prerelease: false
+  version_requirements: *70159600002560
+description: Log transitions on a state machine to support auditing and business process
+  analytics.
+email:
 - willem@shopify.com
 - jesse@shopify.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .travis.yml
 - Gemfile
@@ -135,37 +120,38 @@ files:
 - spec/state_machine/mongoid_spec.rb
 - state_machine-audit_trail.gemspec
 - tasks/github_gem.rb
-has_rdoc: true
 homepage: https://github.com/wvanbergen/state_machine-audit_trail
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
+      hash: 3519932254629100155
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 3519932254629100155
 requirements: []
-
 rubyforge_project: state_machine
-rubygems_version: 1.3.6
+rubygems_version: 1.8.16
 signing_key: 
 specification_version: 3
-summary: Log transitions on a state machine to support auditing and business process analytics.
-test_files: 
+summary: Log transitions on a state machine to support auditing and business process
+  analytics.
+test_files:
 - spec/state_machine/active_record_spec.rb
 - spec/state_machine/audit_trail_spec.rb
 - spec/state_machine/mongoid_spec.rb