Skip to content

Restore Deleted Data with the Python SDK

Introduction

Use the Flywheel Python Software Development Kit (SDK) to restore files, acquisitions, sessions, and subjects that were deleted. The same operations are available through the Flywheel API. The Web App does not include a restore option.

Added in version 23.1.0

Restore only permitted data

Administrators are responsible for restoring only data that is permitted on the site. Do not restore data that was deleted on purpose, such as data that contained Protected Health Information (PHI) or other information that is not approved for the site.

Before You Begin

  • You need the Admin project role on the project that held the deleted data, or site administrator access. The permissions to restore deleted data are part of the default Admin project role.
  • The project must not be locked.
  • You need the ID of the item to restore. Deleted items do not appear in the Web App, so see Find the ID of Deleted Data.
  • You need the Flywheel Python SDK, version 23.1.0 or later, and an API key. See APIs and SDKs.

Find the ID of Deleted Data

Start from the Access Log, which a site administrator can filter and download.

  1. Generate an Access Log report filtered to the project and to the delete_container and delete_file access types, and to the date range of the deletion.
  2. Download the report as a CSV file. Each row identifies the subject that held the deleted data in the subject.id and subject.label columns.

Then find the ID for the type of item you want to restore:

  • Subject: Use the subject.id value from the Access Log CSV. A delete_container row also records deletions of sessions and acquisitions within a subject, so preview the restore with a dry run first. If the subject is not deleted, the dry run reports a not_deleted conflict.
  • Session, acquisition, or file: Starting in Flywheel 23.2.0, create an Audit Trail report filtered to the subject from the Access Log. The report includes each item's ID and file version as separate columns. Before 23.2.0, contact support, and provide the Access Log CSV filtered to the delete events of the data you need to recover.

What a Restore Brings Back

A restore brings back the item and everything that was deleted with it. Anything deleted separately before the item stays deleted.

Item restored Also restored
File Every version of the file that was deleted at the same time as the version you restore
Acquisition Its files, and its analyses with their output files
Session Its files, its acquisitions and their files, and its analyses with their output files
Subject Its files, its sessions, their acquisitions and files, and its analyses with their output files

Restored items reappear in search, and Flywheel rechecks session template compliance for the restored sessions. Restoring data does not trigger Gear Rules or other automation that runs when data is created.

When Audit Trail is enabled, each restored item receives an UNDELETE record in the Audit Trail.

How Flywheel Checks a Restore

Flywheel checks every restore before it changes any data. If any check fails, Flywheel restores nothing and reports each conflict, so you can resolve them and try again.

A restore fails when:

  • The item, or a container above it, is still deleted. Restore the container above it first.
  • An active item in the same place already uses the same label, or the same DICOM identifier.
  • An item in the restore was permanently deleted.
  • An analysis in the restore uses an input file that is still deleted.
  • The restore contains more than 10,000 items. Contact support to restore more than 10,000 items at once.

Preview a Container Restore

For acquisitions, sessions, and subjects, a dry run reports what a restore would bring back and any conflicts, without changing any data.

  1. Connect to Flywheel with your API key:

    1
2
3
    import flywheel

fw = flywheel.Client('<YourAPIKey>')

  2. Run the restore with dry_run=True. Use undelete_acquisition, undelete_session, or undelete_subject to match the item:

    1
    result = fw.undelete_session('<session-id>', dry_run=True)

  3. Review the result:

    1
2
3
4
    print(result.total)   # Number of items the restore would bring back
print(result.counts)  # Number of items of each type
for conflict in result.conflicts:
    print(conflict.type, conflict.container_type, conflict.id, conflict.detail)

    result.conflicts lists up to 10 conflicts, and result.conflict_count reports the total.

  4. Resolve any conflicts, then run the dry run again until it reports none.

Restore an Acquisition, Session, or Subject

  1. Run the restore without dry_run:

    1
2
    result = fw.undelete_session('<session-id>')
print(result.restored, result.total, result.counts)

  2. Review result.warnings. Warnings do not stop the restore. For example, when a restored file has a malware finding, the warning names the finding, and the finding returns to the triage queue for review.

If the restore has conflicts, the request fails with a 409 error and restores nothing. Run a dry run to see the conflicts.

Restore a File

Restore a file by its file ID:

1
result = fw.undelete_file('<file-id>')

By default, Flywheel restores the current version of the file and every other version that was deleted at the same time. To restore from a specific version, pass its version number:

1
result = fw.undelete_file('<file-id>', version=2)

File restores do not offer a dry run. If the restore has conflicts, the request fails with a 409 error and restores nothing.