Skip to content

Reader Tasks

Reader Tasks is a feature available with a Flywheel Clinical module.

A reader task is a unit of work that assigns specific imaging data to a reader (user) for review. Each task links to a container (session, acquisition, or file), a protocol that defines the review form, and an assignee who is responsible for completing it.

Task versions: Legacy vs Tasks Manager

Flywheel has two distinct reader task systems, Legacy and Tasks Manager. 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.

Task lifecycle

Current tasks move through the following states:

  1. To-do — created but not yet opened by the assignee
  2. In progress — the assignee has opened the task in the viewer and saved a draft
  3. Completed — the assignee has submitted the form

Tasks remain in "To-do" state until the assignee opens them in the viewer and saves a draft response.

Task fields

Field Description
id Unique task identifier
type Type of task: "reader"
status Current state: todo, in_progress, completed, or cancelled
protocol_id ID of the protocol defining the task's form
protocol_label Label of the protocol at task creation time
assignee The user or staffing pool assigned to this task
staffing_pool Staffing pool ID, if the task is pool-assigned
parent_details Dictionary of the task's parent's labels
parent_ref Reference to the container or file this task is attached to
parents Dictionary of the task's hierarchy by container IDs
priority blocker, high, medium, or low
batch_number Batch number of the task
item_number Item number of the task
task_id Task identifier including abbreviated type, batch, and item
description Optional free-text description (max 250 characters)
esignature Optional esignature
due_date Optional due date
transitions Dictionary of timestamps for state marker updates
tags Optional tags for filtering
created Creation timestamp
creator User who created the task
modified Last-modified timestamp

Note

A task has both id and task_id attributes. When referring to a specific task for SDK commands, the id is used, not task_id.

Create a Task Manager task

fw.create_reader_task(body) creates a single task on a container. Either a kwarg dict or a ReaderTaskCreate object are accepted as the body.

Create a reader task with a dict of kwargs
task = fw.create_reader_task(
    {
        "protocol_id": protocol_id,
        "parent_ref": {"id": session_id, "type": "session"},
        "assignee": {"id": user_id, "type": "user"},
        "priority": "medium",
        "description": "Please review this chest CT session.",
        "subcategory": "reader",
        "status": "todo",
        "due_date": None,
    }
)
Create a reader task with ReaderTaskCreate
from datetime import datetime
from flywheel.models.reader_task_create import ReaderTaskCreate
from flywheel.models.task_parent_ref_input import TaskParentRefInput

task = fw.create_reader_task(
    ReaderTaskCreate(
        protocol_id=protocol_id,
        parent_ref=TaskParentRefInput(type="session", id=session_id),
        staffing_pool=pool_id,
        subcategory="reader",
        status="todo",
        due_date=datetime(2026, 10, 10),
        priority="high",
    )
)

Create Task Manager tasks in bulk

fw.batch_create_reader_task(body) creates tasks across multiple containers in a single call. Either a kwarg dict or a ReaderBatchCreate object are accepted as the body. Tasks are created for every container_type specified in filters within the specified project; include_tags and exclude_tags specified in filters can include/exclude container_type containers by tag.

Batch create tasks with a dict
tasks = fw.batch_create_reader_task(
    {
        "protocol_id": protocol_id,
        "project_id": project_id,
        "assignee": {"id": user_id, "type": "user"},
        "filters": {
            "container_type": "session",
        },
        "subcategory": "reader",
    }
)
Batch create tasks with ReaderBatchCreate
from flywheel.models.assignee import Assignee
from flywheel.models.batch_create_filters import BatchCreateFilters
from flywheel.models.reader_batch_create import ReaderBatchCreate

tasks = fw.batch_create_reader_task(
    ReaderBatchCreate(
        protocol_id=protocol_id,
        project_id=project_id,
        assignee=Assignee(
            id="user@example.com",
            type="user"
        ),
        subcategory="reader",
        filters=BatchCreateFilters(
            container_type="session",
            include_tags=["ct-read"],
        )
    )
)

List Task Manager tasks

fw.find_all_api_tasks_reader_get() returns a paginated list of reader tasks. Use filter and sort to narrow results.

List all tasks
result = fw.find_all_api_tasks_reader_get(limit=50)

for task in result.results:
    print(f"{task.id}: {task.status} — {task.protocol_label}")
List incomplete tasks for a specific user
result = fw.find_all_api_tasks_reader_get(filter=f"assignee.id={user_id},status!=completed")

Get a Task Manager task by ID

Get a reader task by ID
task = fw.get_reader_task(id_)
print(task.status)
print(task.protocol_id)

Assign a Task Manager task

Use fw.assign_reader_task() to assign or reassign a task to a user or staffing pool.

Assign a task to a specific user
task = fw.assign_reader_task(id_, {"assignee": {"id": user_id, "type": "user"}})
Assign a task to a staffing pool
task = fw.assign_reader_task(id_, {"staffing_pool": pool_id})

Modify a Task Manager task

fw.modify_reader_task() updates mutable task fields such as description, priority, due_date, and tags.

Update task priority and due date
from datetime import datetime

updated = fw.modify_reader_task(id_, {"priority": "blocker", "due_date": datetime(2025, 6, 30)})
Cancel a task
fw.modify_reader_task(cancel_id, {"status": "cancelled"})

Complete a Task Manager task

fw.complete_reader_task() marks a task as complete. The task's form response must be submitted before or simultaneously with completion.

Mark a task as complete
fw.complete_reader_task(task_id)

Find which containers have Task Manager tasks

fw.get_task_parent_container_ids() returns the subset of a provided list of container IDs that have at least one task associated with them.

Check which sessions have tasks
session_ids_with_tasks = fw.get_task_parent_container_ids(ids=session_id_1, container_type="session")