Skip to content

Protocols

Protocols are a part of Reader Tasks, which is a feature available with a Flywheel Clinical module.

A protocol is a reusable template that defines the form a reader completes when working on a reader task. Protocols specify the form schema (field types, validation rules, and conditional logic), optional electronic signature (e-signature) requirements, viewer configuration, and tags to apply automatically when a task is completed.

Every reader task references a specific published version of a protocol. The protocol determines what data the reader is asked to collect and how that data is validated.

Protocol versions: Legacy vs Tasks Manager

Flywheel has two distinct protocol systems, corresponding to the two reader task systems. They are not compatible with each other, and are accessed in different ways. If you are unsure which version your instance has, contact your Flywheel administrator or check your site settings with the SDK.

Check whether Legacy tasks are enabled
fw.get_config().features.get("reader_tasks")
Check whether Tasks Manager is enabled
fw.get_config().features.get("tasks_refactor")

Legacy tasks are not managed through SDK methods, but can be managed through Low-Level API Access or the fw-client Python package for making API calls.

Protocol states

Protocols move through three states:

  • Draft — newly created; editable until published. Use this state while building and testing the form schema.
  • Published — the protocol has been versioned and is available for use in tasks. Published protocols are immutable: they cannot be edited or reverted to draft.
  • Archived — the protocol is soft-disabled. Archived protocols cannot be selected for new tasks but remain accessible for reading existing task data.

Archiving a protocol does not delete it or affect tasks that already reference it. Deleting a protocol is permanent and irreversible.

Protocol fields

Field Description
id Unique identifier assigned by Flywheel
label Human-readable name (max 32 characters, must be unique)
notes Optional description or context (max 250 characters)
status Current state: draft, published, or archived
version Integer version number, assigned when published
form The form schema defining fields, defaults, and validation
protocol_config Viewer and task configuration settings
completion_tags Tags applied to the container when a task is completed
esignature_config Optional e-signature requirements
group_id The group that owns the protocol
created Creation timestamp
modified Last-modified timestamp

Create a protocol

fw.create_task_protocol(body) creates a new protocol in draft state. The label and group_id fields are required.

For more information on the options available when building a form, see the product documentation's Form Technical Reference.

Create a protocol in draft state
protocol = fw.create_task_protocol(
    {
        "label": "Chest CT Review",
        "group_id": group_id,
        "notes": "Standard review form for chest CT imaging studies",
        "protocol_config": {
            "adjudication": False,
            "longitudinal": False,
            "viewer_config": {},
        },
        "form": {
            "title": "Chest CT Review",
            "description": "Complete all fields for each chest CT session.",
            "defaults": {"impression": "", "finding": ""},
            "fields": [
                {
                    "key": "finding",
                    "type": "radio",
                    "label": "Finding",
                    "options": [
                        {"value": "normal", "label": "Normal"},
                        {"value": "abnormal", "label": "Abnormal"},
                    ],
                    "requiredWhenVisible": True,
                },
                {"key": "impression", "type": "text-area", "label": "Impression", "requiredWhenVisible": True},
            ],
        },
        "esignature_config": None,
        "completion_tags": [],
        "task_type": "reader",
    }
)

Publish a protocol

Protocols must be published before they can be assigned to tasks. Publishing a protocol locks it and assigns it a version number starting at v1.

Publish a protocol
protocol = fw.publish_task_protocol(protocol.id)
print(protocol.version)  # 1

List protocols

fw.find_task_protocols() returns a paginated list of all protocols. Use the filter, sort, limit, and skip parameters to narrow results.

List all protocols
result = fw.find_task_protocols()
for protocol in result.results:
    print(f"{protocol.id}: {protocol.label} ({protocol.status})")
List only active (non-archived) protocols
result = fw.find_task_protocols(filter="status!=archived")
for protocol in result.results:
    print(f"{protocol.label} v{protocol.version}")

Get a protocol by ID

Get a protocol by ID
protocol = fw.get_task_protocol(protocol_id)
print(protocol.label)
print(protocol.status)

Modify a protocol

Modifying a published protocol creates a new version of the protocol.

Update a draft protocol's label and notes
updated = fw.modify_task_protocol(protocol_id, {"label": "Chest CT Review v2", "notes": "Test note"})

Archive a protocol

Archiving soft-disables a protocol. It remains readable but cannot be selected for new tasks. Use archiving instead of deletion when you need to preserve the record for existing task data.

Archive a protocol
fw.archive_task_protocol(protocol_id)

Delete a protocol

Deleting a protocol is permanent. Only delete protocols that have no associated tasks, and only protocols in draft state can be deleted.

Delete a protocol
fw.delete_task_protocol(draft_protocol_id)