This week I was working on a project where the users need to see the history of changes to a particular model. We had been using the Papertrail gem for this, but in the process of making our display of the history more robust, decided to create our own model to explicitly track the changes we cared about instead. Here's what I did.

Let's say we're working with a model like this:

# == Schema Information
#
# Table name: bicycles
#  needs_repair               :boolean          default(FALSE)
#  in_repair                  :boolean          default(FALSE)
#  notes                      :text
#  created_at                 :datetime         not null
#  updated_at                 :datetime         not null
#  bicycle_type_id            :bigint
#  brand_id                   :bigint
#  location_id                :bigint
class Bicycle < ApplicationRecord
  belongs_to :bicycle_type
  belongs_to :brand
  belongs_to :location
end

And we need to keep track of the history - if someone updated the location of the bike, we need to know who did that and when it happened.

Now, we could use a gem like Papertrail, but today we aren't doing that for whatever reason. So we are going to create our own model called BicycleHistory.

We'll add a migration and a new model:

class CreateBicycleHistories < ActiveRecord::Migration[7.0]
  def change
    create_table :bicycle_histories do |t|
      t.references :bicycle
      t.references :user, type: :uuid, optional: true     # who made the change?
      t.references :bicycle_type, optional: true
      t.references :brand, optional: true
      t.references :location, optional: true
      t.boolean :in_repair
      t.boolean :needs_repair
      t.text :notes
      t.timestamps
    end
  end
end

class BicycleHistory < ApplicationRecord
  belongs_to :bicycle, inverse_of: :bicycle_histories

  # optional: true because some of the paper trail histories we're backfilling don't have a whodunnit associated with them
  belongs_to :user, optional: true

  belongs_to :bicycle_type, optional: true
  belongs_to :brand, optional: true
  belongs_to :location, optional: true

Our first pass at writing a method to save the history might look something like this, on the Bicycle model class:

class Bicycle < ApplicationRecord
  after_update :create_bicycle_history

 def create_bicycle_history
    return unless saved_changes?

    bicycle_history = BicycleHistory.new(bicycle: self)
    bicycle_history.brand_id = brand if saved_change_to_attribute?(:brand)
    bicycle_history.location_id = location_id if saved_change_to_attribute?(:location_id)
    bicycle_history.bicycle_type_id = bicycle_type_id if saved_change_to_attribute?(:bicycle_type_id)
    bicycle_history.in_repair = in_repair if saved_change_to_attribute?(:in_repair)
    bicycle_history.needs_repair = needs_repair if saved_change_to_attribute?(:needs_repair)
    bicycle_history.save
  end
end

The interesting parts of this approach are the saved_changes? and saved_change_to_attribute? methods, both provided by ActiveRecord::Dirty, which is going to be our best friend for this feature.

In an Active Record model, thanks to ActiveRecord::Dirty, saved_changes() returns a hash containing all the changes that were just saved (in the last call to save). saved_changes? will tell you if the last call to save had any changes, that is, it answers the same question as saved_changes.present?.

That's great! This is working well. We can write a test using Minitest conventions and Fabricator (I usually prefer factories but this project has a Fabricator convention) ensuring each of our attributes were saved correctly, that might look something like this:

  test "creates bicycle history after update of bicycle location" do
    bicycle = Fabricate.create(:bicycle)
    bicycle.location = Location.create
    bicycle.save
    bicycle_history = BicycleHistory.last
    assert_equal bicycle.location, bicycle_history.reload.location
  end

Yay! The test is green, we're doing great.

But! We forgot to save who the user is that made the change. And unfortunately, we don't have that information in the after_update callback of our model. We need to pass the user in from the controller in order to get the logged-in user who made the change through the site's UI. So, we'll need to change our method from being a callback to something called explicitly after a successful update in our controller, and give it an updater parameter so we can pass in the user.

That method is also using a lot of code that looks quite similar, with just the attribute names changing. We can use a bit of metaprogramming (writing code that produces other code that gets executed) to simplify it.

Let's add some TRACKED_FIELDS to our BicycleHistory model:

  TRACKED_FIELDS = [
    :location_id,
    :brand_id,
    :bicycle_type_id,
    :in_repair,
    :needs_repair
  ]    

and use them like this in our method on Bicycle:

  def create_bicycle_history(updater)
    return unless saved_changes?

    bicycle_history = BicycleHistory.new(bicycle: self)
    bicycle_history.user = updater unless updater.blank?
    BicycleHistory::TRACKED_FIELDS.each do |attribute|
      bicycle_history.public_send("#{attribute}=", public_send(attribute)) if saved_change_to_attribute?(attribute)
    end

    bicycle_history.save
  end

Here we're calling the assignment method provided by ActiveRecord automatically for each attribute we want to track, and giving it the current value of the attribute if there were any changes the last time the attribute got saved.

This could be subject to race conditions if we had a lot of people using our app at once and it was multi-threaded, but the app I'm working on is single threaded.

This is looking great! Our tests, after being updated to explicitly call the create_bicycle_history method, are still green!

Let's say we now want to display the changes in a table for our users on our site. But, we don't want to have a lot of repetition in our frontend code, either. So let's use some metaprogramming again.

We'll put this on the BicycleHistory model:

  def change_information
    BicycleHistory::TRACKED_FIELDS.map do |field|
      "#{field.to_s.titleize}: " + public_send(field.to_s.sub("_id", "")).to_s if public_send(field).present?
    end.compact
  end

Our fields are stored as symbols, so we need to call to_s before we can use string methods on them like titleize.

We don't want to display the location id in our UI; we want to display the location name. So, here: public_send(field.to_s.sub("_id", "")).to_s we're stripping the _id portion of the attribute name off, so that Active Record will give us the actual model, not just the id. Then we're calling to_s on the model to give us back the user-relevant model info, which we can support by adding a to_s override on the models we care about like this:

class Location
  def to_s
    name
  end
end

If the attribute is already a string or can be converted to one, or doesn't have a _id substring to strip off, our code still works just fine for displaying the value (like for our booleans).

Yay! Pretty code.

# Backfilling a history previously tracked with Papertrail to my new model:

The model I'm tracking manually now was previously tracked with Papertrail. I don't want to lose that history, so I wrote this rake task to backfill the history from Papertrail to my new model:

  task backfill_history: :environment do
    Bicycle.find_each do |bicycle|
      bicycle.versions.where(event: "update").order(created_at: :desc).each do |bicycle_version|
        b_history = BicycleHistory.new(bicycle: bicycle)
        b_history.user_id = bicycle_version.whodunnit if bicycle_version.whodunnit.present?
        bicycle_version.changeset.each do |co|
          flattened_change = co.flatten
          co_key = flattened_change[0]
          next if co_key == "created_at" || co_key == "updated_at"

          co_new_value = flattened_change[2]
          b_history.public_send("#{co_key}=", co_new_value)
        end
        b_history.created_at = bicycle_version.created_at
        b_history.save!
      end
    end
  end

# A weird rabbit hole about saving changes to associated records

Something I noticed while writing my tests, after updating my code to not use a callback and instead call my change tracking method explictly, is that my test failed if the model my history belongs_to wasn't already saved.

  test "creates bicycle history after update of bicycle location" do
    bicycle = Fabricate.create(:bicycle)
    bicycle.location = Location.create   # Location.new doesn't work!
    bicycle.save
    bicycle_history = BicycleHistory.last
    assert_equal bicycle.location, bicycle_history.reload.location
  end

This seems to be because when you save a nested belongs_to relationship as part of saving a parent model, the belongs_to assocation runs a callback after update that clears the saved_changes. I added a comment in my code making a note of that, but it's okay for right now because right now we don't have a nested form for creating Locations (or any other associated records) when updating a Bicycle.