Roles
The Roles app lets administrators define exactly what each type of user can create, view, edit, and delete across every app in the platform — so access is intentional, consistent, and easy to manage at scale.
🔐 Who Can Access Roles
| Your Role | What You See in the Roles List |
|---|---|
| Super Administrator | All roles in the account |
| Administrator | All roles except the Super Administrator role |
| All other roles | No access to the Roles app |
📋 Roles List
The list shows all roles defined in your account. Each row represents a permission profile that can be assigned to one or more users.
Roles List — Columns
| Column | Description |
|---|---|
| Name | The unique name of the role (e.g., administrator, distributor, customer, orgadministrator, reader). The same role name can appear more than once if separate instances were created for different organizations. |
| Description | A plain-language summary of the role's purpose |
| Create Date | Date and time the role was first created |
| Action — 🗑 Delete | Disables the role — see the Delete section below for important warnings |
Table Controls
| Control | Description |
|---|---|
| 🔍 Search | Search roles by name or description |
| ⚡ Filter | Apply filters to narrow the list |
| ⊞ / ☰ / ⊡ view icons | Switch between card, list, and density display options |
| + Add | Opens the Create Role form |
| Request Data | Export a data extract of the roles list |
⚠️ Non-obvious: Multiple rows with the same role name (e.g., several rows all named "orgadministrator") are separate role records — each created for a different organization or user context. They may have different permission configurations despite sharing a name. Check the Description column to distinguish them.
🔍 Role Detail View
Click any role row in the list to open its detail view. The breadcrumb shows: Roles / [role name]
The detail page shows the role's name and description as a header, followed by a full permission matrix for every app installed in your account.
Permission Matrix (Read-Only View)
| Column | Description |
|---|---|
| App | The name of the app this permission row applies to |
| Create | ✅ Checked = users with this role can create new records in this app. ☐ Empty = cannot create |
| Read | ✅ Checked = users with this role can view records in this app. ☐ Empty = cannot view |
| Update | ✅ Checked = users with this role can edit records in this app. ☐ Empty = cannot edit |
| Delete | ✅ Checked = users with this role can delete records in this app. ☐ Empty = cannot delete |
⚠️ Non-obvious: The detail view only shows apps that are both configured in the role and installed for you (the logged-in administrator). If an app appears missing from the matrix, it may simply not be installed for your account — not necessarily missing from the role.
A ✏️ pencil icon in the top-right corner opens the Update Role form.
➕ Create Role Form
Click the + icon in the Roles List toolbar to open the Create Role form.
Section 1 — Role Details
| Field | Description |
|---|---|
| Role Name | Must be unique across the entire account. Two roles cannot share the same name. |
| Description | A plain-language explanation of this role's purpose and the type of user it is intended for |
Section 2 — Access Details
A scrollable list of every app installed in your account. Each app is shown with its icon and name, followed by individual checkboxes for each permission type.
Standard permissions (available for most apps):
| Permission | What It Controls |
|---|---|
| Create | Users with this role can add new records in this app |
| Read | Users with this role can view records in this app |
| Update | Users with this role can edit existing records in this app |
| Delete | Users with this role can delete records in this app |
Extended permissions (available for specific apps):
Some apps include additional sub-sections beyond the standard four:
| App | Sub-Section | Additional Permission | What It Controls |
|---|---|---|---|
| Manuals | DynamicManuals | autoSelect | Controls whether manuals are automatically associated with assets for users of this role |
| Manuals | ManualsTrash | restore | Allows users to recover deleted manuals from the trash |
| Walkthrough | WalkthroughTemplate | Standard CRUD | Controls access to walkthrough template management separately from walkthrough execution |
| Audits | AuditTemplate | Standard CRUD | Controls access to audit template management separately from audit execution |
Form Buttons
| Button | Description |
|---|---|
| ✕ CANCEL | Discards all entries and returns to the Roles List |
| 💾 SAVE | Creates the role and applies it immediately to any users already assigned to it |
✏️ Update Role Form
Click the ✏️ pencil icon on any role's detail view to open the Update Role form. The breadcrumb shows: Roles / [role name] / Update
The form has the same two sections as Create Role.
Section 1 — Role Details
| Field | Behavior on Update |
|---|---|
| Role Name | Can be changed, but must remain unique across the account |
| Description | Update to reflect any changes to the role's purpose |
Section 2 — Access Details
The same app permission grid as on Create. Check or uncheck any permission for any app.
📌 Important: Changes saved here apply immediately to every user who holds this role — not just the user whose record you may have been viewing when you navigated here.
⚠️ Non-obvious: If you update a role's permissions, users currently logged in with that role will not see the change until they log out and log back in. Updated permissions only take effect at the start of a new session. If you need the change to apply immediately, ask all affected users to log out and back in.
🗑️ Delete Role
Click the 🗑 icon on any role row in the Roles List to delete it. The role is disabled in the system.
⚠️ Non-obvious: Deleting a role does not immediately remove access for users currently logged in with that role — the role is marked as disabled but active sessions may continue until those users log out. Any user assigned a deleted role should be reassigned to a valid role as soon as possible, otherwise they may lose access to the platform entirely on their next login.
🔄 Workflows
Workflow 1 — Create a New Role
- Open Settings (⚙️ gear icon, top-right) and click Roles.
- Click the + icon in the Roles List toolbar to open the Create Role form.
- Enter a unique Role Name and a clear Description that describes the intended user type.
- Scroll through the Access Details section. For each app, check the permissions this role should have. Leave boxes unchecked to deny that action.
- Pay special attention to sub-sections like DynamicManuals, ManualsTrash, WalkthroughTemplate, and AuditTemplate if those apps are in use.
- Click SAVE.
✅ Result: The new role appears in the Roles List and is immediately available to assign to users via the Users app.
Workflow 2 — Update Permissions for an Existing Role
- Open Settings → Roles and find the role you want to update.
- Click the role row to open the detail view and confirm you have the right role (check name and description).
- Click the ✏️ pencil icon to open the Update Role form.
- Check or uncheck permissions in the Access Details section as needed.
- Click SAVE.
- Notify all users with this role that they must log out and log back in for the changes to take effect.
✅ Result: The role's permissions are updated. All current and future users assigned this role will have the new permissions active on their next login.
Workflow 3 — Review What a Role Allows Before Assigning It
- Open Settings → Roles and locate the role you are considering.
- Click the role row to open the detail view.
- Scan the permission matrix — note which apps have Read-only access, which have full Create/Read/Update/Delete, and which have no access at all.
- Use the pagination at the bottom to review all app rows.
- If the role is not quite right, either find a closer match or open Update Role to adjust it.
✅ Result: You have a clear picture of exactly what a user with this role can and cannot do before you assign it.
Workflow 4 — Audit Which Roles Have Access to a Sensitive App
- Open Settings → Roles and note the list of all role names.
- Click each role row in turn and check the permission matrix for the app in question (e.g., Audits, DocGPT, Cases).
- Note which roles have Create, Update, or Delete checked for that app — these are the roles with write access.
- Cross-reference with the Users app to see which users hold those roles.
✅ Result: You have a complete access map for a sensitive app, confirming who can create or delete records within it.
✅ Best Practices
- Name roles by user type, not by person. Role names like "customer", "distributor", or "orgadministrator" scale to many users. Names tied to individuals create maintenance problems when people change roles or leave.
- Change permissions on a role only when you intend to affect all users with that role. Every user assigned the role is affected on their next login. If you only need to change one user's permissions, assign them a different role or create a new dedicated role instead.
- Always log out and log back in after a role change. Permission updates do not apply to active sessions — this applies to both the affected users and any admin testing the change.
- Keep role descriptions specific and current. Outdated descriptions cause confusion during user setup. Update the description whenever permissions are meaningfully changed.
- Use the read-only detail view to audit roles regularly. Role sprawl is a real risk in large accounts. Periodically review the list and disable roles that are no longer in use.
- Be careful with Delete permissions on Manuals and ManualsTrash. If a role has Delete on Manuals but no restore access on ManualsTrash, deleted manuals cannot be recovered by users of that role.
💡 Tips & Shortcuts
| Tip | How |
|---|---|
| Find a role quickly | Use the 🔍 search bar and type the role name or part of the description |
| Check if a role name is already in use | Search the list first — the Create form will reject duplicate names on save |
| See all permissions for a role | Open the role detail view and use pagination to scroll through all app rows |
| Distinguish between multiple rows with the same name | Check the Description column — each instance typically includes the organization name it was created for |
| Apply a permission change to only one user | Assign that user a different role rather than editing the shared role |
| Confirm a role change is active for a user | Ask the user to log out and back in, then test the specific action in the affected app |