auditing

Auditing is a simple way to track and rollback changes to a record.

Sample Project

https://github.com/bcantin/auditing_project

Installation

gem install auditing

There is a handy installer in the gem now. To see what it will do

rails g auditing:install --help

and, of course, to use it

rails g auditing:install
rake db:migrate

If you want to track the user, uncomment the t.integer :user_id above. See the Tracking Users section below.

Upgrading to 1.3.0

New installs will not need to do this. Anyone that is using 1.2.X and below should upgrade

gem update auditing
# ... updates happen
rails g auditing:upgrade
rake db:migrate

This will create a new migration to update the :old_value and :new_value attribute from STRING to TEXT

Basic Usage

To add auditing to all attributes on a model, simply add auditing to the model.

class School < ActiveRecord::Base
  audit_enabled
end

If you want more control over which attributes are audited, you can define them by supplying a fields hash

class School < ActiveRecord::Base
  audit_enabled :fields => [:name, :established_on]
end

Auditing will not track "id", "created_at", or "updated_at" by default

belongs_to relationships

Auditing a belongs_to relationship works by keeping track of the foreign_id attribute. You do not need to add anything to the foreign model.

has_many relationships

You may have the need to keep track of a has_many relationship. To accomplish this, we have to enable a similar type of auditing on the other model(s)

class Company < ActiveRecord::Base
  has_many :phone_numbers
  audit_enabled
end
class PhoneNumber < ActiveRecord::Base
  belongs_to :company
  audit_relationship_enabled
end

As above, you can supply a :fields hash of which attributes will be logged. If your relationship is polymorphic, you can supply an array of classes that you only want to log.

audit_relationship_enabled :only => [Company, Person]

Tracking Users

NOTE: there is probably a more elegant solution to this, if you know of one, please drop me a line.

NOTE: currently this only works with a model called User. I welcome patches to change this.

To track which logged in users have made the changes, you will need to have a user_id column in your audits table. If you did not add it when you created the audits table, you can add it in another migration

add_column :audits, :user_id, :integer

You will need to add the relationship to the Audit class as well

class Audit < ActiveRecord::Base
  belongs_to :user
end

If you want to see all the audits for a particular user, you can add the has_many relationship to the User model as well

class User < ActiveRecord::Base
  has_many :audits
end

Your user class should respond to a class method called current_user and current_user= (some authentication systems do this, others do not).

Here is a suggested method

class User < ActiveRecord::Base

  def self.current_user=(current_user)
    @current_user = current_user
  end

  def self.current_user
    @current_user
  end

end

Your ApplicationController should also set the current user so the auditing gem can get the current user properly

class ApplicationController < ActionController::Base

  before_filter :set_current_user
  after_filter  :unset_current_user

  private

  def set_current_user
    User.current_user = current_user
  end

  def unset_current_user
    User.current_user = nil
  end

end

Testing

To run the tests, first clone this repo, then

cd auditing
bundle
rake

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.