Skip to content

Flywheel Core 22.0

22.0.0

BREAKING CHANGES

Gears and Compute

GearKeyInput.read_only flag removed

The read_only flag on the GearKeyInput field of the gear manifest has been removed from the gear model. Existing gear manifests that still include this field continue to work - the value is silently ignored, and is no longer returned by the API. Gear authors may remove read_only from their manifests, but no action is required before upgrading.

Data Management

Analysis input filename APIs removed

The API endpoints for managing analysis input files by filename have been removed in 22.0.0. These endpoints had undefined behavior and could return inconsistent or incorrect results. Any direct API integrations or scripts that referenced analysis input files using filename-based endpoints must be updated before upgrading. Flywheel recommends using file ID-based endpoints instead. Refer to the deprecation notice for migration guidance, including SDK examples for the supported replacement APIs.

files_create_upload permission removed

The legacy files_create_upload project permission (labeled "File Upload/Create" in the web interface) has been removed. This permission was deprecated in release 19.3.0, when two more specific permissions — "Single File Upload/Create" and "Bulk File Upload" — were introduced to give administrators finer control over file upload access.

What users can expect:

  • No manual role changes are required. Project roles that previously had the legacy permission enabled have been automatically updated to include both replacement permissions, preserving prior upload capabilities.
  • Client applications must be updated. Any SDK scripts, custom integrations, or tooling that reference files_create_upload by name — including code that creates or modifies custom project roles — must be updated to reference the two replacement permissions instead. Calls that continue to reference the removed permission will fail.
  • Permission descriptions clarified. The descriptions for the two replacement permissions have been updated to more clearly describe which upload methods each one covers. See the Permission Matrix for details.

DEPRECATIONS

Gears and Compute

!!!! warning "Upcoming Breaking Change 23.0, October 2026"

1
2
3
4
5
Job output classification validation will be enforced by default for all sites.
Gears that produce outputs with invalid or missing classifications will fail
with a validation error, whereas previously such jobs would have proceeded.
Gear authors should ensure their gears emit classifications that match the
gear manifest before upgrading to Flywheel Core 23.0.

FEATURES

Viewers

The behavior of launching the Viewer at the file level now correctly reflects which viewer version is enabled and set as the default on the site. The file context menu now lists viewer options based on which viewers are active on the site, so users see only the relevant "Launch in Viewer" entries for their configuration.

V3 Viewer

The Viewer now schedules image data loading more efficiently, with improvements that will benefit users opening sessions with a large number of image datasets or loading many image series from the file browser:

  • The Viewer advances to the viewport as soon as the first image series is ready, allowing users to begin reviewing images immediately while the remaining image series continue loading in the background.
  • The left-side panel immediately displays a loading placeholder for every file in the study, replaced by the corresponding thumbnail as each image series finishes loading.
  • A progress bar helps users keep track of the status of image datasets being loaded in the left-side panel.

The annotations quick view has been redesigned to make measurement sets and their version history easier to understand:

  • Each measurement set now displays the version number, measurement count, creation date, and the avatars of both the set owner and any users who have contributed versions.
  • An overflow menu on each measurement set provides access to Version History, Download, and Delete actions.
  • Opening Version History shows a dedicated dialog with a full list of versions, each expandable to show individual labels and metrics.
  • Users can restore previous versions, download older versions, and see who deleted any removed versions and when.

The segmentation brush tool now supports pixel-based sizing in addition to millimeter-based sizing. Users can now choose whether the brush radius is measured in millimeters or pixels, and can draw segmentations down to a single pixel.

Logging of annotations activity in the audit trail has been improved:

  • Details about every single annotation within a measurement set is no longer logged into the audit trail to prevent audit trail from growing too big when users create a lot of annotations.
  • The audit trail path for a measurement set now includes the owner, ensuring each measurement set is uniquely identified when multiple sets on the same image share the same name but belong to different owners.

Additional UI/UX improvements:

  • Confirmation dialogs have been updated or removed when deleting measurements and closing measurements sets to provide a more intuitive user experience.
  • Link to documentation is now available in the Viewer footer bar when the one-click segmentation tool is selected.
  • Instructions and link to documentation are now available in the Viewer footer bar When the Slice Interpolation tool is selected.

Data Transfer

Amazon HealthImaging

Flywheel now supports Amazon HealthImaging (AHI) as both a Bulk Import source and a Bulk Export destination through External Storage. Administrators can configure an AHI datastore as an External Storage connection and grant import or export permissions, allowing users to move imaging data directly between Flywheel and AHI without staging in Amazon S3.

External Storage registration

Administrators can now control how each External Storage registration is used within Flywheel by assigning a permission mode — import only, export only, or both — directly from the user interface. When registering storage providers using the command-line interface (CLI), administrators can now supply relative paths in addition to absolute paths, reducing manual configuration effort and making registrations easier to reuse across environments.

Rule Sets

Data Transfer rule sets now support additional job options for import and export operations. Import rule sets can specify a scan parameters query to filter which files are discovered, a conflict strategy to control how duplicate files are handled, a fail-fast setting to stop processing on the first error, and a UID scope to control how unique identifiers are assigned. Export rule sets can specify a fail-fast setting. These options can be embedded directly in a saved rule set, so users do not need to supply them manually each time a job runs.

UX Improvements

  • Data Transfer services now produce clearer, human-readable error messages when a required dependency — such as the database or core API — becomes unreachable. Previously, these failures surfaced as generic import or export errors that were difficult to diagnose. Error messages now identify the specific unreachable dependency, include trace information, and include health probe details to accelerate root-cause analysis. In addition, the Data Transfer service now uses a dedicated Redis instance with guaranteed quality-of-service, improving stability during imports and exports when Flywheel is deployed in multi-service configurations.

  • When uploading DICOM files via the Case Uploader and a de-identification (de-id) error occurs for one file in a series, the upload interface previously showed an error state for every file in the series with no visual distinction between the root cause and the cascading failures. The upload interface now highlights the specific file that caused the de-id failure, making it immediately clear which file requires attention and reducing the time needed to diagnose and resolve upload errors.

  • The Case Uploader no longer shows the "Create New Upload" button while an upload form is in progress. Previously, clicking this button would discard all work entered in the current form without warning. The button is now hidden until the current upload completes, preventing accidental data loss.

  • The Legacy CLI (fw) now includes detailed documentation for rule set fields used with the import and export commands. Users can view field-level descriptions directly from the CLI when working with import and export rule sets, making it easier to configure rule sets without referring to external documentation.

  • The New CLI (flyw) no longer displays animated spinner output during import and export operations so outputs are easier to parse and redirect.

  • Resolved an issue that could interrupt long-running Data Transfer imports and exports.

Tasks Manager

When running batch gear jobs from a session, users can now select whether the gears run at the session level or the acquisition level. Previously, the execution level was determined automatically based on whether the gear had optional inputs — gears with no inputs ran at the session level while gears with optional inputs ran at the acquisition level. The new control gives users explicit, predictable control over how batch jobs are applied regardless of gear inputs.

Tag filters for batch task creation now support AND logic in addition to the default OR logic. Previously, a task was created or excluded whenever any one of the specified tags matched. Users can now set each filter type (include or exclude) to require all specified tags to match, giving teams more precise control over which sessions receive tasks.

Data Management

Bulk tagging from Search results is now generally available to all sites, including Validated instances. Users can add or remove multiple tags at once across subjects, sessions, acquisitions, files, and analyses selected from Search results. Users who do not have permission to modify tags on all selected items are blocked in the interface before the action is submitted.

The Create New Session dialog has been redesigned to address common usability issues. The updated dialog reduces the risk of accidentally entering a subject label into a session label field by making each field's purpose clearer. Users who have access to similarly named projects across different groups can now more easily identify and select the correct project. Timezone selection is also improved, with the list defaulted to the user's nearest region to reduce the effort required to find the correct timezone. The dialog has been updated to the current Flywheel UI design standard.

The Audit Trail UI now supports selecting and viewing attribute audit history for prior versions of a file. Previously, users could only inspect the current version, making it impossible to review how attributes changed across earlier file versions without using the API directly.

The audit trail report now includes project-level activity. Changes to project metadata (such as permissions, lock status, custom information fields, and gear rules), as well as uploads, deletions, and modifications to project-level files and analyses, are captured in the report alongside existing subject-level entries.

The Usage Report table now includes a File Count column, showing the number of files added during the selected date range.

The Extension Applications SDK supporting custom viewer apps now includes a method for retrieving gear job status. Extension developers can use this method to trigger a gear job and then poll for its completion state — such as Complete, Failed, or Cancelled — before proceeding with subsequent actions in their workflow. This enables Extension Applications to build coordinated, job-aware workflows without requiring direct access to internal platform APIs.

FIXES

Viewers

V3 Viewer
  • Canceling the save dialog when exporting measurements to a DICOM Structured Report (SR) no longer triggers an error notification.
  • Loading a segmentation file and then switching to the 3D four-up viewport layout no longer causes the "Hide All" segmentation control to stop working.
  • The Jump to Slice feature now works for segmentations when using an advanced layout that includes a 3D viewport.
  • Issues with loading DICOM segmentation (SEG) files packaged as a ZIP archive in the Viewer have been fixed.
  • Clicking the hide icon on a measurement Label group for the first time after loading a measurement set now hides all measurements under that label on the first click, instead of requiring two clicks.
  • The "Save As" button is no longer incorrectly disabled for users with file creation permissions.
V2 Viewer
  • Resolved an issue where opening Siemens Mosaic data caused sessions to hang or load slowly.

Data Transfer

  • Fixed an issue in Data Transfer where the conflict count displayed an incorrect negative value (such as -2) instead of the actual number of conflicts.
  • Fixed an issue where listing storage locations stopped working after the introduction of storage prefixes in a prior release. Users were unable to view available storage options as expected.
  • Fixed an issue where storage could be created with both the import and export options disabled, resulting in a storage configuration that could not transfer data in either direction. The system now requires at least one transfer direction to be enabled when creating storage.
  • The estimated time remaining displayed during a Bulk Import was significantly overstated. The prediction now reflects a more accurate estimate.
  • Uploading gzip-compressed files (such as NIfTI .nii.gz files) through the Web Uploader no longer fails when de-identification is enabled.
  • Resolved an intermittent 422 - no such blob session error when uploading data through the Case Uploader. The error occurred due to a timing gap in the database where a newly created upload session was not yet visible to all database nodes when the next upload request arrived.
  • When configuring a Bulk Export to Amazon HealthImaging (AHI), the export form no longer displays options for storage prefix, overwrite handling, and deletion of pre-existing files. These options apply only to blob-based storage destinations and are not applicable to the DICOM-based storage model used by AHI.
  • Updating the new CLI (flyw) no longer fails with the error No module named 'pydantic_core._pydantic_core' when dependent packages are missing or partially installed. The update process now uses atomic file operations to ensure all required packages are fully installed before the update completes.
  • C-MOVE operations using the DIMSE (Digital Imaging and Communications in Medicine Service Element) service now succeed when retrieving DICOM studies that use compressed transfer syntaxes (such as JPEG 2000 or JPEG-LS).

Legacy Tasks

  • Completed reader tasks can now be reopened correctly even when image data outside of the task container was opened through the Nav Panel before task completion. Previously, re-opening a completed reader task would fail to render the protocol form and the Viewer displayed a RightSidePanel: Cannot read properties of undefined (reading 'findDisplaySet') error instead of the saved form data.

Tasks Manager

  • Users without multi-factor authentication (MFA) enabled can no longer assign tasks requiring an electronic signature to themselves.
  • Status changes in the Tasks Manager are now reflected in the task list in real time, removing the need to manually refresh the page to see updated statuses.
  • The Tasks Manager Protocol column now displays both the protocol name and version, making it consistent with the protocol filter dropdown.
  • When creating tasks at the file level in projects containing both DICOM and non-DICOM files, the confirmation message now shows only the count of DICOM files eligible for task creation.
  • During task creation, users can no longer select a group or project that has no associated protocols, eliminating an error that previously surfaced at the final step.
  • The Create button in the Create Reader Task dialog is now correctly disabled when the required Assignee field is empty.
  • The Save Draft button for Reader Tasks in the Viewer no longer appears active when switching between the Measurements and Forms panels without making any changes, and no longer remains highlighted after saving draft measurement changes.
  • The user filter now closes correctly after a selection is made or when clicking outside of it.
  • The Protocols tab is no longer displayed in the Admin Groups interface when the Tasks feature is not enabled.

Data Views

  • Reordering columns while editing a Data View now activates the Save button, so users can save their column order changes without making an unrelated edit first.
  • Exporting Data Views reports to JSON-flat or JSON-row-column format now applies the selected format structure to the output file, instead of producing output identical to standard JSON.
  • Refreshing the page while on the Data Views Queue tab no longer redirects users to the Data View tab.
  • Data View execution now succeeds when an "is not" filter contains more than one value. Using an "is not" filter or the SDK !=| operator with multiple values now executes correctly.
  • The Reset button in the Data View filter editor is no longer enabled when no filter changes have been made.
  • When a Data View contains both analysis columns and file columns, the analysis columns now appear in the executed results, matching the columns visible in exported result files.
  • Fixed an issue where the aggregation method selector for custom fields was unavailable, preventing users from changing the aggregation method.

Gears and Compute

  • Custom values entered in the gear configuration dialog for one gear are no longer carried over to a different gear when the gear selection changes; the dialog now correctly resets to the newly selected gear's default values.
  • In the job details view, moving a job's input file to a different project no longer causes both an active and a disabled file actions menu to appear side-by-side.
  • Uploading the same gear version simultaneously no longer creates duplicate gear entries.
  • The Create New Gear Rule form no longer displays validation errors on fields immediately upon opening; validation errors now appear only after the user interacts with the form.
  • Adjusting gear configuration fields with the increment/decrement arrows now correctly applies the updated values when the gear runs, instead of submitting the original defaults.
  • The gear run modal now displays the output container selection field when a gear requires a destination container, allowing users to run such gears.
  • Default Gear Rule templates are no longer duplicated each time a site is updated or redeployed; templates are now created only once at site initialization.
  • The subject label now appears in job details when the subject was identified using the deprecated subject.code field rather than subject.label.
  • The View Log buttons on the Sessions Provenance tab are now vertically aligned with their corresponding entries.

Jupyter Notebooks

  • The "Reason for deletion" field has been removed from the JupyterLab workspace deletion dialog, as it applies only to governed data objects rather than compute resources.
  • Launching a JupyterLab server with the Large-Compute-GPU option now succeeds on attempts after the first. Previously, users who stopped and tried to restart the server would find it did not launch.
  • Resolved an issue that prevented launching analysis jobs in certain environments.

Data Management

  • Fixed an issue where the UI froze in an empty state and did not automatically prompt re-authentication when a user returned to a Flywheel viewer app after a period of inactivity. The authentication prompt now appears automatically when a session expires due to inactivity.
  • Fixed an issue where users navigating directly to a Flywheel viewer app URL without an active session were not redirected back to their original URL after login. Users were deposited at a default page instead of the resource they had requested. After completing authentication, users are now returned to the original URL they attempted to access.
  • Resolved a search indexing service issue that caused indexing to fall behind on sites with large data volumes. Previously, newly added custom metadata fields did not become searchable and the "Site data being indexed" status banner persisted indefinitely.
  • Sites that experienced stalled data indexing after upgrading to 21.6.1 — displaying a persistent "data is being indexed" state — can now complete indexing successfully.
  • Fixed an issue where file counts in usage reports were inflated by analysis input file references.
  • Fixed an issue where the audit trail panel could hang indefinitely, or not display the originating user.
  • The "Replace File" tooltip on the attribute audit trail screen now displays the expected description text instead of an empty tooltip.
  • Deleting a single session from the session list now updates the list immediately, instead of requiring a manual page reload.
  • The confirmation dialogs displayed when deleting a subject, session, or acquisition now use the standard dialog style consistent with the rest of the web interface.
  • Fixed incorrect indentation on the Subjects > Sessions page so that session headers, acquisition header checkboxes, labels, and file names align consistently.
  • The Create New Session option has been removed from search results, where it was not applicable.
  • Field filter inputs in the Smart Copy dialog and the Data Views filter dialog now suggest values when typing.
  • Tag chips in the bulk add/remove tags dialog now render with updated colors that keep the label text legible regardless of the tag color assigned.
  • Tag filter chips in the search results panel now render with sufficient contrast so that all tag labels remain legible.
  • In the web UI, site admin users were unable to use the Download, Run Batch, Move, Delete, and Modify Tags actions on items in the session list, subject list, and search results, when they did not hold any role on the project.
  • User permission avatars on the Projects page no longer flicker after adding a second member to a project that previously had only one.
  • The Role column tooltip in Admin > Users now correctly reflects each project's Lightweight Directory Access Protocol (LDAP) status, instead of incorrectly indicating LDAP management for projects that do not have LDAP enabled.
  • The Session Templates Sessions tab now displays the count of flagged (non-compliant) sessions.

Python SDK

  • Calling find_task_protocols() no longer raises a RuntimeError due to an incorrect type string in the CustomField model.
  • Calling fw.get("") with an empty string now raises ValueError: container_id cannot be empty instead of returning a misleading credentials error.