Validated Instance - Audit Trail

Introduction

This document is a guide on how to use the Audit Trail feature to view detailed data change records.

Note

This feature is available with Flywheel Validated Instance.

Features

The Audit Trail is a detailed and immutable record of every creation, change to and deletion of data on the Flywheel system. The record includes:

When the change happened
Who performed the change
Where the change happened (Flywheel path to container/file + attribute name)
What the contents was of the change (including change reason)

In addition to changes to data, the Audit Trail also captures administrative events, such as locking/unlocking projects.

The Audit Trail record can be accessed by users both interactively, and in bulk from a downloadable report.

Permissions

These are the project permissions relevant to interacting with the Audit Trail feature.

Project Permission	Description
View Metadata	Viewing Audit Trail records for specific attributes of containers/files. This permission is included with all project roles.
Manage Audit Trail Reports	All deletions of data within projects, as well as projects themselves require a delete reason to be specified. This permission is included with the system default “admin’ project role.
View Audit Trail Reports	Viewing the status of, and downloading completed Audit Trail reports. This permission is included with the system default “admin’ project role.

Problems and Resolutions

Long Running Audit Trail Report

For large projects (over 1 million files) or projects that have high occurrences of updates/modifications to data, it may take an hour or more for the Audit Trail report to complete. This is expected due to the Audit Trail record tracking the change to each field individually. If the Audit Trail report for such large projects does not complete after 24 hours, contact Flywheel Support.

For smaller and less busy projects, if an Audit Trail report does not complete within 1 hour, contact Flywheel Support.

Non-Change entries in Audit Trail

Do not assume the presence of an Audit Trail Record constitutes a change. Both the Web UI Attribute Audit Trail, and the Audit Trail Report CSV will omit records that it determines did not constitute a change to the attribute value – that is, the previous and new values match.

Instruction Steps

How to Access Individual Attribute Audit Trail Record

The Attribute Audit Trail can be accessed directly from Subjects...

and Sessions...

And from any editable attribute on a Project, Subject, Session, Acquisition, File, or Analysis, such as Acquisiton Info...

and File Info...

Usage of the Attribute Audit Trail UI

From within the Attribute Audit Trail UI, you can view details of the specific Audit Trail record, and navigate to the Audit Trail records for other attributes on the same container, and parent containers.

This example represents the File Name value at creation time, for the echo.zip File, under the “Example US” Acquisition, “Cardiac CR” Session, “126” Subject, and “Cardiac Study Validated” project.

How to Navigate File/Container Level Audit Trail Records

The elements of the Flywheel path at the top of the dialog are clickable, to allow navigating up the Flywheel Hierarchy.

When viewing a container or file, each audit trail record can be expanded to show all the attributes affected by that event. The individual attributes can be clicked on to inspect the full Audit Trail history for that specific attribute.

How to Use Audit Trail Reports

Audit Trail Reports are available via the Project Menu.

With the Audit Trail Reports UI, reports can be created, cancelled, downloaded, and deleted.

By default, a report will contain records for all its subjects. A limited set of subjects can also be selected for inclusion in the report. This is useful for system validation and audit tasks where inspecting only a limited number of subjects is necessary.

Audit Trail Reports can be downloaded in CSV format, for satisfying requests of an audit or other investigation. The Flywheel system does not prune past audit trail reports automatically.