ActionTracker
Installation
Add this line to your application's Gemfile:
gem 'action_tracker_client', require: 'action_tracker'
And then execute:
$ bundle
Or install it yourself as:
$ gem install action_tracker
Usage
Configuration
You need to put the following values in initializer:
# config/initializers/action_tracker.rb
ActionTracker.configure do |config|
config.api_url = ENV['ACTION_TRACKING_API_URL']
config.api_key = ENV['ACTION_TRACKING_API_KEY']
config.api_secret = ENV['ACTION_TRACKING_API_SECRET']
# Avalilable options:
#
# :inline (default) -> performs request to external API
# :test -> stores request parameters, can be accessed via ActionTracker.records
# :custom -> calls custom labda
#
config.tracking_method = :custom
config.custom_worker_proc = ->(form) { MyCustomActionTrackingJob.perform_later(form.attributes) }
end
Reading records
api = ActionTracker::Models::TransitionRecord.new
data = api.index(target_id: order.id, target_type: 'Order', per_page: 25, cursor: 'Y3VycmVudF9wYWdl')
#<ActionTracker::CollectionProxy:0x00007f958b6970a8
# ...
data.each do |record|
puts record.inspect
end
#<ActionTracker::Models::TransitionRecord:0x00007f9584d44470 @id="a51b2fe2-fa92-4e91-bdcd-5beee9081903"...
#<ActionTracker::Models::TransitionRecord:0x00007f9584d3dfd0 @id="810b900d-d24b-4206-85e3-b7a53e55a060"...
Records filtered by user
api = ActionTracker::Models::TransitionRecord.new
data = api.filtered_by_users(user_id: user.id, target_id: order.id, target_type: 'Order', per_page: 25, cursor: 'Y3VycmVudF9wYWdl')
#<ActionTracker::CollectionProxy:0x00007f958b6970a8
# ...
data.each do |record|
puts record.inspect
end
#<ActionTracker::Models::TransitionRecord:0x00007f9584d44470 @id="a51b2fe2-fa92-4e91-bdcd-5beee9081903"...
#<ActionTracker::Models::TransitionRecord:0x00007f9584d3dfd0 @id="810b900d-d24b-4206-85e3-b7a53e55a060"...
# data = api.filtered_by_users_count(user_id: user.id, target_id: order.id, target_type: 'Order')
# this will return count of actions
Writing records
Call ActionTracker::Recorder after creating or updating your model:
basic usage: ActionTracker::Recorder.new(:event_name).call(model)
Where :event_name is the name of template. Custom templates could be defined if needed.
valid events (templates): [:create, :update, :destroy]
# Suppose you have some command, creating an order:
class CreateOrderCommand
# https://github.com/krisleech/wisper
include Wisper::Publisher
def initialize(order_form)
@form = order_form
subscribe(ActionTracker::Recorder.new(:create), on: :ok, with: :call)
end
def call
if order.save
broadcast(:ok, order)
else
broadcast(:failed, order)
end
end
end
or with ActiveRecord callbacks:
class User < ApplicationRecord
SKIPPED_ATTRIBUTES = [:password, :updated_at]
after_update -> { ActionTracker::Recorder.new(:update, skip: SKIPPED_ATTRIBUTES).call(self) }
end
Defining custom templates
Action tracker will look for templates in ActionTracker::Templates module.
# app/models/action_tracker/templates/state_change.rb
module ActionTracker
module Templates
class StateChange < ActionTracker::Templates::BaseTemplate
# Any text, describing the event
#
def event_name
'State changed'
end
# Can be any string, representing what changed in your model. Max length limited to 1000 chars
#
def content
"from `#{target.previous_state_name}` to `#{target.current_state_name}`"
end
# The user who performed the change. { id: 0, name: 'Anonymous', type: 'System' }
#
def user
@user ||= CurrentUser.fetch
end
end
end
end
module ActionTracker
module Templates
module Orders
class SomeCustomEvent < ActionTracker::Templates::BaseTemplate
# ...
end
end
end
end
# Call recorder
ActionTracker::Recorder.new(:state_change).call(target)
ActionTracker::Recorder.new('Orders::SomeCustomEvent').call(target)
Testing
Set tracking method to :test
in application environment config and clear records after each spec
# config/environments/test.rb
config.after_initialize do
ActionTracker.config.tracking_method = :test
end
# spec/rails_helper.rb
config.after(:each) do
ActionTracker.clear_records
end
ActionTracker.records
=> [{:target_id=>76, :target_type=>"Order", :payload=>{:event=>"Created payment #89", :content=>"amount 100.0", :user=>{:id=>0, :name=>"Anonymous", :type=>"System"}}, :reference_id=>89, :reference_type=>"PaymentTransaction"}]
ActionTracker.last_event
=> "Created payment #89"
ActionTracker.records.select_by('payload.user.name', 'Anonymous')
=> [{:target_id=>76, :target_type=>"Order".....
ActionTracker.records.last_content
=> "amount 100.0"
ActionTracker.records.select_by('payload.user.name', 'SomeUser')
=> []
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/action_tracker.
License
The gem is available as open source under the terms of the MIT License.