Audit Trail Display

The Audit Trail display is used to retrieve and visualize Audit Trail Records for the system and individual objects. The Audit Trail feature creates a full record of every object configuration change, external write and component launch/update/connection in the system.

Before using Audit Trail, it is first necessary to Enable the Audit Trail Features as system administrator and select the Audit Trail changes that should be recorded. Once enabled, Audit Trail records can be visualized in the Audit Trail display.

The Audit Trail display can be opened from the Open menu (Open  Audit Trail) or from the context menu of an object in a model panel by right clicking and selecting Add item(s) to…​  Audit Trail.

Open Audit Trail Display
Figure 1. Open Audit Trail Display

Depending on when the Audit Trail features were enabled, some audit trail entries may already be visible. If the Audit Trail display was opened from the context menu for a particular object, then only the Audit Trail records for that object will be displayed.

The available menu bar options are as follows:

Table 1. Audit Trail Display Menu Bar Items
Element Shortcut Action

icon audit trail print 64

Print the Audit Trail output

icon refresh 02

F5

Refresh grid based on current time settings

icon export

Exports the current contents of the grid into selected file format and opens the file

icon time period

F6

Opens Time Period Setting dialogue

Object Filter box

-

Displays the name of any objects added to the display. Grid will then filter entries to display those corresponding to the object names.

Change Type Column Configuration box

Configures a preset column selection based on change type. Grid entries are also filtered to display those corresponding to the type of change.

icon grid auto resize columns

Ctrl+Alt+R

Automatically resizes all columns to fit content

Max Lines selector

-

Enter the maximum number of lines that should be displayed in the grid

Filter Time

-

Start and End Time for the currently displayed audit trail query

The footer of the Audit Trail Display contains fields giving information about the returned records and the times that queries were made. These fields are described below.

Table 2. Audit Trail Display Footer Fields
Field Description

Returned Time

Time range of returned data (timestamps of the first and last records returned in query).

Query Time

Time that the query was made.

Records

Number of records returned in the query.

By default, the Audit Trail Display can show a maximum of 1000 records. This value can be configured in the General Settings (shortcut F10) if required.

Selecting Columns and Adding Objects and Filters

The columns displayed in the grid can be changed by clicking on the column selector icon icon select column 32.

Audit Trail Display - Column Selector
Figure 2. Audit Trail Display - Column Selector

The displayed columns can also be configured using the drop-down menu in the menu bar. Based on the types of changes tracked by the Audit Trail, each option has its own preset selection of columns relevant to the change type. This drop-down menu will also filter the Audit Trail display to show only the entries which match the selected change type.

Audit Trail Display - Change Type Filter
Figure 3. Audit Trail Display - Change Type Filter

Dragging and dropping objects from the model panels will apply filters to the grid display, only displaying entries associated with those objects.

Audit Trail Display - Object Filters
Figure 4. Audit Trail Display - Object Filters

The filters can be cleared by clicking on the object filter box in the menu bar and clicking the delete icon icon generic tcp recycle bin 32.

Remove Object Filter
Figure 5. Remove Object Filter

Audit Trail Displays can also be filtered by pre-existing column entries. Column entries are listed in the drop-down menu for each column.

Pre-existing Entries in Drop-Down Menu
Figure 6. Pre-existing Entries in Drop-Down Menu

Selecting one of the entries in the drop-down menu will filter the display to show only those that match the specified input. For example, selecting '3' in the drop-down menu for the 'From Config Version' column will filter the Audit Trail Display entries to show only those from Config Version 3.

Column Filter by Pre-existing Entries
Figure 7. Column Filter by Pre-existing Entries

The maximum number of records displayed at once in all Audit Trail Displays can be configured in the General Settings (shortcut F10); the default value is 1000. In an individual Audit Trail Display, the maximum number of records can also be configured by changing 'Max Lines' in the menu bar. If the number of records exceeds the maximum value set, click Request more > to view them.

Audit Trail Display - Request More Records
Figure 8. Audit Trail Display - Request More Records

Examining Audit Trail Entries and Comparing Versions

Individual entries in the Audit Trail display can be examined further by using the available options in the context menu. To do this, select an entry and right-click.

Audit Trail Entry - Context Menu Options
Figure 9. Audit Trail Entry - Context Menu Options

The audit trail entry can be opened in the JSON Viewer to examine the record elements directly.

Audit Trail Entry - JSON Viewer
Figure 10. Audit Trail Entry - JSON Viewer

From the context menu, you can select to compare the record entry with the previous config version or with the current version. Selecting either of these options will open up the version difference viewer.

Audit Trail Entry - Compare Versions
Figure 11. Audit Trail Entry - Compare Versions

The difference dialog displays the chosen Audit Trail record entry and a comparison with either a previous config version or the current version. In the case of object configuration changes, the difference viewer shows the current and previous config versions of the object, represented as the syslib.mass Lua script needed to create the fully configured objects. The left column contains the previous config version and the right column the current version. The additions or deletions are highlighted in green and red respectively.

The menu bar options in the difference viewer allow you to navigate forwards and backwards through the different changes between the two config versions (making the change visible in the viewer without having to scroll). Using the find function, you can search for particular elements in the config versions.

Difference Viewer - Find function
Figure 12. Difference Viewer - Find function