Roles

The Roles feature lets administrators define and manage access levels within Freedam. Permissions are grouped into roles, and roles can inherit from one another, so you can control what different users see and do across the platform.

Everything happens in one place: the Roles page is a matrix. Roles (and their parent‑child hierarchy) are listed as rows, and permissions are the columns, grouped by category. You read and edit permissions directly in the grid — there is no separate window to open for each role, so you can compare several roles side by side at a glance.

Page Overview

• Purpose: Centralize the management of permissions and role hierarchies in a single, comparable view.
• When to use it: When you need to create an access level, adjust permissions for one or more roles, or audit who can do what across every role at once.
• What you can do here:
  • See every role and its permissions together in the matrix.
  • Compare roles side by side and follow the hierarchy as indented rows.
  • Switch a permission between Inherit, Allow, and Deny directly in a cell.
  • Toggle between Explicit (what each role sets) and Effective (what each role can actually do after inheritance).
  • Create, rename, re‑parent, duplicate, and delete roles.

Page Layout

• Toolbar (top): Row filter (All roles / Custom roles / System roles), a Find a permission… search, an Explicit / Effective view toggle, Expand all / Collapse all, and a New role button.
• The matrix (main area):
  • Rows are roles. The first column is sticky (stays in view as you scroll sideways) and shows each role's name, indented to reflect its place in the hierarchy. System roles show a small lock icon.
  • Columns are permissions, grouped by category (Assets, Collections, Admin, …). Each category is a collapsible group.
  • Each editable cell is a three‑button toggle: Inherit, Allow, Deny.
• Save bar (bottom): Appears only when you have unsaved edits. It shows how many changes are pending across how many roles, with Discard and Save changes.
• Role dialog: A focused dialog opens for creating a new role or editing a role's details (name, code, parent, description). Permissions themselves are edited in the matrix, not in the dialog.

Main Features

The Permissions Matrix

• What it's for: Viewing and setting permissions for every role in one grid.
• Typical use: Granting "Editor" the ability to delete assets while confirming "Viewer" cannot — without opening either role in a separate window.
• Result: You see all roles and permissions together; changes are made in the cells and applied when you save.

Role Hierarchy and Inheritance

• What it's for: Organizing roles in a parent‑child structure so child roles inherit their parent's permissions.
• Typical use: A "Manager" role that inherits everything from "Staff" and adds administrative capabilities on top.
• Result: Child roles appear indented under their parent. A child only needs to declare what is different — everything else flows down from the parent chain.

Collapsible Categories and Coverage

• What it's for: Keeping a wide grid (there are dozens of permissions) readable.
• Typical use: Collapsing categories you are not working on so the grid stays compact.
• Result: Categories start collapsed, each showing a coverage count for every role (for example, 6/9 means six of the nine permissions in that category are effectively allowed). Click a category header to expand it into its individual permission columns.

Role Duplication

• What it's for: Creating a new role based on an existing one.
• Typical use: Copying a complex "Editor" role to create a "Junior Editor" with slightly fewer permissions.
• Result: A new role is created as a child of the original, inheriting its permissions, ready for you to adjust.

Detailed Feature Documentation

Filtering and finding permissions

• Purpose: Focus the matrix on the roles and permissions you care about.
• Where to find it: The toolbar at the top of the page.
• What you'll see: The grid updates to match your choices.

How to use it:

1. Use the row filter (labeled "All roles") to show only Custom roles or only System roles.
2. Type in Find a permission… to highlight matching columns; matching categories expand automatically so you can see the permission.
3. Use Expand all / Collapse all to open or fold every category at once. Your expand/collapse choices are remembered for next time.
4. Click the X in the search field to clear it.

Setting a permission (Inherit / Allow / Deny)

• Purpose: Define exactly what a role can do.
• Where to find it: Any cell in an expanded category, on a custom (non‑system) role.
• What you'll see: A three‑button toggle in each cell.

How to use it:

1. Expand the category you want to edit by clicking its header.
2. In the role's row, click one of the three buttons in the cell:
   • Inherit — the role takes whatever its parent grants for this permission. When a cell is set to Inherit, it faintly shows the inherited result so you are never guessing.
   • Allow — explicitly grant the permission.
   • Deny — explicitly block the permission, even if a parent allows it.
3. Repeat for as many cells and roles as you like — you can edit several roles in one pass. Edited cells are highlighted.
4. Click Save changes in the save bar at the bottom to apply everything at once, or Discard to undo your pending edits.

Explicit vs. Effective view

• Purpose: Tell apart what a role sets from what it can actually do.
• Where to find it: The Explicit / Effective toggle in the toolbar.
• What you'll see:
  • Explicit (default) shows what is configured on each role; Inherit cells stay editable and hint at the inherited value.
  • Effective shows the fully resolved access after walking the inheritance chain — exactly what users with that role will experience. In this view the matrix is read‑only.

Creating and editing a role's details

• Purpose: Set a role's name, code, parent (who it inherits from), and description.
• Where to find it: The New role button, or the ⋮ menu on a role's row → Edit details.
• What you'll see: A dialog with the role's fields, including an Inherits from dropdown that sets the parent.

How to use it:

1. Click New role, or open a role's ⋮ menu and choose Edit details.
2. Fill in the Name (the Code is generated automatically if you leave it blank).
3. Choose a parent under Inherits from, or leave it as No parent (top‑level).
4. Optionally add a Description.
5. Save. Then set the role's permissions in the matrix.

Complete Workflows

Workflow: Creating a modified copy of a role

• Goal: Create a new role based on an existing one without starting from scratch.
• Prerequisites: An existing role to copy.

Steps:

1. Open the ⋮ menu on the row of the role you want to copy.
2. Select Duplicate. The copy appears as a child of the original, inheriting its permissions.
3. Open the copy's ⋮ menu → Edit details to rename it (and adjust its parent if needed), then Save.
4. Expand the categories you want to change and set cells to Allow, Deny, or Inherit.
5. Click Save changes in the save bar.

• Expected result: A new role with your name and adjusted permissions.

Workflow: Tightening one permission across several roles

• Goal: Deny a sensitive action on multiple roles in a single pass.
• Prerequisites: The roles must be custom (not system).

Steps:

1. Use Find a permission… to locate the permission column (it expands automatically).
2. In each affected role's row, click Deny in that cell.
3. Review the save bar — it shows the number of pending changes and how many roles they touch.
4. Click Save changes.

• Expected result: The permission is explicitly denied on every role you edited.

Workflow: Deleting an obsolete custom role

• Goal: Remove a role that is no longer needed.
• Prerequisites: The role must be Custom and must have no child roles inheriting from it.

Steps:

1. Open the role's ⋮ menu.
2. Select Delete (shown in red).
3. Review the warning in the confirmation dialog.
4. Confirm to delete.

• Expected result: The role is removed and unassigned from any users who held it.

Who can use it

This page is reserved for people with the Manage roles permission — its catalog description is "create and edit role definitions." A second, related permission, View audit logs, gives auditors read‑only access so they can review role configurations without changing them.

How permissions are grouped

Permissions are organized into categories, each a column group in the matrix. Hover a column header to see the permission's full name and description. Highlights you will see as you browse:

• Assets — view, upload, edit metadata, delete, download, share, and replace files.
• Attachments — view, edit, and delete supporting documents like model releases and contracts.
• Collections — view, create, edit, delete, share, and manage collections owned by others.
• Custom Pages — view, create, edit, publish, and delete branded portal pages.
• Workflows — view history, override transitions, and design new workflows.
• AI and Studio — use chat, open the Studio image editor, administer AI providers, and review AI costs.
• Admin: Users and Security — manage users, roles, role assignments, user groups, user requests, asset requests, access requests, invitations, and audit logs.
• Admin: System Configuration — asset classes, collection types, metadata, vocabularies, watermarks, templates, automation rules, and global settings.
• Rights — create rights policies, apply rights to assets, and view rights on assets.

Each cell has three states: Inherit, Allow, and Deny. Deny always wins, so you can explicitly block a sensitive action even if a parent role grants it. A cell left on Inherit follows the parent chain.

Limits and guardrails

• System roles are read‑only: Roles marked "System" ship with the product and are required for core functionality. They show a lock icon, their cells cannot be edited, and they cannot be deleted. You can still duplicate them to start a custom role.
• No orphaned users: A role cannot be deleted while anyone still has it assigned. The error tells you exactly how many users are on the role.
• No orphaned inheritance: A role cannot be deleted while any child role inherits from it. Move or delete the children first.
• No circular inheritance: A role cannot be set as its own parent, nor as a child of one of its own descendants. The dialog rejects the change.
• Administrator seat cap: The number of people who can hold an administrator‑level role at once is limited by your plan. Assigning someone a role with any "Admin" permission is blocked with a clear message if you are already at the cap.

What happens behind the scenes

• Hierarchical inheritance: A child role automatically gains every permission from its parent chain; you only declare what is different. Duplicating a role makes the copy a child of the original, so your changes are additive by default.
• Effective permissions are computed for you: The matrix walks the parent chain to show each role's resolved access. Switch to the Effective view to see exactly what users with that role will experience at runtime.
• Changes are batched: Cell edits are collected and applied together when you click Save changes, so you can review everything before committing — and edit several roles in one go.

Tips and Best Practices

• Compare instead of opening windows: Pin the view to Custom roles and expand a category to compare the same permissions across several roles at once.
• Use Effective to audit: Switch to Effective to confirm what a role truly grants after inheritance, then switch back to Explicit to make changes.
• Lean on inheritance: Set common permissions on a parent role and leave children on Inherit; only override where a child genuinely differs.
• Collapse to scan, expand to edit: Collapsed categories show a coverage count (like 6/9) that's perfect for a quick audit; expand only what you're changing.

Troubleshooting

Issue: A role's cells can't be edited

• Symptoms: The three‑button toggles don't appear; cells show a single icon and a lock sits next to the role name.
• Cause: It is a System role, which is read‑only by design.
• Fix: Duplicate the system role to create an editable custom role, then edit the copy.

Issue: Cannot delete a role

• Symptoms: The Delete option is unavailable, or an error mentions child roles or assigned users.
• Cause: The role is a protected System role, has child roles inheriting from it, or still has users assigned.
• Fix: Re‑parent or delete the child roles first, and reassign any users. System roles cannot be deleted.

Issue: Permission changes not taking effect

• Symptoms: A user assigned to the role still cannot perform an action you set to "Allow."
• Cause: The changes were not saved, or the user holds another role that explicitly Denies the permission (Deny always wins).
• Fix: Confirm you clicked Save changes and the save bar cleared. Then check the user's other roles for an explicit Deny on the same permission.