Skip to content

Validated Instance - Audit Trail


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


This feature is available with Flywheel Validated Instance.


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:

  1. When the change happened

  2. Who performed the change

  3. Where the change happened (Flywheel path to container/file + attribute name)

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


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


Audit Trail reports can exceed millions of rows and multiple gigabytes in real-word scenarios, making the use of Microsoft Excel and similar tools unable to process them. It is up to the customer to determine and implement alternative methods that will satisfy their needs -- such as loading the csv into a RDBMS where SQL queries can be used.

Fields in the CSV Report

Field Description
Timestamp Date & Time of the event in UTC
Path The Flywheel path to the container/file that was acted on
Field The container/file field that was affected by the event
Value The new value that the field was set to – possible that the new value is the same as the prior value.
Operation The type of operation – CREATE/REPLACE_FILE/UPDATE/DELETE/ADD
Origin The type of identity the operation originated from – user/job/device
User The id of the Origin –
Reason The Reason supplied for controlled operations – Delete/Project Lock

Example of the CSV report contents... Pic10.png


  1. Delete Reason

  2. Validated Instance Overview