Skip to content

Roles

Flywheel supports custom roles that provide fine-grained control over what actions users can take within a project. Custom roles go beyond the three built-in access levels (admin, read-write, read-only) by letting you define exactly which operations a user may perform.

How roles differ from access levels

Built-in access levels apply at the group level and grant broad permissions. Custom roles are defined site-wide but must be explicitly added to a group before they can be assigned to users in that group's projects.

A user assigned a role on a project must have that role registered on the group that owns the project. The role governs only the actions listed in its definition.

Available actions

Every custom role requires a minimum set of read-only actions. Additional actions expand what the user can do.

Action Description
containers_view_metadata View container metadata
containers_create_hierarchy Create container hierarchy
containers_modify_metadata Modify container metadata
containers_delete_hierarchy Delete container hierarchy
containers_delete_project Delete project
copy_by_reference Copy containers by reference
analyses_view_metadata View analysis metadata
analyses_create_sdk Create ad hoc analysis
analyses_create_job Create job-based analysis
analyses_modify_metadata Modify analysis metadata
analyses_delete Delete analysis
files_view_metadata View file metadata
files_view_contents View file contents
files_download Download file
files_create_bulk Create or upload file in bulk
files_create_single Create or upload single file
files_modify_metadata Modify file metadata
files_move Move files between containers
files_delete_non_device_data Delete non-device file data
files_delete_device_data Delete device file data
tags_view View tags
tags_manage Manage tags
notes_view View notes
notes_manage Manage notes
annotations_manage Manage annotations
annotations_view_others View other users' annotations
annotations_edit_others Edit other users' annotations
annotations_delete_others Delete other users' annotations
project_permissions_view View project permissions
project_permissions_manage Manage project permissions
project_sharing_manage Manage project sharing settings
gear_rules_view View project gear rules
gear_rules_manage Manage project gear rules
data_views_view View data views
data_views_manage Manage data views
session_templates_view View session templates
session_templates_manage Manage session templates
jobs_view View jobs
jobs_manage Run and cancel jobs
jobs_manage_others Manage other users' jobs
settings_view View project settings
settings_modify Modify project settings
reader_task_view View reader tasks
reader_task_admin Administer reader tasks
form_admin Administer forms
form_responses_manage Manage form responses
form_responses_view_others View other users' form responses
form_responses_edit_others Edit other users' form responses
imports_manage Manage data imports
exports_manage Manage data exports
jupyterlab_servers_read View JupyterLab servers
jupyterlab_servers_launch Launch JupyterLab servers
jupyterlab_servers_create Create JupyterLab servers
jupyterlab_servers_modify Modify JupyterLab servers
jupyterlab_servers_delete Delete JupyterLab servers
audit_trail_reports_manage Create and manage audit trail reports
audit_trail_reports_view View audit trail reports
tasks_view View tasks
tasks_create Create tasks
tasks_modify Modify tasks
tasks_assign Assign tasks to users
tasks_report_create Create task reports
tasks_report_delete Delete task reports
tasks_report_read Read task reports

The following actions are required in every custom role definition, as they provide the minimum read-only access:

Required actions for any custom role
REQUIRED_ACTIONS = [
    "containers_view_metadata",
    "files_view_metadata",
    "tags_view",
    "notes_view",
    "project_permissions_view",
    "data_views_view",
    "session_templates_view",
    "gear_rules_view",
    "jobs_view",
    "reader_task_view",
    "settings_view",
    "jupyterlab_servers_read",
    "tasks_view",
]

Listing roles

List all roles
all_roles = fw.get_all_roles()
for role in all_roles:
    print(role.id, role.label)
List roles registered on a group
group_roles = fw.get_all_group_roles(group_id)
for role in group_roles:
    print(role.id, role.label)

Getting a role by ID

Get a role by ID
role = fw.get_role(role_id)
print(role.label, role.actions)

Creating a custom role

Create a custom role with download access
action_list = REQUIRED_ACTIONS + ["files_download", "files_view_contents"]

new_role = fw.add_role(flywheel.RoleInput(label="Read and Download", actions=action_list))
role_id = new_role.id

Adding a role to a group

Before a role can be assigned to users on a project, it must be registered on the group that owns the project:

Register a role on a group
fw.add_role_to_group(group_id, flywheel.GroupRole(id=role_id))

Assigning a role to a user on a project

Assign a role to a user on a project
project.add_permission(flywheel.RolesRoleAssignment(user_email, [role_id]))

A user can hold multiple roles on a project. Pass all role IDs in the role_ids list.

Removing a role assignment from a user

Remove a user's permission from a project
project.delete_permission(user_email)

Removing a role from a group

Remove all project permissions that reference the role before removing it from the group:

Remove a role from a group
fw.remove_role_from_group(group_id, role_id)

Deleting a custom role

A role must be removed from all groups and project permission entries before it can be deleted:

Delete a custom role
fw.delete_role(role_id)