Skip to main content
Role management page at /settings/roles where organization administrators create and manage custom roles and review system roles.

​
Overview

The Roles page displays two tabs — Custom Roles and System Roles — loaded via useCustomRoles. Custom roles are organization-specific and can be created, edited, and deleted; system roles are platform-provided and read-only. The page guards against missing user or organization context with an error message. Navigation to create a new role goes to /settings/roles/new; editing an existing role goes to /settings/roles/:id.

​
Who it’s for

Access follows your organization’s role and module configuration. The component requires a valid authenticated user and an active organization context. Creating new roles requires pf.users.manage.

​
Before you start

  • You must be signed in with a valid organization context.
  • Understand your organization’s access model before creating or modifying roles.

​
Steps

  1. Navigate to /settings/roles.
  2. On the Custom Roles tab, review existing custom roles for your organization.
  3. To create a new role, navigate to /settings/roles/new.
  4. To edit a role, click its row to navigate to /settings/roles/:id.
  5. Review the System Roles tab to see platform-provided roles.

​
Key concepts

Custom role — A role created by your organization with a specific set of permissions. Scoped to the organization. System role — A platform-provided role that cannot be modified. SME: confirm the full list of system roles.

​
Creating a role

Administrators can create a new custom role at /settings/roles/new. This route renders CreateRolePage with no additional permission wrapper on the route itself. The New Role page presents a RoleForm for defining a custom role. The form collects a role name, optional description, and permission assignments. The useCreateRole() mutation (from useCustomRoles) persists the new role scoped to the current organization. The page guards against missing user or organization context and redirects to /settings/roles on successful creation or if context is unavailable.
  1. Navigate to Settings > Roles and select New Role, or go directly to /settings/roles/new.
  2. Enter a Name for the role.
  3. Add an optional Description.
  4. Assign permissions using the role form.
  5. Save the role.

​
Editing a role

The Edit Role page (/settings/roles/:id) provides a full editor for a custom role, allowing administrators to modify its name and description, configure its permission matrix, and manage which users are assigned to the role. The page loads the role via useCustomRole(roleId) and fetches current assignees via useRoleAssignees. Updates are submitted through useUpdateRole. The form uses RoleForm for name and description fields, and a PermissionAssignmentMatrix for configuring which permissions are granted to the role. A second Assignees tab shows users currently assigned to the role. A RoleAssignmentDialog allows adding new assignees. The back button navigates to /settings/roles. Understand the permission matrix structure before making changes that may affect multiple users.
1

Open role editor

Navigate to /settings/roles/:id. The form loads with the role’s current name, description, and permissions.
2

Edit role name and description

Use the RoleForm fields to update the role’s display name and description.
3

Configure permissions

Use PermissionAssignmentMatrix to grant or revoke individual permissions for the role. The matrix displays all available platform permissions grouped by module.
4

Manage assignees

Switch to the Assignees tab to view current users assigned to this role. Click Assign Users to open RoleAssignmentDialog. Adding or removing assignees does not affect the role’s permission configuration.
5

Save changes

Submit the form. Changes are applied via useUpdateRole.

Platform Foundation

Platform Foundation overview.

Governance & parity

Documentation coverage and governance.
This page documents shipped product behavior. It is not medical, legal, or billing advice. Verify against your organization’s policies and applicable regulations before using it for clinical, compliance, or billing decisions. Protected health information (PHI) shown in the product is governed by your tenant’s access controls and is never exposed in this documentation.
  • src/routes/platform.tsx
  • src/platform/roles/pages/RolesPage.tsx
  • src/platform/permissions/hooks/useCustomRoles.ts
  • src/platform/roles/components/RoleList.tsx
  • src/platform/roles/pages/CreateRolePage.tsx
  • src/platform/roles/pages/EditRolePage.tsx
  • src/platform/permissions/hooks/useRoleAssignments.ts