Skip to content

Flywheel Core 23.1

23.1.0

DEPRECATIONS

Data Transfer

Legacy CLI (fw) commands deprecated

Flywheel 23.1.0 deprecates the following commands in the Legacy CLI (fw), and plans to remove them in Flywheel 24.0, no earlier than March 2027:

  • All fw ingest commands
  • fw sync
  • fw export bids
  • fw bids validate
  • fw deid test
  • The fw job and fw admin commands

Each time a deprecated command runs, it prints a warning that names the removal release, the replacement command, and a link to instructions for switching:

1
2
'<command>' is deprecated and will be removed in Flywheel 24.0 (no earlier than March 2027).
 Use <replacement> instead. How to switch: <link>

The warning prints to stderr, so command output and exit codes do not change, and existing scripts continue to work. Help listings mark deprecated commands with a [DEPRECATED] prefix. Until they are removed, the deprecated commands receive only security fixes and critical bug fixes.

On the Profile page, the Flywheel CLI section now lists the New CLI (flyw) first, marked Recommended, and moves the Legacy CLI (fw) into a collapsed Classic (Legacy) section marked Deprecated.

Use the New CLI (flyw) instead:

  • Bulk Export (flyw export run) replaces fw sync, including analysis export. With the Brain Imaging Data Structure (BIDS) export rule set, it also replaces fw export bids.
  • Bulk Import (flyw import run) with a rule set replaces the fw ingest commands that import data, such as fw ingest dicom, fw ingest folder, and fw ingest template. Use the BIDS rule set in place of fw ingest bids.
  • flyw import get and flyw import cancel replace fw ingest follow and fw ingest abort.
  • flyw utils deid replaces fw deid test.
  • flyw job retry replaces fw job retry.

FEATURES

Data Transfer

Project Transfer

The New CLI (flyw) adds the flyw transfer command, which copies a whole project from one Flywheel site to another. The destination site imports the files directly from the source site, so no files pass through your computer. The transfer keeps running if you close the CLI or press Ctrl+C, and the command prints the commands to follow its progress.

Start a transfer from the source site's login profile, and name the destination site's login profile with -d, for example flyw -P site-a transfer -p fw://group/project -d site-b. The command shows live progress for the export and the import, then summarizes the files transferred, skipped, and failed. By default, the project keeps its group and label on the destination site, and the command creates the project there if it does not exist. The destination group must already exist. Use --destination-project to choose a different destination project, --level, --include, and --exclude to limit which files transfer, and --conflict-strategy to control how files that already exist in the destination are handled. Transfers run under a user's API key, not a device key. Before the first transfer, Flywheel must configure each site as a trusted peer of the other, and the two sites must be able to reach each other.

Case Uploader

Case Uploader now supports configurable forms, so teams can collect the information they need about each acquisition at the time of upload, instead of tracking it outside Flywheel. Users who can manage session templates attach a form to an acquisition in a session template, from the Attach Form dialog on the project's Templates tab. The dialog lists the published Upload forms in the group's form library, and can also create and publish a new form. When a user uploads data for that acquisition, Case Uploader shows the form on the Acquisition Details step, and the user cannot continue until the form is valid. Questions can appear, disappear, or become required based on earlier answers.

Flywheel saves each response in the acquisition and file metadata (info.upload_form), and also records it in a new Upload task. In Tasks Manager, the Upload view lists these tasks, and the task details dialog shows the form, its version, and the submitted answers.

Case Uploader no longer includes a built-in default form. When no form is attached to the acquisition, Case Uploader skips the Acquisition Details step, and still records an Upload task without a form.

When a user enters a label that matches an existing subject in the Case Uploader Add New Subject dialog, the dialog now names that subject and its project, shows the subject's number of sessions and last upload date, and offers a Select This Subject button to use the existing subject instead. The dialog also shows how many of the 64 allowed characters are used, starts with any text already typed in the subject search box, and saves when the user presses Enter. New subjects are marked as new in the subject list.

Data Management

Restore deleted data with the Python SDK

Administrators can now restore deleted files, acquisitions, sessions, and subjects through the Python Software Development Kit (SDK) and the API. This gives teams a controlled, auditable way to recover records that were deleted. This release provides Python SDK and API access only; the Web App does not include a restore option.

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.

Restoring a file brings back every version of the file that was deleted in the same action. Restoring an acquisition, session, or subject also brings back the items that were deleted with it: the containers beneath it, their files, and analyses with their output files. Anything deleted separately before the container stays deleted. Restored items reappear in search, and do not trigger Gear Rules or other automation that runs when data is created.

Restoring requires the permission to restore deleted data on the project, which project administrators receive automatically, or site administrator access.

Flywheel checks every restore before it changes any data. If a check fails, such as when an active item already uses the same label, a parent container is still deleted, or an item was permanently deleted, Flywheel restores nothing and reports the conflicts so the administrator can resolve them and try again. For acquisitions, sessions, and subjects, a dry run option previews what a restore would bring back without changing anything. By default, a single restore of more than 10,000 items requires help from Flywheel Support.

When Audit Trail is enabled, each restored item receives an UNDELETE record in the Audit Trail, which gives regulated teams a traceable history of every restore. See Restore Deleted Data with the Python SDK.

Tasks Manager

Forms

A new site-level Forms page lists the forms from all groups in a single list, so site administrators can view and manage forms across the site in one place. The list loads forms one page at a time to stay responsive on sites with many forms. To create a form, use the form library of a group.

FIXES

Data Transfer

Bulk Import
  • Bulk Import now reports a file as failed, or skips it when missing metadata handling is set to skip, if the file has no label for the container level that its import rule targets. Previously, such a file was added to the next container up, for example to a session instead of an acquisition.
  • Imports from cloud storage now ignore zero-byte objects, including the folder placeholder objects that some storage providers create, instead of listing them as skipped files in the import report.
  • Bulk Import now accepts manifest files saved as UTF-8 with a byte-order mark (BOM), such as the CSV UTF-8 (Comma delimited) format in Excel. Previously, uploading such a manifest could fail with the error Manifest missing required column: src_path, or the import could skip its rows.
  • The malware scanner now scans files of up to 1 GB during Bulk Import, up from 500 MB. Larger files still import, and the import report shows their scan as skipped.
  • Fixed an issue where an import retried a file repeatedly when the import ran out of temporary storage. The file now fails right away, and the import report gives the reason Temp disk full. To import such files, contact Flywheel Support to increase the temporary storage.
  • Fixed an issue where very large imports, with millions of files, repeatedly stalled and slowed down.
Bulk Export
  • Fixed an issue where exports could fail because the data transfer service ran out of memory.
DICOM Router
  • The DICOM Router now applies the import settings in a data processing rule's rule set, label, conflict_strategy, fail_fast, and uid_scope, to the studies it imports. Previously, Flywheel accepted these settings, but the DICOM Router ignored them.
  • Setting zip_single to false in a DICOM Router data processing rule now imports a series that contains a single instance unzipped, under the instance's file name. Previously, the DICOM Router still zipped the series, and only removed the .dicom.zip extension from the archive name.
  • Fixed an issue where sending a very large DICOM file, such as a file of 10 GB or more, to the DICOM Router could end with the sending device reporting Peer aborted Association, even though the import succeeded. The DICOM Router now responds sooner after it receives a file, and sending the same file again while the first transfer is still in progress no longer stores an incomplete copy. When the DICOM Router reaches its limit of simultaneous connections, it now rejects new connections with a temporary congestion response, so the sending device can retry later.
New CLI (flyw)
  • Fixed an issue where flyw import run could fail with a ReadTimeout error when importing from a local folder, especially over a slow or shared connection. The New CLI (flyw) now limits how many file chunks it uploads at the same time across all files, and waits longer and retries more before an upload fails.
Case Uploader
  • Fixed an issue where Case Uploader could display a different user name than Flywheel Core when the user's name differed between the identity provider and Flywheel. Case Uploader read the name from the identity provider, while Flywheel Core read it from its own database, so it appeared that different users were signed in to each application. Case Uploader and Flywheel Core now display the same name.
  • Conditional questions in Case Uploader forms now appear and disappear as soon as the controlling answer changes. Previously, selecting an option from a dropdown list showed the questions for the prior selection, and turning on a switch did not show the questions that depend on it.

Data Management

  • Fixed an issue where the project Information tab, the Session tab, and the Acquisition tab stopped responding when a project, session, or acquisition had more than 1,000 attachments. Users could not open any other tab and had to close the browser window to recover. The attachments table now loads attachments in pages instead of all at once.
  • Fixed an issue where the Web App became unresponsive when viewing acquisitions that contain a large number of files.
  • Fixed an issue where the session list took more than one minute to load on sites with a large number of sessions, even for users with access to only a few sessions.
  • Fixed an issue where the session list returned a server error (500) when users filtered sessions and sorted them by project label.
  • Fixed an issue where an acquisition continued to appear after the last session was deleted, and refreshing the view displayed an error.
  • Fixed an issue introduced in 23.0.0 where Flywheel accepted uploads of files whose names contained a non-printable control character or a double quote ("), and stored them under a modified name, such as %22. Flywheel again rejects these uploads with the error 422 Invalid file name.
  • Fixed an issue where moving a file into a container where the user has read-only access returned the error File with this name already exists instead of the permission error User does not have permission to files_move. The incorrect error also revealed that a file with that name existed in the destination.
  • Fixed an issue where session templates flagged a session when the template required multiple classifications on a single file and the file had all of them, whether the classifications were entered in exact mode or matched with a regular expression (regex).
  • Fixed an issue where selecting session.age_in_years as an include or exclude filter in Smart Copy caused the copy to fail with the error invalid field: 'session.age_in_years'. Smart Copy no longer offers session.age_in_years as a filter field; the session.age filter remains available.
  • Fixed an issue where the Cancel and Copy buttons were hidden in the Smart Copy dialog when the browser developer tools were open. The dialog now adjusts its width to fit the available space.
  • Fixed an issue where image files uploaded as ZIP archives, such as .jpg.zip files, did not sync to Video Annotation. Files that already failed to sync are not repaired, so upload those files again.

Audit Trail

  • The Audit Trail report now lists only the metadata field that changed when a user edits a single value in the Web App. Previously, changing one field, such as the sex of a subject, caused the report to log a change in every metadata field on that container.
  • Audit Trail reports now include the form_id and form_version fields for submitted form responses, which identify the form and form version used for each response.
  • Fixed an issue where Audit Trail report generation failed without explanation for a project whose change history contained only a deletion record. Audit Trail reports now include these records.
  • Fixed an issue where Audit Trail reports could not be downloaded after the project was renamed.

Usage Reporting

  • Fixed an issue where Usage Reporting failed to load when grouped by month, and displayed the error Couldn't Load Usage Data.

Site Administration

  • Fixed an issue where some sites did not consistently enforce their sign-in method settings.
  • Fixed an issue where adding group permissions to a user required selecting Save twice: once in the Add Permissions dialog and again on the permissions list. Selecting Save in the Add Permissions dialog now saves the new permissions.
  • Fixed the Security Champion filter on the Admin Users page so that it lists deactivated users who hold the Security Champion role.
  • Long group names now display with an ellipsis, so they no longer overlap the group ID.

Web App

  • Fixed an issue where navigation stopped working in a browser tab left open across a Flywheel upgrade. Selecting another page briefly started to load it, then returned to the current page until the user reloaded the browser tab.

Gears and Compute

  • The Save button is now disabled when a Gear Rule Template uses a gear with Multiple Files Input and no triggering input is selected. Previously, a site administrator could save the template without a triggering input.
  • Fixed an issue where job logs showed extra line breaks in the middle of a log message, which split long lines, such as DICOM fields, across multiple lines. Job logs on the Provenance tab and the Jobs page now display such a message on a single line and preserve its indentation.
  • Fixed an issue where the Jobs page could fail to load on sites with a very large number of jobs, and timed out after several minutes.
  • Fixed an issue on the Jobs page where dismissing a bulk action confirmation, such as Retry Jobs, cleared the job selection, so reopening the confirmation showed Are you sure you'd like to retry 0 job(s)? and acted on no jobs. Dismissing a confirmation now keeps the selected jobs, and the selected job count next to the Actions button updates after a confirmed action.

Tasks Manager

Protocol Builder
  • Fixed an issue where retrying a failed publish after editing a protocol published the previously saved version without the new edits, and gave no indication that the edits were missing. A retry now saves the latest edits before publishing.
  • Saving an existing protocol in the Protocol Builder no longer removes viewer settings that the builder does not show, such as Early Treatment Diabetic Retinopathy Study (ETDRS) grid settings set through the API. Previously, the save removed these settings without warning.
  • Adjudication protocols created with the Protocol Builder no longer include an unsupported form_id entry, which the code editor flagged with Property form_id is not allowed. Previously, saving an edited version in the code editor disabled the Publish button and displayed Protocols is missing form.
  • Fixed an issue where triggered fields configured in older Viewer Protocols did not appear in the protocol and form editor, even though they still appeared in the viewer when a task that used the protocol was launched.
  • The Protocol Builder no longer opens the protocol JSON editor after a user saves a draft or publishes a new protocol. The Protocol Builder dialog now closes and returns to the protocol list, where the new protocol appears with a success notification.
  • Publishing a draft protocol from the Review & Publish step no longer displays the error Unable to load notification when the protocol and its draft form publish successfully.
  • The form version comparison no longer shows a blank field error for the current form version, and the Protocol Builder now shows a success or error notification when a protocol edit is saved.
  • The tooltip on the Archived indicator in the Protocols tab now shows the user who archived the protocol, the date, and the last published version.
Tasks and Forms
  • Fixed an issue where an In Progress task became stuck when the assigned user's role was removed from the project. The task was unassigned but remained In Progress, so it could not be reassigned or moved back to To Do.
  • Fixed an issue where Forms and Annotations task reports failed to generate, and could not be downloaded, for some reader and adjudication task protocols, including protocols with tasks created before the adjudication data upgrade.
  • Cloned tasks now include the measurements from the source task. Tasks cloned before this fix are not updated, so clone them again to include the measurements.
  • Conditional questions in forms now appear and disappear as soon as the controlling answer changes, without requiring a click elsewhere on the form. Conditional questions that depend on a specific radio button option now appear only when that option is selected.
  • Tasks Manager now displays an error when the task list fails to load or a task filter fails to save, and keeps the previous value when a task update fails. The due date tooltip now shows the correct year.
  • The staffing pool name is now marked as required, and Flywheel no longer accepts a staffing pool name that contains only spaces.

Legacy Tasks

  • Creating Legacy Tasks for a batch of sessions no longer stops at 100 tasks. Flywheel now creates tasks for up to 1,000 sessions in one batch, and displays an alert when a selection exceeds that limit.

Viewers

V2 Viewer
  • Fixed an issue where DICOM segmentation (SEG) files from an analysis did not appear in the series panel, and could not be loaded into the viewport with Load Mask.
V3 Viewer
  • Fixed an issue where the mean, maximum, and standard deviation statistics of closed Freehand regions of interest (ROIs) changed when users switched between the stack layout and an advanced layout, or changed the zoom level.
HTML Viewer
  • Fixed an issue where links to files, such as images, within an .html.zip file did not open in a new window.
Tabular Data Viewer
  • Fixed an issue where opening a Tabular Data Viewer permalink in a browser window without an active Flywheel session displayed a blank page. Flywheel now redirects the user to the sign-in page.
BrainBrowser
  • Routine updates to viewer dependencies. BrainBrowser is now published on the flywheel-cdn.io domain. See the BrainBrowser documentation for updated installation instructions.
Montage Viewer
Form Builder and Viewer

Data Views

  • Fixed an issue where a Data View filter that used the regular expression match operator (=~) on a field that holds multiple values, such as file tags or classification entries, returned no results even when a value matched. The filter now compares the pattern against each value in the list.
  • The remove (minus) button now stays visible on the last remaining filter row in the Include and Exclude sections of Data Views, Smart Copy, and Bulk Export. When only one row remains, the button clears the field, operator, values, and any validation errors on that row.
  • Fixed an issue where the Operator menu of an existing Subject Machine Learning (ML) Set filter in a saved Data View did not include the is not option.