Merge branch 'main' of github.com:avo-hq/docs.avohq.io

Author: adrianthedev

docs/.vitepress/config.js

@@ -287,6 +287,7 @@ const config = {
             {text: "<code>Avo::Services::EncryptionService</code>", link: "/3.0/encryption-service.html"},
             {text: "Select All", link: "/3.0/select-all.html"},
             {text: "Icons", link: "/3.0/icons.html"},
+            {text: "Reserved model names and routes", link: "/3.0/internal-model-names.html"},
           ],
         },
         {

docs/3.0/audit-logging/overview.md

@@ -7,11 +7,11 @@ outline: [2,3]
 
 # Audit Logging
 
-Avo's Audit Logging feature provides a seamless way to track and visualize user activity and changes within your applications. It supports integrations with [`audited`](https://github.com/collectiveidea/audited) and [`paper_trail`](https://github.com/paper-trail-gem/paper_trail), and offers flexible installation and customization options.
+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`](https://github.com/paper-trail-gem/paper_trail), offering flexible installation and customization options.
 
-Captures user's activities on Avo resources and actions, recording details like the author and the performed event.
+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 powers activity tracking. Additionally, the chosen versioning gem, either [`audited`](https://github.com/collectiveidea/audited) or [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) will be installed if it is not already present in your project.
+The installation process will automatically generate the necessary migrations, resources, and controllers that power activity tracking. Additionally [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) will be installed if it is not already present in your project.
 
 ## Requirements
 
@@ -20,7 +20,7 @@ The installation process will automatically generate the necessary migrations, r
 ## Installation
 
 :::info
-When installing `avo-audit_logging` on a application, we strongly recommend following this documentation page step-by-step without skipping sections, as it was designed with that approach in mind.
+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
@@ -36,25 +36,11 @@ Then
 bundle install
 ```
 
-### 2. Select the audit gem
+### 2. Run the installer
 
-Prior to running the installer, choose the gem you want to use for record versioning:
-
-- [`audited`](https://github.com/collectiveidea/audited)
-- [`paper_trail`](https://github.com/paper-trail-gem/paper_trail)
-
-Once you've chosen a gem, proceed by running the installation command:
-
-:::code-group
-```bash [audited]
-bin/rails generate avo:audit_logging install --gem audited
-
-```
-
-```bash [paper_trail]
-bin/rails generate avo:audit_logging install --gem paper_trail
+```bash
+bin/rails generate avo:audit_logging install
 ```
-:::
 
 ### 3. Migrate
 
@@ -72,7 +58,7 @@ After installation, audit logging is disabled by default. To enable it, navigate
 
 Set `config.enabled` to `true` within this configuration.
 
-```ruby{7-9}
+```ruby
 # config/initializers/avo.rb # [!code focus]
 
 Avo.configure do |config|
@@ -82,11 +68,12 @@ end
 Avo::AuditLogging.configure do |config| # [!code focus]
   # config.enabled = false # [!code --] # [!code focus]
   config.enabled = true # [!code ++] # [!code focus]
+  # config.author_model = "User"
 end # [!code focus]
 ```
 
 :::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 step.
+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
@@ -95,7 +82,7 @@ Setting this configuration to `false` will disable the audit logging feature ent
 If `User` is your only author model, you can skip this step as it will be automatically set by default.
 :::
 
-Avo needs to identify the author possible models to properly set up associations behind the scenes. This will allow to fetch all activities for a specific author using the `avo_authored` association. To mark a model as an author use the `config.author_model` or for multiples models use `config.author_models`
+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`.
 
 ```ruby
 # config/initializers/avo.rb # [!code focus]
@@ -110,7 +97,7 @@ Avo::AuditLogging.configure do |config| # [!code focus]
   # config.author_model = "User" # [!code --] # [!code focus]
   config.author_model = "Account" # [!code ++] # [!code focus]
 
-  # Or if multiples # [!code focus]
+  # Or for multiples models # [!code focus]
   config.author_models = ["User", "Account"] # [!code ++] # [!code focus]
 end # [!code focus]
 ```
@@ -162,49 +149,21 @@ end # [!code focus]
 ```
 :::
 
-At this point, all resources and actions with audit logging activity enabled are being tracked.
+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
 
-### Table with detailed activities
-After installing and enabling audit logging, it's time to display the tracked activities. By default, they will appear like this, using the generated resource, which you can customize as needed.
+### Resource-Specific Activities
 
-<Image src="/assets/img/3_0/audit-logging/avo-activities.png" width="1912" height="682" alt="Avo activities table image" />
+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:
 
-To display this table as an association view, add the `:avo_activities` field to resources that have audit logging enabled.
+<Image src="/assets/img/3_0/audit-logging/sidebar-activities.png" width="1915" height="719" alt="Avo compact activities on sidebar image" />
 
-```ruby
-class Avo::Resources::Product < Avo::BaseResource # [!code focus]
-  self.audit_logging = {
-    activity: true
-  }
+### Configuring the Sidebar for Activity Tracking
 
-  def fields # [!code focus]
-    field :id, as: :id, link_to_record: true
-    field :name, as: :text, link_to_record: true
-    field :price, as: :number, step: 1
-    field :avo_activities, as: :has_many # [!code ++] # [!code focus]
-  end # [!code focus]
-
-  def actions
-    action Avo::Actions::ChangePrice
-  end
-end # [!code focus]
-```
-
-:::info
-This table is displayed using the `Avo::Resources::AvoActivity` generated during installation. You have full control to customize it as desired.
-:::
-
-### Sidebar with compact activities
-
-During installation, a resource tool called `Avo::ResourceTools::Timeline` was also generated. This tool is designed for use in the sidebar, providing a compact view of activities that looks like this:
-
-<Image src="/assets/img/3_0/audit-logging/sidebar-activities.png" width="1934" height="733" alt="Avo compact activities on sidebar image" />
-
-This can be achieved by configuring the resource to ensure that the main menu sidebar includes the resource tool:
+To enable this feature, configure the resource to include the resource tool in the main menu sidebar:
 
 ```ruby{7,12-15}
 class Avo::Resources::Product < Avo::BaseResource # [!code focus]
@@ -232,9 +191,66 @@ class Avo::Resources::Product < Avo::BaseResource # [!code focus]
 end # [!code focus]
 ```
 
+### 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.
+
+<Image src="/assets/img/3_0/audit-logging/hover-activities.png" width="657" height="284" alt="Hover on activity" />
+
+### 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:
+
+```ruby
+# app/models/product.rb # [!code focus]
+
+class Product < ApplicationRecord # [!code focus]
+  has_paper_trail # [!code ++] # [!code focus]
+
+  belongs_to :user, optional: true
+
+  validates_presence_of :price
+end # [!code focus]
+```
+
+Once enabled, the changelog will be visible, along with an action to revert changes.
+
+<Image src="/assets/img/3_0/audit-logging/activity-details.png" width="2010" height="1152" alt="Activity details page" />
+
+### 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:
+
+```ruby
+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.
+
+<Image src="/assets/img/3_0/audit-logging/authored.png" width="1921" height="754" alt="Authored table image" />
+
+:::warning
+If you're using a model other than `User`, make sure you have already [configured the author models](#configure-author-models).
+:::
+
+```ruby
+class Avo::Resources::User < Avo::BaseResource # [!code focus]
+  def fields # [!code focus]
+    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 # [!code ++] # [!code focus]
+  end # [!code focus]
+end # [!code focus]
+```
+
 ### Overview of all activities
 
-We've covered how to view activity for specific records and how to review all actions by a particular author. However, having an overview of all 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.
+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.
 
 ```ruby
 # config/initializers/avo.rb
@@ -303,143 +319,8 @@ The default value for `actions` is:
 }
 ```
 
-## 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.
-
-<Image src="/assets/img/3_0/audit-logging/authored.png" width="1926" height="739" alt="Authored table image" />
-
-:::warning
-If you're using a model other than `User`, make sure you have already [configured the author models](#_2-configure-author-models).
-:::
-
-```ruby
-class Avo::Resources::User < Avo::BaseResource # [!code focus]
-  def fields # [!code focus]
-    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 # [!code ++] # [!code focus]
-  end # [!code focus]
-end # [!code focus]
-```
-
-## Display Record Versions
-
-During installation, you chose between [`audited`](https://github.com/collectiveidea/audited) and [`paper_trail`](https://github.com/paper-trail-gem/paper_trail). Now, let's enable tracking for record changes and display them.
-
-### 1. Enable record versioning
-
-Each gem has its own method for enabling versioning, which needs to be configured at the model level:
-
-
-:::code-group
-```ruby [audited]
-# app/models/product.rb # [!code focus]
-
-class Product < ApplicationRecord # [!code focus]
-  audited # [!code ++] # [!code focus]
-
-  belongs_to :user, optional: true
-
-  validates_presence_of :price
-end # [!code focus]
-```
-
-```ruby [paper_trail]
-# app/models/product.rb # [!code focus]
-
-class Product < ApplicationRecord # [!code focus]
-  has_paper_trail # [!code ++] # [!code focus]
-
-  belongs_to :user, optional: true
-
-  validates_presence_of :price
-end # [!code focus]
-```
-:::
-
-### 2. Display Record Versions
-
-:::warning
-If you're using `paper_trail` and the `changeset` field in the versions table consistently appears as `nil`, ensure you add the following configuration in your `application.rb` file:
-
-```ruby
-config.active_record.yaml_column_permitted_classes = [Symbol, Date, Time, ActiveSupport::TimeWithZone, ActiveSupport::TimeZone]
-
-```
-:::
-
-To show record changes, you'll need to use one of the resources generated during installation. The resource name and structure will vary based on the gem you selected:
-
-:::code-group
-```ruby [audited]{22}
-class Avo::Resources::Product < Avo::BaseResource # [!code focus]
-  self.audit_logging = {
-    activity: true,
-    actions: {
-      edit: false,
-      show: false
-    }
-  }
-
-  def fields # [!code focus]
-    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
-    field :audits, as: :has_many, use_resource: Avo::Resources::Audited # [!code ++] # [!code focus]
-  end # [!code focus]
-
-  def actions
-    action Avo::Actions::ChangePrice
-  end
-end # [!code focus]
-```
-
-```ruby [paper_trail]{22}
-class Avo::Resources::Product < Avo::BaseResource # [!code focus]
-  self.audit_logging = {
-    activity: true,
-    actions: {
-      edit: false,
-      show: false
-    }
-  }
-
-  def fields # [!code focus]
-    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
-    field :versions, as: :has_many, use_resource: Avo::Resources::PaperTrail # [!code ++] # [!code focus]
-  end # [!code focus]
-
-  def actions
-    action Avo::Actions::ChangePrice
-  end
-end # [!code focus]
-```
-:::
-
 ## Conclusion
 
-With Avo’s Audit Logging, you now have the ability to track and visualize user actions and records changes across your application. By following each setup step and configuring logging as needed, you can create a robust audit system.
-
-For more advanced configurations, consider exploring the extended documentation (not available yet, work in progress) to gain further control over your audit logging setup.
+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!