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

  1. 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.

    Log in to DataStudio as System Administrator
    Figure 1. Log in to DataStudio as System Administrator
  2. 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.

    Profile Object - Audit Trail Roles
    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.
  3. Go to the menu bar at the top of DataStudio and select Admin  Edit Root Object to open the Edit Root dialog.

    Log in to DataStudio as System Administrator
    Figure 3. Open Edit Root Object
    The Admin menu options will only be visible when logged in as Administrator or with the "so" profile.
  4. In the Edit Root dialog, select Audit Trail from the sidebar.

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

    Audit Trail Root Options - Enable Audit Trail
    Figure 5. Audit Trail Root Options - Enable Audit Trail
  6. 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.

    Audit Trail Root Options - Enable Audit Trail All Options
    Figure 6. Audit Trail Root Options - Enable Audit Trail All Options
  7. 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.

    Audit Trail Options - Select All
    Figure 7. Audit Trail Options - Select All
  8. 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).

    Comment required Error
    Figure 8. Comment Required Error
  9. 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.

    Comment Entered to Make Configuration Changes
    Figure 9. Comment Entered to Make Configuration Changes
  10. 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.

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

    Enter Comment for Property Change
    Figure 11. Enter Comment for Property Change

Viewing Audit Trail Entries

  1. 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.

    Audit Trail Tab - Object Properties Panel
    Figure 12. Audit Trail Tab - Object Properties Panel
  2. 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.

    Compare Config Version Differences
    Figure 13. Audit Trail Tab - Compare Config Version Differences
  3. 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.

  4. 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.

    Audit Trail Display
    Figure 14. Audit Trail Display
  5. 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 'syslib.AuditTrail' library. Please visit the Lua Audit Trail documentation for more information and examples.