Class: Decidim::Traceability

Inherits:
Object
  • Object
show all
Defined in:
decidim-core/app/services/decidim/traceability.rb

Overview

This class wraps the logic to trace resource changes and their authorship. It is expected to be used with classes implementing the `Decidim::Traceable` concern. Version authors can be retrieved using the methods in `Decidim::TraceabilityHelper`.

Examples:

# consider MyResource implements Decidim::Traceable
resource = Decidim::Traceability.new.create!(MyResource, author, params)
resource.versions.count # => 1
resource.versions.last.whodunnit # => author.to_gid.to_s
resource.versions.last.event # => "create"
resource = Decidim::Traceability.new.update!(resource, author, params)
resource.versions.count # => 2
resource.versions.last.event # => "update"

This class uses the `paper_trail` gem internally, so refer to its documentation for further info on how to interact with versions.

Instance Method Summary collapse

Instance Method Details

#create(klass, author, params, extra_log_info = {}) ⇒ Object

Calls the `create` method to the given class and sets the author of the version.

klass - An ActiveRecord class that implements `Decidim::Traceable` author - An object that implements `to_gid` or a String params - a Hash with the attributes of the new resource extra_log_info - a Hash with extra info that will be saved to the log

Returns an instance of `klass`.


31
32
33
34
35
# File 'decidim-core/app/services/decidim/traceability.rb', line 31

def create(klass, author, params, extra_log_info = {})
  perform_action!(:create, klass, author, extra_log_info) do
    klass.create(params)
  end
end

#create!(klass, author, params, extra_log_info = {}) ⇒ Object

Calls the `create!` method to the given class and sets the author of the version.

klass - An ActiveRecord class that implements `Decidim::Traceable` author - An object that implements `to_gid` or a String params - a Hash with the attributes of the new resource extra_log_info - a Hash with extra info that will be saved to the log

Returns an instance of `klass`.


45
46
47
48
49
# File 'decidim-core/app/services/decidim/traceability.rb', line 45

def create!(klass, author, params, extra_log_info = {})
  perform_action!(:create, klass, author, extra_log_info) do
    klass.create!(params)
  end
end

#last_editor(resource) ⇒ Object

Finds the author of the last version of the resource.

resource - an object implementing `Decidim::Traceable`

Returns an object identifiable via GlobalID or a String.


92
93
94
# File 'decidim-core/app/services/decidim/traceability.rb', line 92

def last_editor(resource)
  version_editor(resource.versions.last)
end

#perform_action!(action, resource, author, extra_log_info = {}) ⇒ Object

Performs the given block and sets the author of the action. It also logs the action with the given `action` parameter. The action and the logging are run inside a transaction.

action - a String or Symbol representing the action performed resource - An ActiveRecord instance that implements `Decidim::Traceable` author - An object that implements `to_gid` or a String extra_log_info - a Hash with extra info that will be saved to the log

Returns whatever the given block returns.


61
62
63
64
65
66
67
68
69
70
# File 'decidim-core/app/services/decidim/traceability.rb', line 61

def perform_action!(action, resource, author, extra_log_info = {})
  PaperTrail.request(whodunnit: gid(author)) do
    Decidim::ApplicationRecord.transaction do
      result = block_given? ? yield : nil
      loggable_resource = resource.is_a?(Class) ? result : resource
      log(action, author, loggable_resource, extra_log_info)
      return result
    end
  end
end

#update!(resource, author, params, extra_log_info = {}) ⇒ Object

Updates the `resource` with `update!` and sets the author of the version.

resource - An ActiveRecord instance that implements `Decidim::Traceable` author - An object that implements `to_gid` or a String params - a Hash with the attributes to update to the resource extra_log_info - a Hash with extra info that will be saved to the log

Returns the updated `resource`.


80
81
82
83
84
85
# File 'decidim-core/app/services/decidim/traceability.rb', line 80

def update!(resource, author, params, extra_log_info = {})
  perform_action!(:update, resource, author, extra_log_info) do
    resource.update!(params)
    resource
  end
end

#version_editor(version) ⇒ Object

Finds the author of the given version.

version - an object that responds to `whodunnit` and returns a String.

Returns an object identifiable via GlobalID or a String.


101
102
103
# File 'decidim-core/app/services/decidim/traceability.rb', line 101

def version_editor(version)
  ::GlobalID::Locator.locate(version.whodunnit) || version.whodunnit
end