Skip to content

Import and Export Rule Sets

Rule sets are centrally managed, versioned configurations that define how Bulk Import and Bulk Export jobs handle file filtering, mapping, and placement. Rule sets allow organizations to standardize data handling rules and apply them consistently across jobs.

Unlike local rule files, which are YAML files stored on your machine, managed rule sets are stored in Flywheel and can be shared, versioned, and governed by administrators.

Added in version 21.5.0

Import and export rule sets are available starting in Flywheel Core version 21.5.0.

Key Concepts

  • Centrally managed — Rule sets are stored in Flywheel, not on local machines. Authorized users can create, edit, and manage them from the web application or the New CLI (flyw).
  • Scoped to site, group, or project — Rule sets can be defined at the site level (available everywhere), the group level (available to all projects in a group), or the project level (available only in that project).
  • Versioned — Each edit to a rule set creates a new version. Every job records which rule set and version it used, providing a full audit trail.
  • Default rule set — One rule set per scope (site, group, or project) can be designated as the default. The default rule set is applied automatically when a user starts a job without selecting a specific rule set.
  • Built-in rule sets — Flywheel includes system-provided rule sets for standard, DICOM-only, and BIDS data organization. These cannot be edited but can be selected when running jobs.
  • Archive instead of delete — Once a rule set has been used in a job, it can only be archived, not deleted. This preserves traceability for audit purposes.

Managing Rule Sets in the Web Application

Viewing Rule Sets

  1. Navigate to the scope where you want to view rule sets (site settings, group, or project).
  2. Open the Settings page.
  3. Select the Import Rule Sets or Export Rule Sets tab.

The rule set table displays all available rule sets for that scope, with active rule sets listed before archived ones. The table supports pagination for sites with many rule sets.

Creating a Rule Set

  1. Select Create Rule Set.
  2. Enter a unique name for the rule set. The name must be unique within the scope (site, group, or project).
  3. Define the rules using the YAML editor. The editor retains YAML comments, so you can annotate your rules for future reference.
  4. Select Save.

For the YAML rule syntax, see the sections on import rule structure and export rule structure.

Editing a Rule Set

  1. Open the rule set details by selecting the rule set name from the table.
  2. Make changes in the YAML editor.
  3. Select Save.

Each save creates a new version of the rule set. Previous versions are retained for audit purposes.

Duplicating a Rule Set

To create a new rule set based on an existing one:

  1. Open the rule set you want to duplicate.
  2. Select Duplicate.
  3. Enter a new unique name.
  4. Modify the rules as needed.
  5. Select Save.

Setting a Default Rule Set

  1. Open the rule set you want to make the default.
  2. Select Set as Default.

When a user starts a Bulk Import or Bulk Export job without selecting a specific rule set, the default rule set for the applicable scope is used automatically.

Archiving and Restoring Rule Sets

To archive a rule set that is no longer needed:

  1. Open the rule set.
  2. Select Archive.

Archived rule sets are hidden from the active list but remain accessible for audit purposes. To restore an archived rule set, open it from the archived list and select Restore.

Note

Rule sets that have been used in at least one job cannot be deleted. They can only be archived to preserve the audit trail.

Permissions

The actions available in the rule set interface depend on your role:

  • Viewing rule sets requires read access to the scope.
  • Creating, editing, and archiving rule sets requires administrative access to the scope.

Managing Rule Sets with the New CLI (flyw)

The New CLI provides commands for managing rule sets from the command line. All commands are available under flyw import rule-set and flyw export rule-set.

Listing Rule Sets

1
2
3
4
5
# List import rule sets for a project
flyw import rule-set list --project "fw://group/project"

# List export rule sets for a group
flyw export rule-set list --group "group-label"

Viewing a Rule Set

1
2
3
4
5
# View a specific import rule set by ID
flyw import rule-set get <rule-set-id>

# View a specific export rule set by ID
flyw export rule-set get <rule-set-id>

Creating a Rule Set

1
2
3
4
5
6
7
8
9
# Create from a YAML file
flyw import rule-set create --project "fw://group/project" \
    --name "My Import Rules" \
    --file /path/to/rules.yaml

# Open the default editor to write rules interactively
flyw import rule-set create --project "fw://group/project" \
    --name "My Import Rules" \
    --edit

The --edit flag opens your default text editor (set by the EDITOR environment variable) so you can write or paste rule definitions interactively.

Updating a Rule Set

1
2
3
4
5
# Update from a YAML file
flyw import rule-set update <rule-set-id> --file /path/to/updated-rules.yaml

# Open the editor with current rules for modification
flyw export rule-set update <rule-set-id> --edit

Archiving and Restoring

1
2
3
4
5
# Archive a rule set
flyw import rule-set archive <rule-set-id>

# Restore an archived rule set
flyw import rule-set restore <rule-set-id>

Validation and Error Handling

The CLI validates rule set content and provides clear error messages when:

  • A rule set file contains invalid YAML or the wrong rule type (for example, import rules in an export rule set).
  • A rule set name is already in use within the same scope.
  • An archived rule set is specified when starting a job.
  • A rule set name or ID cannot be found.

Using a Rule Set When Running a Job

In the Web Application

When starting a Bulk Import or Bulk Export job from the web application, a rule set selection step is included in the job configuration flow. You can select from available rule sets or proceed with the default.

For step-by-step instructions, see:

In the New CLI (flyw)

Specify a rule set when starting a job using the --rule-set flag:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Use a managed rule set by ID
flyw import run --project "fw://group/project" --storage <storage> \
    --rule-set <rule-set-id>

# Use a local YAML file instead of a managed rule set
flyw import run --project "fw://group/project" --storage <storage> \
    --rule-set /path/to/rules.yaml

# Same options for export
flyw export run --project "fw://group/project" --storage <storage> \
    --rule-set <rule-set-id>

The --rule-set flag accepts either:

  • A rule set ID referencing a managed rule set stored in Flywheel, or
  • A file path to a local YAML rule file.

If no --rule-set flag is provided, the default rule set for the project (or group, or site) is used. If no default rule set is configured, the system default behavior applies.

Rule Sets vs. Local Rule Files

Feature Managed Rule Sets Local Rule Files
Storage Flywheel server Local file system
Sharing Available to all authorized users in the scope Must be shared manually
Versioning Automatic, with audit trail Manual (for example, via git)
Default assignment Can be set as the default for a scope Not applicable
Governance Archived instead of deleted after use No governance
Syntax Same YAML format Same YAML format

Both managed rule sets and local rule files use the same YAML syntax for defining rules. For rule syntax documentation, see Rule Files.

See Also