Skip to content

Gear Rules

Gear rules let you automate gear execution by triggering a gear whenever set conditions are met. Rules are configured per-project and run automatically without manual intervention.

How gear rules work

When a file is uploaded or updated (i.e. a file is uploaded to an acquisition container, or a tag is added to a file), Flywheel evaluates the project's gear rules against that change. If a rule's conditions match, the system queues a gear job automatically.

Note

Gears run by gear rules use a "System" API key instead of a "User" API key. The System API key's permissions are scoped to the project and role_id set for the gear rule. A gear that requires access to other projects cannot be run as a gear rule.

Listing rules for a project

List gear rules for a project
rules = fw.get_project_rules(project_id)
for rule in rules:
    print(rule.id, rule.gear_id)

Creating a rule

A rule is built from a gear ID, a configuration dictionary, and a list of conditions:

Create a gear rule
rule_input = {
    "gear_id": gear_id,
    "name": "DICOM metadata importer",
    "config": {
        "debug": False,
    },
    "any": [],
    "all": [
        {
            "type": "file.type",
            "value": "dicom",
            "regex": False,
        }
    ],
    "not": [],
    "auto_update": False,
    "priority": "high",
    "role_id": role_id,
    "disabled": False,
}

new_rule = fw.add_project_rule(project_id, rule_input)

Note

To create a rule that is enabled on creation, a role_id must be provided. The role_id refers to the role assigned to the gear rule (see Roles). A gear rule can be created without a role_id when disabled is True and modified later to enable the rule with modify_project_rule, or enabled via the UI.

Condition types

Conditions are organized into three lists:

  • all — every condition in this list must match
  • any — at least one condition in this list must match
  • not — no condition in this list may match

Each condition has a type, a value, and a regex boolean. Set regex to True to treat value as a regular expression pattern.

Condition type Matches on
file.type File type (e.g., "dicom", "nifti")
file.modality File modality (e.g., "MR", "CT")
file.classification Classification value on the file
file.name Filename pattern
file.tags File tag
file.parent_ref.type Type of parent container (e.g. "acquisition", "project")
container.has-type File type present in the parent container
container.has-classification File classification present in the parent container

Fixed inputs

Fixed inputs pre-wire a file as a named gear input. Every time the rule fires, the gear receives that file on the specified input slot — the file does not need to match any condition.

Each fixed input entry has four fields:

Field Description
type Type of the container holding the file
id ID of the container holding the file
input Gear input slot name the file is bound to
name Filename
Create a rule with a fixed input
fixed_input_rule = {
    "gear_id": gear_id,
    "name": "Run gear with fixed input",
    "config": {},
    "any": [],
    "all": [
        {
            "type": "file.type",
            "value": "dicom",
            "regex": False,
        }
    ],
    "not": [],
    "fixed_inputs": [
        {
            "type": "project",
            "id": project_id,
            "input": "config_file",
            "name": "my_config.json",
        }
    ],
    "auto_update": False,
    "role_id": role_id,
    "disabled": False,
}

fw.add_project_rule(project_id, fixed_input_rule)

Note

Triggered gear rules always use the latest version of the fixed input file at runtime.

Updating a rule

Update a gear rule
fw.modify_project_rule(
    project_id,
    rule_id,
    {"priority": "low"},
)

Auto-updating versions

When a gear rule is created, it uses the gear version corresponding with the unique gear ID provided at creation. When a new version of the gear is available, the gear rule can be manually updated, or the gear rule can be set to auto-update to the latest available gear version with the auto_update flag.

The auto_update flag cannot be utilized with a non-default gear configuration, to protect from possible configuration changes between gear versions.

Note

The auto_update flag can only be set to True when the gear is already set to the most recent release of the gear available on the Flywheel instance. Consider updating the gear version and setting auto_update=True at the same time.

Update the gear version to latest and enable auto_update
# First, get the Gear object. The `find_first` method should grab the latest version:
gear = fw.gears.find_first(f"gear.name={gear_name}")
# Then, modify both the `gear_id` and the `auto_update` flag.
fw.modify_project_rule(
    project_id,
    rule_id,
    {"gear_id": gear.id, "auto_update": True},
)

Deleting a rule

Delete a gear rule
fw.remove_project_rule(project_id, rule_id)

Copying rules across projects

To replicate gear rules from one project to another, read the rules from the source project and add each to the destination project:

Copy gear rules from one project to another
source_rules = fw.get_project_rules(source_project_id)

for rule in source_rules:
    rule_dict = rule.to_dict()
    for k in ["id", "revision", "created", "modified", "last_modified_by"]:
        rule_dict.pop(k, None)
    if "_not" in rule_dict:
        rule_dict["not"] = rule_dict["_not"]
        del rule_dict["_not"]

    fw.add_project_rule(destination_project_id, rule_dict)

Note

The gear_id in each rule must be valid on the destination site. If the destination site uses a different gear version, update the gear_id in the copied rule before adding it.