# 🔐 Roles and permissions
This chapter explains who can do what across Totum Video Library, Totum Forms, and Totum Assess — and how seats, organisation roles, and identity groups fit together. Your sign-in and organisations come from the separate Totum platform.
# 🧱 Three layers of access
Think of access as three layers that must line up:
flowchart TD SignIn["1. Sign-in\nTotum platform account"] Seat["2. Seat\nlicensed for this product in this org"] Role["3. Role\nwhat you can do inside the app"] Use["You can use the feature"] SignIn --> Seat --> Role --> Use
| Layer | What it controls | Plain language |
|---|---|---|
| 🔑 Sign-in | Can you open the app at all? | Your Totum platform account |
| 🎟️ Seat | Is this product licensed for you in this organisation? | Product seat assignment |
| 👤 Role | What are you allowed to do inside the product? | Org role, Assess role mapping, or invite role on a video |
If any layer is missing, something will look “broken” (empty pickers, redirects, missing buttons).
# 🎭 Assessor vs Reviewer vs Viewer
These words appear in more than one place and do not always mean the same thing.
flowchart LR VL["Video Library"] Assess["Totum Assess"] VL -->|"Assessor"| Formal["Formal scoring"] VL -->|"Reviewer"| Annotate["Annotate and discuss"] VL -->|"Viewer"| Watch["Watch and comment"] Assess -->|"Reviewer role"| Formal
| Term | Where you see it | Meaning |
|---|---|---|
| ✅ Assessor | Video Library → Assessors | Formal peer assessment via Totum Assess. Creates Assess cases. Scoring uses the framework form. |
| ✏️ Reviewer (informal) | Video Library invites | Can discuss and usually annotate a video. Not the formal Assess score sheet by itself. |
| 👀 Viewer | Video Library invites | Watch and comment only. |
| 👁️ Reviewer (Assess role) | Assess → Roles / Assignments | Person eligible or assigned to complete formal Assess scoring. |
A single colleague can be:
- An informal Reviewer on a video (draw and chat), and
- An Assessor / Assess Reviewer for the same video (formal scores).
When in doubt: Assessor / Assess Reviewer = formal framework scoring; VL Reviewer / Viewer = collaboration on the recording.
# 🎬 Video Library
| Capability | Owner | Informal Reviewer | Viewer | Assessor (formal) | Org admin |
|---|---|---|---|---|---|
| Browse own library | ✓ | ||||
| Open invited videos | ✓ | ✓ | ✓ | ✓* | |
| Discuss / chat | ✓ | ✓ | ✓ | ✓* | |
| Draw / annotate | ✓ | ✓ | |||
| Invite Reviewers / Viewers | ✓ | ||||
| Select Assessors & submit for assessment | ✓ | ||||
| Complete formal scores | ✓ (in Assess) | ||||
| Reviewer eligibility tools | ✓ |
*Assessors primarily work in Assess; they may also open the video from Video Library depending on how they were invited.
Prerequisites for formal assessors in the picker (typical programme):
- Correct organisation selected
- Assess Reviewer-type seat in that organisation
- Often a connection with the submitter (via Totum Social Connections)
- Assess Roles mapping for reviewer eligibility (programme-dependent, but commonly required for a clean setup)
# 📋 Forms
| Capability | Viewer | Editor | Org admin | Platform admin |
|---|---|---|---|---|
| View organisation frameworks | ✓ | ✓ | ✓ | ✓ |
| View public library | ✓ | ✓ | ✓ | ✓ |
| Create / edit frameworks | ✓ | ✓ | ✓ | |
| Publish versions | ✓ | ✓ | ✓ | |
| Export | ✓ | ✓ | ✓ | |
| Fork from library | ✓ | ✓ | ✓ | |
| Submit for public review | ✓ | ✓ | ||
| Import frameworks | ✓ | ✓ | ||
| Delete frameworks | ✓ | ✓ | ||
| Manage members & API keys | ✓ | ✓ | ||
| Review public submissions queue | ✓ | |||
| Publish with public visibility | ✓ |
Editors author content; organisation admins manage the org; platform admins curate the public library path.
# ✅ Assess
| Capability | Reviewer | Admin | Submitter (when results enabled) |
|---|---|---|---|
| My Assignments — accept / score / submit | ✓ | ||
| Admin dashboard & Cases | ✓ | ||
| Programme Settings | ✓ | ||
| Roles mapping | ✓ | ||
| Export | ✓ | ||
| Case registry | ✓ | ||
| Legacy Reviewers pool (if legacy on) | ✓ | ||
| My feedback | ✓ |
Admins are determined by Roles mappings (identity groups → Admin). Reviewers need the Reviewer mapping (and usually the right seat for VL pickers).
Display names in Settings (for example renaming “Surgeon” to “Trainee”) change labels only — not the permission model.
# 🏛️ Platform admin vs organisation admin
| Organisation admin | Platform admin | |
|---|---|---|
| Scope | One organisation (or the orgs they administer) | Broader / platform-level tools |
| Forms | Members, API keys, import, delete | Submissions queue; public publish; may span orgs |
| Assess | Not the same label — use Assess Admin via Roles | Assess Admin is programme admin via Roles mapping |
| How you get it | Forms org membership role; organisation admin signals from Totum groups | Platform Admin identity group (and related) / platform flags |
In everyday speech, “our Forms admin” usually means organisation admin. “Platform admin” is the person who approves public library submissions.
# ✅ Seats vs Roles (checklist)
Use this when someone cannot submit, cannot be picked as assessor, or cannot open an app:
flowchart TD A["Signed in with Totum account?"] B["Correct organisation selected?"] C["Product seat assigned?"] D["Correct role inside the app?"] E["For assessors: connection if required?"] OK["Ready to use the feature"] A -->|Yes| B B -->|Yes| C C -->|Yes| D D -->|Yes| E E -->|Yes| OK
- Signed in? Your Totum platform account works.
- Right organisation? Header switcher.
- Product seat? Video Library / Forms / Assess (and Assess Reviewer where relevant).
- Product role?
- Forms: viewer / editor / org admin
- Assess: Admin or Reviewer mapping on Roles
- Video Library extras for assessors? Connection between surgeon and peer (if required).