The Flywheel template file lets you define rules for where the Flywheel CLI imports your data. Additionally, the template can parse folder names or file names to create labels and metadata in Flywheel, which allows you to leverage your existing naming scheme.
This option is best for data that is a mix of file formats (for example DICOM images, spreadsheets, and word documents). See our importing overview article for more information on how to choose an import method.
This article explains how to create a template to upload your data to Flywheel as well as a reference for the template options.
Flywheel has two CLI commands that allow you to use a template: the import template or the ingest template command. Both commands get images into Flywheel, but which command you use depends on which infrastructure version you are using.
-
Follow the import template steps if your Flywheel site is using V2
-
Follow the ingest template steps if your Flywheel site is using V3
To find your Flywheel software version as well as if you are using V2 or V3 infrastructure:
-
Sign in to Flywheel.
-
In the top right corner, select the help menu. This will tell you your Flywheel version as well as the infrastructure version (v2 or v3). For example, this site is using Flywheel version 12.0.1 with the V3 infrastructure.
Follow the steps below if you are uploading data to a V2 Flywheel site. If you are on a V3 site, follow the Ingest template steps.
What is YAML?
YAML, which stands for YAML Ain't Markup Language, is a data serialization language. The Rollout Blog has a good explanation of the basic structure of a YAML file.
-
Open a text editor such as Sublime, TextEdit, Notepad, etc.
-
Copy and paste the following outline in to the text editor:
--- # Below is a basic outline for the import template. # This example takes the folder names at each # level and creates a label for each Flywheel # container. - pattern: "{group}" - pattern: "{project}" - pattern: "{subject}" - pattern: "{session}" - pattern: "{acquisition}"
-
To convert to a YAML file, add the .yaml extension and save the file.
-
Update the lines as needed for your data. See the reference table below or the example use case to learn more about how you can customize this template.
You can verify if your YAML is valid by using the online tool YAMLlint.
For the template import to succeed, you must tell Flywheel what to do for each level of the Flywheel hierarchy. Use the YAML file or use one of the optional flags to set a label for the Group, Project, Subject, Session, Acquisition.
-
Open Terminal or Windows Command Prompt.
-
Note the location of the parent folder containing the files you are importing.
-
In Terminal or Windows Command Prompt, enter the following command:
fw import template [optional flags] [template file location] [Data location]
For example:
fw import template --verbose ~/Desktop/TemplateExampleFile.yaml ~/Desktop/flywheel/ImportData
-
Add any optional flags to the command to tell Flywheel how to import, organize, or de-identify your data.
-
Flywheel CLI displays the data it has found and notes where it will import the files. It also notes if the Flywheel CLI will create a new container or use an existing container for the files.
-
Review the hierarchy and scan summary to make sure it matches what you expect.
-
Enter yes to begin importing. The Flywheel CLI displays its import progress.
-
Once complete, sign in to Flywheel, and view your data.
To begin, let's start with the following directories. After evaluating the directories, we decide we want to put the data in the following Flywheel hierarchy.
-
Group: fwtest
-
Project: AmygdalaSructure
-
Subject: s4 and s11
-
Session: sess1 and sess2
-
Acquisition: DTI 2mm 30dir 2x b1000_0 and test

For this example, we only want to import the AmygdalaStructure project, but not the psychology project. To do this, use the --exclude-dirs optional flag. We will add this optional flag to the full command in the next step.
-
Copy and paste the example template in to a text editor.
-
Update the YAML template. For example:
--- # We want to use folder name for the Flywheel containers, so we can just # add the variables for group project - pattern: "{group}" - pattern: "{project}" # We want to ignore this level in the directory structure since we are # using the next line to pull out the subject container. - pattern: .* # For subject and session, we only want to use part of that folder name, # so we replace the part of the name we want to use with the variable # for subject and session - pattern: "amyg_s{subject}_amyg_{session}_pcolA" - pattern: "{acquisition}"
Now that we have a template file, we can run the import command with our optional flags. In this example we use the import template
command, but you could also use the ingest template
command:
-
Sign in to Terminal or Windows Command Prompt.
-
Enter the import template command:
fw import template --exclude-dirs psychology ~/Desktop/TemplateExampleFile.yaml ~/Documents/SampleData/Flywheel
-
This command produces the following hierarchy for import:
-
Review the hierarchy and scan summary to make sure it matches what you expect.
-
Enter yes to begin importing. The Flywheel CLI displays its import progress.
-
Once complete, sign in to Flywheel, and view your data.
Use the ingest template method if you are using V3 Infrastructure.
Step 1: Upgrade your CLI version
The steps below assume you are using version 12.3.0 or later. To see your current version:
-
Open Terminal or Windows Command Prompt.
-
Enter
fw version
Learn more about how to upgrade your CLI version.
The ingest template uses a config file. The config file combines what used to be multiple files (the template, de-id profiles, and config files) into a single file where you can set configurations for all aspects of importing data.
In this example we will cover the template portion of the config file, but see our article for how to add de-id profiles, metadata ,and logging info to a config file.
What is YAML?
YAML, which stands for YAML Ain't Markup Language, is a data serialization language. The Rollout Blog has a good explanation of the basic structure of a YAML file.
-
Open a text editor such as Sublime, TextEdit, Notepad, etc.
-
Copy and paste the following outline in to the text editor:
--- # Below is a basic outline for the import template. # This example takes the folder names at each # level and creates a label for each Flywheel # container. template: - pattern: "{group}" - pattern: "{project}" - pattern: "{subject}" - pattern: "{session}" - pattern: "{acquisition}"
-
To convert to a YAML file, add the .yaml extension and save the file.
-
Update the lines as needed for your data. See the reference table below to learn more about how you can customize this template.
You can verify if your YAML is valid by using the online tool YAMLlint.
- Open Terminal or Windows Command Prompt.
- Note the location of the parent folder containing your data.
- In Terminal or Windows Command Prompt, enter the following command:
fw ingest template [optional flags][template file location][parent folder of data to ingest]
For example:
fw ingest template ~/Desktop/flywheel/ImportData ~/Desktop/TemplateExampleFile.yaml
- (Optional) If you are uploading a large amount of data, add the
--cluster <cluster URL>
optional flag to your command. This is not required, but this flag uploads data faster because the CLI utilizes resources from your Flywheel site to upload your data instead of just using your computer's resources. The URL to your cluster ishttps://yourflywheelURL.com/ingest
. For example:https://university.flywheel.com/ingest
fw ingest template --cluster https://university.flywheel.com/ingest ~/Desktop/TemplateExampleFile.yaml ~/Desktop/flywheel/ImportData
See our ingest template reference guide for more information on the optional flags. -
Flywheel CLI displays the data it has found.
-
Review the hierarchy and scan summary to make sure it matches what you expect.
-
Enter yes to begin importing. The Flywheel CLI displays its import progress.
-
Once complete, sign in to Flywheel, and view your data.
Use select to import data that matches your conditional rules. For example, if you have multiple folders at the same level of your hierarchy but you only want to import the DICOM files, you can set two different conditions based on the folder names.
In the example below, The Exams folder contains the DICOMs we want to import (packfile_type takes the single DICOM files and groups them in to an acquisition). Next, we set the template to ignore all other folders.
- pattern: "{acquisition}"
- select:
- pattern: Exams
packfile_type: dicom
- pattern: .*
ignore: true
You cannot nest another select within select conditions. This means that if you have subfolders that require different import rules, you should create another template for that data.
The scan feature reads file names, folder names, or file header information to label and group images into the correct Acquisitions, Sessions, and Subjects in Flywheel. This is especially helpful if you have a mix of filetypes in the same folder. Scan finds all files of the designated filetype.
In the example below, we only want to import the DICOMs images from the directory. See the
- pattern: "{project}"
- pattern: "{subject}"
- pattern: "{session}"
- select:
- pattern: .*
scan: dicom
The template consists of YAML key:value pairs. Below is a description of the template's keys and values.
Key |
Description |
Example |
---|---|---|
pattern |
Use in combination with regex or variable values to use some or all of the file name for the container label in Flywheel. You can use this value to set the label for Flywheel Group and Projects. |
and - pattern: "Anxiety Study"
|
select |
Used to start an expression where you set parameters or logical operators to determine what data is imported. |
|
scan |
Scanners are import methods that are optimized for certain filetypes. The scanners can automatically determine metadata and where to place the data in the Flywheel hierarchy. Scan options are: dicom, parrec, and filename |
See below |
scan: dicom |
Uses the DICOM file standard to place images in containers and add metadata |
|
scan: parrec |
Uses the PAR REC file standard to places images in containers and add metadata |
|
scan:filename |
Allows you to designate part of a filename as an attribute in Flywheel |
|
packfile_type |
Groups related images in to an acquisition. This is useful when you have a folder of images. Possible packfile_type values are: dicom and zip. Use packfile_name to define a name for the file. If the packfile type is .zip the generated packfile name is the following: {container.label or container.id}.zip. If the packfile type is not 'zip', the format is the following: {container.label or container.id}.{packfile_type}.zip |
|
packfile_name |
Names the packfile |
|
ignore |
Does not import files that match the regex pattern. Values can be true/false |
|
Values |
Description |
Example |
---|---|---|
{group} |
Variable that uses the designated part of the filename or folder as the Flywheel group label. If used alone, the entire filename or folder name is used for the Flywheel group label |
|
{project} |
Variable that uses the designated part of the filename or folder name as the Flywheel project label. If used alone, the entire filename or folder name is used for the Flywheel project label |
|
{subject} |
Variable that uses the designated part of the filename or folder name as the Flywheel project label. If used alone, the entire filename or folder name is used for the Flywheel project label |
|
{session} |
Variable that uses the designated part of the filename or folder name as the Flywheel session label. If used alone, the entire filename or folder name is used for the Flywheel session label |
|
{acquisition} |
Variable that uses the designated part of the filename or folder name as the Flywheel acquisition label. If used alone, the entire filename or folder name is used for the Flywheel acquisition label |
|
Regular expressions (regex) |
You can use regex for pattern matching file or folder names you want to import. You can learn more about regex operators and test out your regex at regex101 |
|
Flywheel metadata |
Sets metadata for the Project, Subject, Session, or Acquisition containers. |
|