README.rdoc

AuditedActions¶ ↑

Rails plugin (based on v3.2) to audit users’ actions. It sends users’ actions to IronMQ first and then process them by IronWorker and save to the DB. For now only Mongoid ORM is supported as DB for storing audited actions.

This gem is still in development. Some features are not realized.

Installation¶ ↑

1. Add to Gemfile

   gem 'audited_actions', git: 'git://github.com/featalion/audited_actions.git'
   

2. Configure AuditedActions, place the code bellow at config/initializers/audition_actions.rb

   module AuditedActions
     class Engine < Rails::Engine
   
       config.token = 'IRON_IO_TOKEN'
       config.project_id = 'IRON_IO_PROJECT_ID'
       config.queue_name = 'audited_actions'
   
       config.access_restriction_callback = nil
       config.current_user = :current_user
       config.known_models = Mongoid::Document # ancestor class (or Array of classes)
   
       config.mongo = Rails.application.config.mongo # Hash to configure mongoid
     end
   end
   

   Change +‘IRON_IO_TOKEN’+ and +‘IRON_IO_PROJECT_ID’+ to right iron.io credentials.

3. Mount engine to your application, add to config/routes.rb

   mount AuditedActions::Engine, at: 'audited_actions' # , as: 'my_cool_name'
   

4. Add to controllers which actions may be audited

   audited_actions [:view, :download], associate: {content: :container}
   
   def view
     @container = VideoContainer.find(params['id'])
   end
   
   ...

5. Install worker

   rake audited_actions:install_worker
   

6. Write your own view (and layout) if you want. Place view at app/views/audited_actions/audited_actions/index.html.[erb|haml] and layout at app/layouts/audited_actions/application.html.[erb|haml].

   If you want to adapt your own app layout instead create a new one use routes with Rails engines’ names:

   main_app.root_path
   audited_actions.audited_actions_path
   

   Engine’s controller supports pagination and provides next instance variables in the view:

   @entries # => Array[AuditedActionsLogEntry, ...] - set of the log entries from the DB
   @total_entries # => Integer
   @page # => Integer
   @per_page # => Integer
   @total_pages # => Integer
   

   Accepted parameters for GET on ‘audited_actions`:

   • page - page number to show, default is 1

   • per_page - entities per page, default is 10

   You can launch worker from your app. Use POST to ‘audited_actions` with no parameters to queue worker and launch ASAP.

   <%= button_to 'Launch AuditedActions worker now!', {action: :create, method: :post}, class: 'btn' %>

   To schedule new worker PUT to ‘audited_actions`

   • interval - run interval in minutes

   Be carefull: when you create new schedule of worker plugin cancels others (only with the same worker name of course) under project you’re using at iron.io.

   <%= form_tag(audited_actions.audited_action_path('1'), method: :put) do %>
     <%= submit_tag "Schedule AuditedActions worker!", class: 'btn' %>
     <%= select_tag :interval, options_for_select([['every 30 min', '30'], ['every hour', '60'],
                                                   ['every 2 hours', '120'], ['every 4 hours', '240']]) %>
   <% end %>

Features¶ ↑

Associations with models recognition¶ ↑

Main association for any audited action is user model you are using in your app and names actor. By default plugin gets current actor by current_user method call. If you are using another method just pass its name (string or symbol) to config.current_user in the plugin initializer from step 2.

When you associate any data with the action with associate parameter the plugin try to check is it model or not. The same mechanism is used for actor. To extend the list of ORMs you want to recognize just add their base classes as config.known_models in app’s initializer.

Note: Mongoid::Document would be included to the list automatically.

Warning: any ORM you added must support id and find method. It is because plugin provides automatically association loading thru +ORMClass.find(id)+ call.

Other associations would be converted to JSON and then back and stored to the DB as Hash field.

In your app you will be able to use log entries documents from DB. Associations are available by name and automatically loaded and instantiated as one of known ORMs’ models.

log_entry = AuditedActions::AuditedActionsLogEntry.where(audited_at: {:$gte => 3.days.ago}).first # => Mongoid::Document
log_entry.actor # => KnownModel (Mongoid::Document, ActiveRecord::Base, etc.)
log_entry.my_association_name # => KnownModel

AuditedActionsLogEntry also supports special scope by_actor

actor = User.first # User must have one of known models as ancestor
AuditedActions::AuditedActionsLogEntry.by_actor(actor).where(controller: 'files') # supports chain filtering

Sometimes loaded associations might be unavailable in the DB. You can reload associations of log entry by reload_associations method.

Note: when association (ORM model document/record) is not found it returns nil.

TODO¶ ↑

1. Add functional tests.

2. Add schedule configuration feature which could be built-in to the main app.

3. Support different ORMs to store audited actions log entries. Configurable from engine’s config (initializer).

This project rocks and uses MIT-LICENSE (-: