PaperTrail

PaperTrail lets you track changes to your models' data. It's good for auditing or versioning. You can see how a model looked at any stage in its lifecycle, revert it to any version, and even undelete it after it's been destroyed.

Features

• Stores every create, update and destroy.
• Does not store updates which don't change anything.
• Does not store updates which only change attributes you are ignoring.
• Allows you to get at every version, including the original, even once destroyed.
• Allows you to get at every version even if the schema has since changed.
• Allows you to get at the version as of a particular time.
• Automatically records who was responsible if your controller has a current_user method.
• Allows you to set who is responsible at model-level (useful for migrations).
• Allows you to store arbitrary metadata with each version (useful for filtering versions).
• Can be turned off/on (useful for migrations).
• No configuration necessary.
• Stores everything in a single database table (generates migration for you).
• Thoroughly tested.

Rails Version

Known to work on Rails 2.3. Probably works on Rails 2.2 and 2.1.

Basic Usage

PaperTrail is simple to use. Just add 15 characters to a model to get a paper trail of every create, update, and destroy.

class Widget < ActiveRecord::Base
  has_paper_trail
end

This gives you a versions method which returns the paper trail of changes to your model.

>> widget = Widget.find 42
>> widget.versions             # [<Version>, <Version>, ...]

Once you have a version, you can find out what happened:

>> v = widget.versions.last
>> v.event                     # 'update' (or 'create' or 'destroy')
>> v.whodunnit                 # '153'  (if the update was via a controller and
                               #         the controller has a current_user method,
                               #         here returning the id of the current user)
>> v.created_at                # when the update occurred
>> widget = v.reify            # the widget as it was before the update;
                               # would be nil for a create event

PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version. This is useful when you start keeping a paper trail for models that already have records in the database.

>> widget = Widget.find 153
>> widget.name                                 # 'Doobly'

# Add has_paper_trail to Widget model.

>> widget.versions                             # []
>> widget.update_attributes :name => 'Wotsit'
>> widget.versions.first.reify.name            # 'Doobly'
>> widget.versions.first.event                 # 'update'

This also means that PaperTrail does not waste space storing a version of the object as it currently stands. The versions method gives you previous versions; to get the current one just call a finder on your Widget model as usual.

Here's a helpful table showing what PaperTrail stores:

Event	Model Before	Model After
create	nil	widget
update	widget	widget'
destroy	widget	nil

PaperTrail stores the values in the Model Before column. Most other auditing/versioning plugins store the After column.

Ignoring changes to certain attributes

You can ignore changes to certain attributes like this:

class Article < ActiveRecord::Base
  has_paper_trail :ignore => [:title, :rating]
end

This means that changes to just the title or rating will not store another version of the article. It does not mean that the title and rating attributes will be ignored if some other change causes a new Version to be crated. For example:

>> a = Article.create
>> a.versions.length                         # 1
>> a.update_attributes :title => 'My Title', :rating => 3
>> a.versions.length                         # 1
>> a.update_attributes :content => 'Hello'
>> a.versions.length                         # 2
>> a.versions.last.reify.title               # 'My Title'

Reverting And Undeleting A Model

PaperTrail makes reverting to a previous version easy:

>> widget = Widget.find 42
>> widget.update_attributes :name => 'Blah blah'
# Time passes....
>> widget = widget.versions.last.reify  # the widget as it was before the update
>> widget.save                          # reverted

Alternatively you can find the version at a given time:

>> widget = widget.version_at(1.day.ago)  # the widget as it was one day ago
>> widget.save                            # reverted

Note version_at gives you the object, not a version, so you don't need to call reify.

Undeleting is just as simple:

>> widget = Widget.find 42
>> widget.destroy
# Time passes....
>> widget = Version.find(153).reify    # the widget as it was before it was destroyed
>> widget.save                         # the widget lives!

In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.

Finding Out Who Was Responsible For A Change

If your ApplicationController has a current_user method, PaperTrail will store the value it returns in the version's whodunnit column. Note that this column is a string so you will have to convert it to an integer if it's an id and you want to look up the user later on:

>> last_change = Widget.versions.last
>> user_who_made_the_change = User.find last_change.whodunnit.to_i

In a migration or in script/console you can set who is responsible like this:

>> PaperTrail.whodunnit = 'Andy Stewart'
>> widget.update_attributes :name => 'Wibble'
>> widget.versions.last.whodunnit              # Andy Stewart

Storing metadata

You can store arbitrary metadata alongside each version like this:

class Article < ActiveRecord::Base
  belongs_to :author
  has_paper_trail :meta => { :author_id => Proc.new { |article| article.author_id },
                             :answer    => 42 }
end

PaperTrail will call your proc with the current article and store the result in the author_id column of the versions table. (Remember to add your metadata columns to the table.)

Why would you do this? In this example, author_id is an attribute of Article and PaperTrail will store it anyway in serialized (YAML) form in the object column of the version record. But let's say you wanted to pull out all versions for a particular author; without the metadata you would have to deserialize (reify) each version object to see if belonged to the author in question. Clearly this is inefficient. Using the metadata you can find just those versions you want:

Version.all(:conditions => ['author_id = ?', author_id])

Turning PaperTrail Off/On

Sometimes you don't want to store changes. Perhaps you are only interested in changes made by your users and don't need to store changes you make yourself in, say, a migration.

If you are about change some widgets and you don't want a paper trail of your changes, you can turn PaperTrail off like this:

>> Widget.paper_trail_off

And on again like this:

>> Widget.paper_trail_on

Installation

1. Install PaperTrail either as a gem (from Gemcutter; the ones on GitHub are obsolete) or as a plugin:

   config.gem 'paper_trail', :source => 'http://gemcutter.org'

   or:

   script/plugin install git://github.com/airblade/paper_trail.git

2. Generate a migration which will add a versions table to your database.

   script/generate paper_trail

3. Run the migration.

   rake db:migrate

4. Add has_paper_trail to the models you want to track.

Testing

PaperTrail has a thorough suite of tests. Thanks to Zachery Hostens for making them able to run standalone, i.e. without needing PaperTrail to be sitting in a Rails app.

Articles

Keep a Paper Trail with PaperTrail, Linux Magazine, 16th September 2009.

Problems

Please use GitHub's issue tracker.

Contributors

Many thanks to:

• Zachery Hostens
• Jeremy Weiskotten

Inspirations

• Simply Versioned
• Acts As Audited

Intellectual Property

Copyright (c) 2009 Andy Stewart (boss@airbladesoftware.com). Released under the MIT licence.