Audit Logging

Avo's Audit Logging feature provides a seamless way to track and visualize user activity and changes within your applications. It seamlessly integrates with paper_trail, offering flexible installation and customization options.

Captures user activities on Avo resources and actions, recording details such as the author and the performed event.

The installation process will automatically generate the necessary migrations, resources, and controllers that power activity tracking. Additionally paper_trail will be installed if it is not already present in your project.

Requirements

• avo-advanced

Installation

INFO

When installing avo-audit_logging on an application, we strongly recommend following this documentation page step-by-step without skipping sections, as it was designed with that approach in mind.

1. Install the gem

Start by adding the following to your Gemfile:

gem "avo-audit_logging", source: "https://packager.dev/avo-hq/"

Then

bundle install

2. Run the installer

bin/rails generate avo:audit_logging install

3. Migrate

At this stage, all migrations, resources, and controllers required for the audit logging feature are set up and ready, it's time to migrate:

bin/rails db:migrate

Enable and configure audit logging

Global enable

After installation, audit logging is disabled by default. To enable it, navigate to your avo.rb initializer file and update the configuration for the Avo::AuditLogging module.

Set config.enabled to true within this configuration.

# config/initializers/avo.rb

Avo.configure do |config|
  # ...
end

Avo::AuditLogging.configure do |config| 
  # config.enabled = false
  config.enabled = true
  # config.author_model = "User"
end

INFO

Setting this configuration to false will disable the audit logging feature entirely, overriding any other specific settings. We'll cover those specific settings in the next steps.

Configure author models

INFO

If User is your only author model, you can skip this step as it will be automatically set by default.

Avo must determine the potential author models to correctly establish associations in the background. This setup enables the retrieval of all activities associated with a specific author via the avo_authored association. To designate a model as an author, use config.author_model, for multiple models, utilize config.author_models.

# config/initializers/avo.rb

Avo.configure do |config|
  # ...
end

Avo::AuditLogging.configure do |config| 
  config.enabled = true

  # config.author_model = "User"
  config.author_model = "Account"

  # Or for multiples models
  config.author_models = ["User", "Account"] 
end

Enable specific resources and actions

At this stage, the audit logging feature should be enabled, but activities are not yet being saved. By default, only resources and actions that are explicitly enabled for auditing will be tracked.

To enable audit logging for specific resources or actions, use the self.audit_logging class attribute.

Resource

class Avo::Resources::Product < Avo::BaseResource
  self.audit_logging = { 
    activity: true
  } 

  def fields
    field :id, as: :id, link_to_record: true
    field :name, as: :text, link_to_record: true
    field :price, as: :number, step: 1
    # ...
  end

  def actions
    action Avo::Actions::ChangePrice
  end
end

Action

class Avo::Actions::ChangePrice < Avo::BaseAction
  self.name = "Change Price"

  self.audit_logging = { 
    activity: true
  } 

  def fields
    field :price, as: :number, default: -> { resource.record.price rescue nil }
  end

  def handle(query:, fields:, current_user:, resource:, **args)
    query.each do |record|
      record.update!(price: fields[:price])
    end
  end
end

All resources and actions with audit logging activity enabled are being tracked now.

But these activities aren't visible yet, right? Let's look at how to display them in the next step.

Display logged activities

Resource-Specific Activities

The Avo::ResourceTools::Timeline tool, provided by the avo-audit_logging gem, is designed for use in the sidebar. It offers a compact view of activities that have occurred on a specific resource, presenting them in a streamlined format:

Configuring the Sidebar for Activity Tracking

To enable this feature, configure the resource to include the resource tool in the main menu sidebar:

class Avo::Resources::Product < Avo::BaseResource
  self.audit_logging = {
    activity: true
  }

  def fields
    main_panel do
      field :id, as: :id, link_to_record: true
      field :name, as: :text, link_to_record: true
      field :price, as: :number, step: 1

      sidebar do
        tool Avo::ResourceTools::Timeline
      end
    end

    field :avo_activities, as: :has_many
  end

  def actions
    action Avo::Actions::ChangePrice
  end
end

Viewing and Navigating Activity Logs

Hovering over an entry reveals the precise timestamp in UTC. Clicking on an entry navigates to a detailed page displaying the full payload.

Enabling Change Logs and Reverting Changes

By default, update activities do not display a change log, and there is no way to revert changes. This is because PaperTrail has not yet been enabled on the model. To enable it, simply add has_paper_trail to the model:

# app/models/product.rb

class Product < ApplicationRecord
  has_paper_trail 

  belongs_to :user, optional: true

  validates_presence_of :price
end

Once enabled, the changelog will be visible, along with an action to revert changes.

Troubleshooting: Missing changeset Field

WARNING

If the changeset field in the versions table consistently appears as nil, ensure you add the following configuration in your application.rb file:

config.active_record.yaml_column_permitted_classes = [Symbol, Date, Time, ActiveSupport::TimeWithZone, ActiveSupport::TimeZone]

Display author logged activities

We’ve already covered how to view all activity on a specific record. Now, let’s display a table within Avo::Resources::User to view all tracked activity for a particular user.

WARNING

If you're using a model other than User, make sure you have already configured the author models.

class Avo::Resources::User < Avo::BaseResource
  def fields
    field :id, as: :id, link_to_record: true
    field :email, as: :text, link_to_record: true
    field :products, as: :has_many
    field :avo_authored, as: :has_many, name: "Activity"
  end
end

Overview of all activities

We've covered how to view activities for specific records and how to view all actions made by a particular author. However, having an overview of all the activities in one place can also be useful. This can be achieved by configuring the menu to include a section with an entry for all activities.

# config/initializers/avo.rb

Avo.configure do |config|
  config.main_menu = -> {
    section "AuditLogging", icon: "presentation-chart-bar" do
      resource :avo_activity
    end
  }
end

Disable specific actions logging

By default, when audit logging is enabled for a resource or action, all actions, such as index visits, show visits, edit, update, etc. are logged.

If you prefer not to log all of these actions, configure the actions key within the self.audit_logging class attribute.

Let's turn off edit and show logging for the Avo::Resources::Product:

class Avo::Resources::Product < Avo::BaseResource
  self.audit_logging = { 
    activity: true, 
    actions: { 
      edit: false, 
      show: false
    } 
  } 

  def fields
    main_menu do
      field :id, as: :id, link_to_record: true
      field :name, as: :text, link_to_record: true
      field :price, as: :number, step: 1

      sidebar do
        tool Avo::ResourceTools::Timeline
      end
    end
    # ...
    field :avo_activities, as: :has_many
  end

  def actions
    action Avo::Actions::ChangePrice
  end
end

The default value for actions is:

{
  index: true,
  new: true,
  create: true,
  edit: true,
  update: true,
  show: true,
  destroy: true,
  attach: true,
  detach: true,
  handle: true
}

Conclusion

With Avo's Audit Logging, you gain a powerful tool to track and visualize user actions and record changes seamlessly across your application. By carefully following the setup steps and configuring logging to fit your needs, you can establish a robust and transparent audit system, enhancing accountability and preserving data integrity.

Happy auditing!