Enabling Audit Trail

The Audit Trail functionality allows changes within a system to be tracked and then recalled on demand to enable full auditing of changes to a system. This include configuration changes, component launches and connections, time changes and others.

This section will give details on how to first activate and enable Audit Trail and use the available features.

The enabling and disabling of Audit Trail features is a task that should only be undertaken by system administrators. Changes should not be made to production systems without first being aware of the effects and consequences of changing Audit Trail settings and the potential regulatory compliance issues that may result.

Admin Enabling of Audit Trail

Users must have system administrator privileges to be able to activate Audit Trail. Log in to DataStudio as either the "Administrator" User using Windows Authentication or the "so" profile with Profile Credentials Authentication.

Figure 1. Log in to DataStudio as System Administrator

Go to the Access Model and select the so Profile object. In the Object Properties panel, open the Common and then Audit Trail Roles property compounds and select the checkboxes for Administrator, System-wide Reviewer and Limited Reviewer. Click Apply to confirm the changes.

Figure 2. Profile Object - Special Roles, Audit Trail

The different roles allow different permissions for users under the designated Profiles to make changes related to Audit Trail. The Administrator can enable and disable the Audit Trail across the system and update the Audit Trail Strategy. A System-wide Reviewer can view and retrieve all Audit Trail entries. A Limited Reviewer can view and retrieve Audit Trail entries for objects they have Read access to.

Go to the menu bar at the top of DataStudio and select Admin Edit Root Object to open the Edit Root dialog.

Figure 3. Open Edit Root Object

The Admin menu options will only be visible when logged in as Administrator or with the "so" profile.
In the Edit Root dialog, select Audit Trail from the sidebar.

Figure 4. Edit Root Dialog
In the Audit Trail section, select the Enable checkbox.

Figure 5. Audit Trail Root Options - Enable Audit Trail
Once the enable checkbox is selected, then the other Audit Trail options become available. Also, the comment box is now visible at the bottom of the dialog.

Figure 6. Audit Trail Root Options - Enable Audit Trail All Options
Expand the other Audit Trail options in the Edit Root dialog. The Audit Trail settings configured for the Root object will be inherited by ever other object in the system by default. Select the Comment required on property change(s) to require that a comment be added for all configuration changes. Select all the remaining checkboxes to record all changes related to object configuration (including external writes) and components.

Figure 7. Audit Trail Options - Select All
Click Apply to confirm the changes and you should be greeted with an immediate error reminding you that you must enter a comment when making property changes (this is because the Comment required on property change(s) checkbox was selected).

Figure 8. Comment Required Error
Click OK to close the Error dialog and then enter a comment in the bottom of the Edit Root dialog to satisfy the new Audit Trail requirements. Click Apply and then OK to close the Root Settings.

Figure 9. Comment Entered to Make Configuration Changes
To check that the Audit Trail settings are now working, select an object in the namespace and make a change to one of the properties (for this example we will change the Description for a Gen Item). The new Audit Trail settings mean that you will not be able to click the Apply button until a comment has been entered.

Figure 10. Example of Property Change on Gen Item
Enter an update comment into the field to unlock the Apply button and then click on Apply.

Figure 11. Enter Comment for Property Change

Viewing Audit Trail Entries

To view the entries into the Audit Trail for a particular object, click on the Audit Trail Tab in the Object Properties panel. This will display the recorded Audit Trail entries for the object.

Figure 12. Audit Trail Tab - Object Properties Panel
The change to the object Description field is visible along with the timestamp of the change, the config version of the object prior to the change and the entered comment (other columns can be added to the table by clicking on the Column Selection button in the top left-hand corner of the table). Right-click on the entry and select Compare with Previous Version from the menu to open up the difference viewer.

Figure 13. Audit Trail Tab - Compare Config Version Differences
This 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 Audit Trail entries for multiple objects can also be viewed by adding objects to an Audit Trail display. To open a display select Open Audit Trail in the menu bar. Objects can be dragged and dropped from the model panels into the display.

Figure 14. Audit Trail Display
The Audit Trail Display allows you to retrieve the Audit Trail entries from the Audit Trail Data Store and filter by time (using the time picker in the toolbar) and object (by adding or removing objects from the display). The data can also be exported into different formats by clicking on the export button.

Retrieving Audit Trail Entries with Lua

Audit Trail entries can also be retrieved using the Lua API using the 'getAuditTrail()' function in the 'inmation.AuditTrail' library. Please visit the Lua Audit Trail documentation for more information and examples.