DISCLAIMER: Starting from the beginning of January 2024 the old Audit Trail app will no longer be available. The new Audit Trail functionality will be the only functionality available and to be used. We strongly recommend switching to the new Audit Trail starting from now if you have not done so already. The new Audit Trail is already available and no action is required on your part to activate it.

Introduction

The Audit Trail functionality has been enhanced in order to offer a completely revamped way to manage audit logs in March 2021. The new Audit Trail functionality has been rebuilt as a standalone feature (that you can reach via the Settings section of the Admin Menu) outside of the context of a report and of an app (the current Audit Trail is found in the Reports menu and is a platform app). The new Audit Trail includes the complete list of events found in the old Audit Trail since January 2023.

This enhanced functionality improves the data extraction performance, especially for clients with large databases. The user interface of the area (the new Audit Trail menu) has been redesigned in line with the new platform layout, and a handful of important changes between the current and the new Audit Trail have been made. This article lists the changes introduced by this feature enhancement and lists the APIs that have been developed for this new feature.

Audit Trail Management and Edits

In the current Audit Trail functionality, when you as a Superadmin create an Audit Trail report, the filtering mechanism (on the first page you filter by users, on the second page by courses, on the third page by event dates, event categories and fields) is complex and divided into several pages of the configuration process.

With the new Audit Trail functionality, you only need to set the filters in the corresponding panel, press Apply Filters, and your audit log table will automatically refresh using the applied filters. The result of your research is immediately available to you, without the need to go through several configuration steps.

The same happens when you want to edit one or more filters and see the results: in the current Audit Trail functionality, you need to identify your report from the table listing all of the custom reports created in the platform (at the bottom of the Reports menu), click the ellipsis icon and select the Edit option, and then go through all of the steps of the configuration to change the filter as desired.

With the new Audit Trail functionality, you only need to set a different filter in the Filters panel, press Apply Filters, and the table on the page will automatically refresh using the new filters.

Advanced Filters Capabilities

With the new Audit Trail functionality, searching for specific records becomes simpler and more intuitive. As a consequence, you will notice a notable increase in performance. Thanks to the advanced filters available in the new functionality, you can also search by target, and not only by the person or object performing the action, improving and simplifying the user experience.

For example, with the current Audit Trail functionality, if you know that the training material ABC has been deleted and you want to include this action in your audit log, you can only search by the user who performed the action, the course involved or the date when the event happened. It can be a long and complicated search if you only remember the name of the training material, but don’t know other info.

With the new functionality, you can easily search for the training material name, ABC, via the Target advanced filter.

Deprecation of Audit Trail Report Schedules

In the current Audit Trail functionality, once you have configured your Audit Trail report, you can decide to schedule it, by choosing how often (every hour, day, week…) the audit trail is sent to the email addresses you add in the corresponding field of the configuration window. However, this capability is scarcely used, and for this reason, the scheduling capability is no longer available in the new functionality.

Access to Audit Trail

In the current Audit Trail functionality, at the bottom of the Reports page, all of the reports created within the menu (including the audit trails, which are built using the reports menu) are listed. From there, you can reach the audit logs you created and schedule, edit or delete them.

As already explained in the introductory section of this guide, the new Audit Trail functionality has been rebuilt as a standalone feature and it is no longer a report, but a log of all the actions performed in the platform in a given time frame and corresponding to the filters you set. For this reason, the Audit Trail menu does not show the list of the audit logs created, but it shows a table listing all of the actions performed in the system, filtered using the filters panel on the left side of the page. 

Please Note! The new Audit Trail lists all the events that have taken place since January 2023. The old Audit Trail will be deprecated at the beginnning of January 2024 and all the events from the old Audit Trail app will be archived and transferred to the new Audit Trail. You will still be able to access them from the Archive folder.

Important Notes for Initial Transition

With the new Audit Trail functionality, you can keep track of administrative actions performed in the platform by using the Audit Trail menu (that you reach via the Settings section of the Admin Menu), benefiting from the new experience and features available in the new menu. The current Audit Trail feature is still available on your platform in the Reports menu until the end of 2023 and you can use both of these two menus, but we highly suggest trying out the new and improved Audit Trail feature. You can start using the new Audit Trail functionality as of now, no configuration nor activation is needed on your side!

The old Audit Trail feature has not yet been removed from the old Reports menu, but it is still in your platform for a number of reasons:

• The new Audit Trail functionality is fully tracking all events since January 2023  but you are unable to track the events which occurred before the release of the new Audit Trail.
• You can continue to use the old Audit Trail report when you need to search for events that took place before the availability of the new functionality. After the deprecation of the old Audit Trail app, those previous events will be archived and transferred to the new Audit Trail. You will still be able to access them from the Archive folder.
• If you have built integrations with the old Audit Trail app, you need to migrate these integrations to the new Audit Trail APIs or through Webhooks before the deprecation of the old Audit Trail app.

New APIs

The New APIs table lists the APIs available for the new Audit Trail functionality. These APIs will be fully operational starting from March 2021.

For each new API, the list of parameters is detailed in the following sections and in the Docebo API browser.

Creates a new extraction request of audit trails logs 

POST /audittrail/v1/audittrail @parameter adminFilters [object, optional] Filter by one or more specific columns

@item operatedById [object, optional] Filter by actor_id column

@item option [string, required] The type of condition to apply to the query

@item value [string, required] The value of the field

@item operatedBy [object, optional] Filter by actor column

@item option [string, required] The type of condition to apply to the query

@item value [string, required] The value of the field

@item targetId [object, optional] Filter by target_id column

@item option [string, required] The type of condition to apply to the query

@item value [string, required] The value of the field

@item target [object, optional] Filter by target column

@item option [string, required] The type of condition to apply to the query

@item value [string, required] The value of the field

@item ip [object, optional] Filter by ip column

@item option [string, required] The type of condition to apply to the query

@item value [string, required] The value of the field

  @parameter eventType  [array(string), optional] List of event names @parameter timeframe [object, optional]

@item from [string, required] Event start date in UTC format

@item to[string, required] Event end date in UTC format

Retrieves the logs generated from a specific extraction request

GET /audittrail/v1/audittrail/{query_execution_id} @get query_execution_id [string, required] ID of the requested extraction @parameter pageSize [integer, optional] Maximum number of results per page, min 1 and max 1000, default 20 @parameter nextToken [string, optional] Token generated that specifies from where to continue the pagination  

Retrieves all the event types supported by the audit trail service

GET /audittrail/v1/audittrail/event-types  

Retrieves a CSV file of the requested extraction

GET /audittrail/v1/audittrail/{query_execution_id}/download @get query_execution_id [integer, required] ID of the requested extraction