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
--8 < --"test_docs_admin_concepts.py:get_all_roles"
List roles registered on a group
--8 < --"test_docs_admin_concepts.py:get_all_group_roles"

Getting a role by ID

Get a role by ID
--8 < --"test_docs_admin_concepts.py:get_role"

Creating a custom role

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

--8 < --"test_docs_admin_concepts.py:add_role"

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
--8 < --"test_docs_admin_concepts.py:add_role_to_group"

Assigning a role to a user on a project

Assign a role to a user on a project
--8 < --"test_docs_admin_concepts.py:assign_role_to_project"

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
--8 < --"test_docs_admin_concepts.py:delete_project_permission"

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
--8 < --"test_docs_admin_concepts.py:remove_role_from_group"

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
--8 < --"test_docs_admin_concepts.py:delete_role"