Permissions

Table of contents

  1. Introduction
  2. Permission levels overview
  3. Permission levels
    1. Group permissions
    2. Project permissions
    3. Personal attribute permissions
    4. Protocol permissions
    5. Shared catalog and taxonomies
  4. Permission inheritance
    1. Projects
    2. Personal attributes
  5. Planned entries
  6. Public sharing
    1. Public sharing of projects
    2. Public sharing of personal attributes
  7. Permission management

Introduction

BrainSTEM applies permissions at the level of individual records. Every record derives its access from a parent: the records of a study from their project, a lab’s resources from the groups they are shared with, and shared catalog entries from an approval workflow. This keeps collaboration flexible while every record stays under the control of the people responsible for it.

The diagram shows where every model’s roles come from: each model stands under the record it inherits its permissions from. Expand opens it with its notes, search, layouts, layers and detail panel.

Drag to pan, Ctrl + scroll to zoom and hover a model to see its connections; Reset view returns to this view. Expand opens the full diagram, where you can click a model to read about it and use its search, layouts, layers and detail panel.

Permission levels overview

Permission levelsGroupsProjectsPersonal attributes
Permission scope3 levels, users only4 levels for users and groups4 levels for users and groups
MembersInherit the permissions given to the groupRead access to the project, its subjects, specimen sets, sessions and modulesRead access to the attribute and what it contains (equipment, stock)
Contributors-Create, edit and delete records of the projectCreate, edit and delete contained records
ManagersAdd and remove membersAdd and remove members and groupsAdd and remove members and groups
OwnersManage group details
Add and remove managers
Edit project details, make the project public, delete it
Add and remove managers
Edit attribute details, make it public
Add and remove managers

Permission levels

Group permissions

Groups are the foundation of the permission system, with three levels:

Permission levelCapabilities
OwnerManage group details and settings, add and remove managers, associate the group with a laboratory, rename the group
ManagerAdd and remove members, create invitations, accept or decline membership requests
MemberAccess group resources, inherit the project permissions assigned to the group, leave the group

Users can ask to join a group; group managers accept or decline the request. An invitation grants one of these roles. Managers can also invite users who do not have a BrainSTEM account yet by email; the invitation is applied when the account is created.

Project permissions

Projects have four levels that can be assigned to users and to groups:

Permission levelCapabilities
OwnerEdit the project’s own fields, make it public, delete it, add and remove managers; everything a Manager can do
ManagerAdd and remove members and groups, send invitations; everything a Contributor can do
ContributorCreate, edit and delete the subjects, specimen sets, sessions and modules of the project; everything a Member can do
MemberRead the project and all its records

When a level is given to a group, every member of the group holds it. A user’s effective level is the highest of their own and their groups’ levels.

Creating or editing an entry needs Contributor on at least one project involved; you can only attach entries to projects where you are at least a Contributor. Links that require two records to share a project (a session and its subjects, a specimen set taken from a subject, a cohort and its subjects) are guarded on both sides: a project cannot be removed from a record while such a link depends on it.

Personal attribute permissions

Setups, inventories, behavioral assays, data storage and licenses carry the same four levels, assigned to users and groups. Group members inherit the level given to their group. Equipment inherits from its setup and consumable stock from its inventory.

Protocol permissions

Protocols, like the other personal attributes, have Member, Contributor, Manager and Owner roles of their own. The creator is an Owner and the groups selected at creation receive Contributor access. Protocol permissions are not inherited from the projects or entries that reference the protocol.

Shared catalog and taxonomies

Species, strains, anatomical regions, behavioral paradigms, setup types, regulatory authorities, consumables, hardware devices, suppliers, journals and publications are shared by everyone. Any user can propose a new entry or a change; the proposal becomes an approval request that an admin team reviews (accept, merge into an existing entry, ask for changes, reject). Until it is accepted, the pending entry is visible to its submitter only. Anatomical regions and atlases are loaded by the system and cannot be edited.

Permission inheritance

Roles are given to users and to groups on the record at the top of each tree; every record below it inherits them.

Projects

Users and groups
└── Project  (Member, Contributor, Manager or Owner)
    ├── Subjects
    │   ├── Procedures
    │   │   ├── Material usages and stages
    │   │   └── Procedure logs
    │   ├── Procedure episodes
    │   ├── Subject logs
    │   └── Experimental interfaces (subject-based)
    │       └── Material usages
    ├── Specimen sets
    │   ├── Specimens
    │   ├── Specimen procedures
    │   │   └── Material usages and stages
    │   ├── Specimen logs
    │   └── Experimental interfaces (specimen-based)
    ├── Sessions
    │   ├── Behaviors
    │   ├── Data acquisition
    │   ├── Manipulations
    │   └── Epochs
    ├── Collections
    ├── Cohorts
    └── Breedings
ParentInheriting records
ProjectSubjects, specimen sets, sessions, collections, cohorts, breedings
SubjectProcedures (and their material usages, stages and logs), procedure episodes, subject logs, experimental interfaces of the subject
Specimen setSpecimens, specimen procedures (and their material usages and stages), specimen logs, experimental interfaces of the set
SessionBehaviors, data acquisition, manipulations, epochs

An entry linked to several projects is readable by everyone with Member on any one of them. Adding a subject or session to a second project shares it, and everything that inherits from it, with that project’s members.

Personal attributes

Users and groups
├── Setup  (Member, Contributor, Manager or Owner)
│   └── Equipment
├── Inventory  (Member, Contributor, Manager or Owner)
│   └── Consumable stock
├── Data storage  (Member, Contributor, Manager or Owner)
├── Behavioral assay  (Member, Contributor, Manager or Owner)
├── License  (Member, Contributor, Manager or Owner)
└── Protocol  (its own roles, not inherited from projects)
ParentInheriting records
SetupEquipment
InventoryConsumable stock

Data storage, behavioral assays, licenses and protocols have no inheriting records. Each personal attribute is owned by the user who created it and is shared by giving roles to other users and to groups.

Templates (procedure, procedure episode, specimen procedure, interface, data acquisition, manipulation and material usage templates) are owned by the user who created them and can be shared with projects; members of those projects can read and apply them.

Planned entries

Procedures, specimen procedures, sessions and breedings carry a status of planned, performed or cancelled. Subjects, specimen sets, specimens and procedure episodes have planned states of their own (see Planning). Planned entries are shown to users with a “Planned” badge and are kept out of counts, public pages and API listings unless asked for explicitly. Permissions are the same as for performed entries.

Public sharing

Public sharing of projects

Making a project public publishes, at once and without an account, everything that inherits from it, including templates shared with the project and logs; see What becomes public. An entry in several projects is public as soon as one of them is public.

Only project owners can make a project public. Public access is read-only; members keep their edit rights. Planned entries stay private until they are marked performed.

Public sharing of personal attributes

  • Each personal attribute (setup, inventory, behavioral assay, license, protocol) has its own public setting, changed by its owners. A data storage has none: it is public when at least one of its data protocols is marked public.
  • Make the attributes public that readers of a public project should be able to open; otherwise the public record shows the link but not the attribute.

Permission management

  • Projects and personal attributes: the entry’s Manage button opens the Manage permissions page, where Managers and Owners invite users and groups, change levels and remove access. Public visibility is set on the entry’s form (Project visibility, Setup visibility and so on). See Sharing and memberships.
  • Groups: the group’s page: members, roles, join requests and invitations. See Managing groups.
  • API tokens act with the permissions of their owner; see API authentication.
  • Institutional security policy: your institution can require two-factor sign-in and set session lifetimes for every account of its email domain; see Two-factor authentication.