Access Management

CellEngine uses role-based access for sharing folders and experiments.

The standard roles available to all users are as follows:

Role	Description
Limited read-only	Can view experiment, but not save a copy or download files. Can view folder.
Read-only	Can view and save a copy of experiment and download files. If a user wants to modify the experiment, they will have to save their own copy first.
Basic read/write	Can modify experiment or folder, but not delete it or share it. This is the suggested role to provide to other users if you want them to have read/write access.
Full read/write	Can modify, delete and share experiment or folder. This is the default role assigned to you when you create a new experiment or folder.

(See Standard Role Definitions for more details.)

Users in a custom domain can also create and use custom roles comprised of approximately 50 different granular permissions. For example, you could create a custom role that only allows modifying gates and combine it with another role that allows viewing the experiment in order to separate access and ability to perform tasks.

Roles can be assigned to folders and experiments. Permissions are inherited, so if a user has “Basic read/write” on a folder, they will be able to view and modify all experiments and sub-folders in that folder.

Advanced: Permissions and Roles

Key Points

• Operations in CellEngine require specific permissions.
• Permissions can be combined into roles.
• CellEngine provides four standard roles, and domain administrators can create additional roles.
• Permissions inherit dynamically from folders.

Operations in CellEngine require users to have specific permissions for each experiment or folder. For example, a user must have the fcsfile.upload role for each experiment to which they are allowed to upload an FCS file. There are about 50 different permissions currently.

Permissions can be combined into roles, which allow for easy reuse of sets of permissions between experiments. CellEngine provides four standard roles, shown in the tables above and below. Domain administrators can create additional roles.

Permissions and roles can be assigned to experiments or folders. Experiments inherit permissions from folders in which they reside. For example, if a user has the experiment.read permission assigned to a folder, they will be able to view all experiments in that folder. A user’s effective set of permissions are aggregated across the experiment and all of its containing folders. For example, if a user has fcsfile.delete on the experiment and fcsfile.upload on the folder containing the experiment, they can perform both of those operations on the experiment. This inheritance is dynamic, meaning that if you have an existing experiment in a folder and grant a user a new role on the folder, the user effectively gains that role on the experiment also. Likewise, if you later remove that role from the folder, the user will effectively lose that role on the experiment.

When you create an experiment, you are automatically granted the full read/write role. (Being the primary researcher or creator of an experiment does not itself confer any permissions.) Because that role allows changing permissions, you may grant other users roles/permissions for that experiment. Note that you can also remove some or all of your own permissions.

Warning

CellEngine uses the “fcsfile.download” and “attachment.download” permissions to control if a user can download FCS files and attachments, respectively. Note, however, that a user can still download files when they have the “experiment.clone” permission and do one of the following:

• Save a copy of the experiment.
• Export populations (potentially including the Ungated population) to a new experiment.
• Run an algorithmic analysis such as UMAP.

Ensure that custom roles are created with this caveat considered.

Standard Role Definitions

Permission	Limited read-only	Read-only	Basic read/write	Full read/write
audittrail.comment			✔	✔
attachment.delete			✔	✔
attachment.download		✔	✔	✔
attachment.update			✔	✔
attachment.upload			✔	✔
compensation.create			✔	✔
compensation.delete			✔	✔
compensation.update			✔	✔
experiment.changePermissionExternal				✔
experiment.changePermissionInternal				✔
experiment.changePrimaryResearcher				✔
experiment.clone		✔	✔	✔
experiment.delete				✔
experiment.move				✔
experiment.read	✔	✔	✔	✔
experiment.saveRevision			✔	✔
experiment.signRevision			✔	✔
experiment.update			✔	✔
fcsfile.delete			✔	✔
fcsfile.download		✔	✔	✔
fcsfile.lockGates			✔	✔
fcsfile.unlockGates			✔	✔
fcsfile.update			✔	✔
fcsfile.upload			✔	✔
folder.changePermissionExternal				✔
folder.changePermissionInternal				✔
folder.create			✔	✔
folder.createExperiment			✔	✔
folder.createFolder			✔	✔
folder.delete				✔
folder.move				✔
folder.read	✔	✔	✔	✔
folder.removeExperiment				✔
folder.removeFolder				✔
folder.update			✔	✔
gate.create			✔	✔
gate.delete			✔	✔
gate.lock			✔	✔
gate.unlock			✔	✔
gate.update			✔	✔
illustration.create			✔	✔
illustration.delete			✔	✔
illustration.update			✔	✔
population.create			✔	✔
population.delete			✔	✔
population.update			✔	✔
scaleset.update			✔	✔

Requirements for Common Tasks

The table below lists which permissions are required for common actions available in the CellEngine Web interface. For permissions required by individual API methods, refer to the API reference.

When multiple permissions are shown in the right-hand column, all of those permissions are required unless otherwise indicated.

Note: experiment.read is effectively required for all actions within experiments in order to use the Web interface. Nonetheless, that permission is listed for specific actions where it’s required by the underlying API.

Task	Permissions
Algorithms
Run algorithm (e.g., UMAP, SOM)	experiment.read experiment.clone fcsfile.download
Attachments
Delete attachment	attachment.delete
Download attachment	experiment.read attachment.download
Rename attachment	attachment.update
Upload attachment	attachment.upload
Compensations
Create compensation matrix	compensation.create
Delete compensation matrix	compensation.delete
Import compensation from file	compensation.update or compensation.create
Update compensation matrix	compensation.update
Experiments
Change annotation column order and wrapping	experiment.read experiment.update
Change annotation sort order	experiment.read experiment.update
Change annotation validators	experiment.read experiment.update
Change comments, tags and custom fields	experiment.read experiment.update
Change experiment-wide compensation	experiment.read experiment.update
Change permission: Grant permission to user in same domain	experiment.read experiment.changePermissionInternal
Change permission: Grant permission to user outside of domain	experiment.read experiment.changePermissionExternal
Change permission: Revoke other user’s permission	experiment.read experiment.changePermissionInternal or experiment.changePermissionExternal
Change permission: Revoke your own permission	experiment.read
Change primary researcher	experiment.read experiment.update experiment.changePrimaryResearcher
Comment on audit trail	audittrail.comment
Compare experiments or revisions	experiment.read
Create a revision	experiment.read experiment.saveRevision
Download audit trail	experiment.read
Download GatingML	experiment.read
Download JSON	experiment.read
Import compensations	experiment.read1 compensation.create
Import Diva workspace	population.create gate.create illustration.create scaleset.update
Import illustrations	experiment.read1 illustration.create
Import populations	experiment.read1 population.create gate.create
Import scales	experiment.read1 scaleset.update
List and view experiments	experiment.read
Move experiment to folder	experiment.read experiment.move folder.createExperiment5 folder.removeExperiment6
Move experiment to trash (soft-delete)	experiment.read experiment.update experiment.delete
Remove experiment from trash (un-delete)	experiment.read experiment.update
Rename experiment	experiment.read experiment.update
Save a copy of experiment	experiment.read experiment.clone folder.createExperiment5
Set retention policy	experiment.read experiment.update
Sign a revision	experiment.read experiment.signRevision
FCS Files
Add and change FCS file annotations	fcsfile.update
Change “control” status	fcsfile.update
Change file’s per-file compensation	fcsfile.update
Concatenate FCS files	fcsfile.upload fcsfile.delete2
Delete FCS file	fcsfile.delete
Delete FCS file annotations	fcsfile.update, experiment.update
Download annotations	experiment.read
Download FCS file3	experiment.read fcsfile.download
Import FCS file	experiment.read1 experiment.clone1 fcsfile.upload
Lock gates for FCS file	fcsfile.update fcsfile.lockGates
Rename FCS file	fcsfile.update
Rename FCS file panel	fcsfile.update
Rename FCS file reagent	fcsfile.update
Unlock gates for FCS file	fcsfile.update fcsfile.unlockGates
Upload FCS file	fcsfile.upload
Folders
Change permission: Grant permission to user in same domain	folder.changePermissionInternal
Change permission: Grant permission to user outside of domain	folder.changePermissionExternal
Change permission: Revoke other user’s permission	folder.changePermissionInternal or folder.changePermissionExternal
Change permission: Revoke your own permission	folder.read
Create folder	folder.create4
List and view folders	folder.read
Move folder	folder.update folder.move folder.createFolder5 folder.removeFolder6 experiment.move7
Move folder to trash (soft-delete)	folder.delete experiment.delete7
Remove folder from trash (un-delete)	folder.update experiment.update7
Rename folder	folder.update
Gates and Populations
Add or remove polygon point	gate.update
Apply tailoring	gate.update
Convert rectangle to polygon	gate.update
Copy/paste gate geometry	gate.update
Copy/paste populations	experiment.read gate.create population.create
Copy/paste populations, linked	population.create
Create “not”, “and” and “or” populations	population.create
Create combo populations	population.create
Create gate/population	gate.create population.create
Delete gate/population	gate.delete population.delete
Download populations	see download FCS file
Enable/disable quadrant skewing	gate.update
Export populations to new experiment	experiment.read experiment.clone fcsfile.download folder.createExperiment4
Lock gate	gate.update gate.lock
Modify gate	gate.update
Rename gate/population	gate.update population.update
Reset all gates/populations	gate.delete population.delete
Reset gate to global gate	gate.delete
Tailor a gate to a file	gate.create
Turn off tailoring	gate.update
Turn on tailoring	gate.delete
Unlock gate	gate.update gate.unlock
Illustrations
Create illustration	illustration.create
Delete illustration	illustration.delete
Download a PDF or PNG of illustration	experiment.read
Modify illustration	illustration.update
Save a copy of an illustration	experiment.read illustration.create
Scales
Modify scales	scaleset.update
Statistics
Download	experiment.read

¹Required on source experiment.
²Required if automatically deleting source files after concatenating.
³Includes downloading the original file or gated populations, in any format (FCS, TSV, CSV).
⁴Required on parent folder, if any.
⁵Required on new parent folder, if any.
⁶Required on old parent folder, if any.
⁷Required on all experiments in/below folder.