Roles Management

Overview

The Roles module allows you to create and manage roles that group permissions together. Roles are the foundation of the permission system, making it easy to assign consistent sets of permissions to multiple users at once. Instead of assigning individual permissions to each user, you create roles with specific permissions and then assign those roles to users.

Accessing Roles Management

Navigation: Dashboard > Users > Roles & Permissions

Required Permission: roles.view

Key Features

• Role Creation: Define custom roles with specific permission sets
• Permission Management: Assign and remove permissions from roles
• User Assignment: View and manage which users have each role
• Role Descriptions: Add descriptions to clarify each role's purpose
• Statistics: See how many users and permissions each role has
• Protected System Roles: Super admin and admin roles are protected from deletion

Main Interface

List View

The roles list displays all roles in a card-based grid layout with the following information:

Role Cards Display:

• Role Icon: Visual indicator with role badge
• Role Name: The name of the role (e.g., "Admin", "Editor")
• System Role Badge: Indicates if it's a protected system role
• Description: Brief explanation of the role's purpose
• Statistics:
  • Number of users with this role
  • Number of permissions assigned to the role
• Action Buttons: View, Edit, Delete (if allowed)

Statistics Dashboard:
At the top of the page, you'll see summary cards showing:

• Total Roles: Count of all roles in the system
• Total Users: Sum of all users across all roles
• Permissions: Total number of available permissions

Available Actions:

• View Permissions: Link to view all available permissions
• Create Role: Button to create a new role (if you have permission)
• Search: Filter roles by name or description

Role Details View

When viewing a specific role, you'll see:

Role Information:

• Role name and description
• Creation and last update dates
• Total permissions count
• Total users count

Permissions List:

• All permissions assigned to this role
• Grouped by category for easy review
• Permission names and descriptions

Users List:

• All users who have this role assigned
• User names and email addresses
• Quick links to user profiles

Common Tasks

Creating a New Role

1. Click the "Create Role" button in the top right corner
2. Fill in the required fields:
   • Name: Unique name for the role (required)
   • Description: Brief explanation of the role's purpose (optional but recommended)
3. Select permissions:
   • Permissions are grouped by category (Users, Roles, Pages, etc.)
   • Check the boxes for permissions you want to include
   • You can expand/collapse categories for easier navigation
4. Click "Create Role" to save

Validation Rules:

• Role name must be unique
• Role name can only contain letters, numbers, underscores, dashes, and spaces
• Role name cannot contain special characters like <>"/\
• Description is limited to 500 characters

What Happens:

• Role is created with selected permissions
• Role becomes immediately available for assignment to users
• Role creation is logged in the audit system
• Success message confirms the creation

Example Roles:

• Content Editor: Can create and edit pages, manage media, but cannot access user management
• SEO Manager: Can manage SEO settings, sitemaps, and page metadata
• Support Agent: Can view contact messages and impersonate users for troubleshooting

Editing a Role

1. Find the role in the list
2. Click the Edit button (pencil icon) on the role card
3. Update the desired fields:
   • Name: Change the role name (must remain unique)
   • Description: Update the description
   • Permissions: Check or uncheck permissions to add or remove them
4. Click "Update Role" to save changes

Important Notes:

• Super admin role cannot be edited (protected system role)
• Admin role cannot be edited (protected system role)
• Permission changes affect all users with this role immediately
• All changes are logged in the audit system with detailed permission changes

Permission Changes:

• Adding permissions grants new access to all users with this role
• Removing permissions revokes access immediately
• Permission caches are automatically cleared after changes

Deleting a Role

Scenario 1: Role Has No Users

1. Find the role in the list
2. Click the Delete button (trash icon)
3. Confirm the deletion
4. Role is permanently removed

Scenario 2: Role Has Assigned Users

1. Click the Delete button
2. You'll see a confirmation dialog with two options:
   • Reassign Users: Choose another role to assign these users to
   • Remove Role Only: Remove the role from users (they keep other roles)
3. Select your preferred option
4. If reassigning, choose the target role from the dropdown
5. Confirm the deletion
6. Role is deleted and users are handled according to your choice

Restrictions:

• Cannot delete system roles (super_admin, admin)
• Deletion is permanent and cannot be undone
• All role deletions are logged in audit system

What Happens:

• Role is removed from the database
• Users are either reassigned or have the role removed
• All permission assignments for this role are removed
• Audit log records the deletion and any user reassignments

Viewing Role Details

1. Click on a role card or the View button (eye icon)
2. The role details page shows:
   • Role Information: Name, description, dates
   • Statistics: Permission count, user count
   • Permissions: Complete list grouped by category
   • Users: All users with this role
   • Actions: Edit and delete buttons

Managing Role Permissions

Adding Permissions:

1. Edit the role
2. Scroll through the permission categories
3. Check the boxes for permissions you want to add
4. Save the changes

Removing Permissions:

1. Edit the role
2. Find the permissions you want to remove
3. Uncheck their boxes
4. Save the changes

Understanding Permission Categories:
Permissions are organized into categories:

• Users: User account management
• Roles: Role and permission management
• Pages: Content page management
• Media: Media library access
• Settings: System configuration
• Security: Security features and audit logs
• SEO: SEO and sitemap management
• And more...

Managing Users in a Role

Viewing Users:

1. Open the role details page
2. Scroll to the "Users" section
3. See all users with this role

Adding Users to a Role:

• Go to the Users module
• Edit the user or use bulk actions
• Assign the role to the user

Removing Users from a Role:

• Go to the Users module
• Edit the user or use bulk actions
• Remove the role from the user

Settings and Options

Name Field

• Type: Text input
• Required: Yes
• Max Length: 255 characters
• Validation: Alphanumeric, underscores, dashes, and spaces only
• Description: Unique identifier for the role
• Example: "content_editor", "SEO Manager", "support-agent"

Description Field

• Type: Textarea
• Required: No (but recommended)
• Max Length: 500 characters
• Description: Explains the role's purpose and intended use
• Example: "Can create and edit content pages, manage media files, but cannot access user management or system settings"

Permissions Field

• Type: Checkbox list (grouped by category)
• Required: No (roles can have zero permissions)
• Description: Select which permissions this role should have
• Notes:
  • Permissions are grouped by category for easier selection
  • You can select all permissions in a category or individual ones
  • Changes affect all users with this role immediately

Permissions

The following permissions control access to the Roles module:

• roles.view: Can view the roles list and role details
• roles.create: Can create new roles
• roles.edit: Can edit existing roles and their permissions
• roles.delete: Can delete roles (except system roles)

Permission Hierarchy:

• Viewing roles is the base permission
• Creating, editing, and deleting require their respective permissions
• Super admins have all permissions by default
• System roles (super_admin, admin) cannot be modified even with permissions

Tips and Best Practices

• Use Descriptive Names: Name roles based on job functions (e.g., "Content Editor", "SEO Manager") rather than generic names like "Role1"
• Add Clear Descriptions: Always add descriptions explaining what the role is for and who should have it
• Follow Least Privilege: Only grant permissions that are necessary for the role's function
• Group Related Permissions: When creating roles, think about complete workflows and include all permissions needed for those workflows
• Test New Roles: Use the impersonation feature to test new roles before assigning them to real users
• Regular Reviews: Periodically review role permissions to ensure they're still appropriate
• Avoid Too Many Roles: Having too many similar roles makes management difficult; consolidate when possible
• Document Custom Roles: Keep notes about why custom roles were created and their intended use cases
• Use Role Hierarchy: Create a logical hierarchy (e.g., Editor < Manager < Admin) for easier understanding

Troubleshooting

Problem: Cannot Create Role - Name Already Exists

Solution: Role names must be unique. Choose a different name or check if a similar role already exists that you could use instead.

Problem: Cannot Edit or Delete Super Admin Role

Solution: This is a security feature. The super_admin and admin roles are system roles that are protected from modification to prevent accidental lockouts. These roles should not be modified.

Problem: Cannot Delete Role - Has Assigned Users

Solution: When deleting a role with users, you must choose to either:

• Reassign users to another role
• Remove the role from users (they keep their other roles)
  Select your preferred option in the confirmation dialog.

Problem: Permission Changes Not Taking Effect

Solution:

• Permission changes should take effect immediately
• Users may need to log out and log back in to see changes
• Check if permission caching is causing delays
• Verify the permission was actually saved by viewing the role details

Problem: Users Have Wrong Permissions After Role Edit

Solution:

• Review the role's current permissions in the role details view
• Check if the user has multiple roles (they get permissions from all roles)
• Verify you edited the correct role
• Check the audit logs to see what changes were made

Problem: Cannot Find Permission to Add to Role

Solution:

• Permissions are grouped by category; expand all categories to find it
• Use the search function if available
• Check the Permissions module to see all available permissions
• The permission might not exist; contact a developer if a new permission is needed

Problem: Role Creation Fails with Validation Error

Solution:

• Check that the role name doesn't contain special characters (<>"/\)
• Ensure the name is unique
• Verify the description is under 500 characters
• Remove any invalid characters and try again

Related Modules

• Users: Assign roles to users and manage user access
• Permissions: View all available permissions and understand what they control
• Impersonation: Test roles by impersonating users who have them
• Audit Logs: Review all role management activities and permission changes
• Security Settings: Configure additional security requirements