Roles & Permissions Manager Guide

This guide covers how to create custom roles, assign permissions, and manage access control for your team members.

Overview

SWELLEnterprise uses a role-based access control (RBAC) system where:

• Roles define a set of permissions
• Users are assigned roles within a tenant
• Permissions control what actions users can perform
• Custom roles can be created to match your business needs

Accessing Roles & Permissions Manager

Location: Settings → Roles & Permissions

Requirements: Only Owner or Admin roles can manage roles and permissions.

Understanding Permissions

Permission Structure

Permissions follow a pattern: {module}.{action}

Core Module Permissions:

• CRM: crm.view, crm.create, crm.edit, crm.delete
• Projects: projects.view, projects.create, projects.edit, projects.delete
• Finance: finance.view, finance.create, finance.edit, finance.delete, finance.approve
• Files: files.view, files.upload, files.delete

Proposals & Contracts:

• Proposals: proposals.view, proposals.create, proposals.edit, proposals.delete, proposals.send
• Contracts: contracts.view, contracts.create, contracts.edit, contracts.delete, contracts.send

Automation & Workflows:

• Workflows: workflows.view, workflows.create, workflows.edit, workflows.delete, workflows.execute

Communication & Marketing:

• Communication/Chat: communication.view, communication.send, communication.manage
• Email & Marketing: email.view, email.send, email.campaigns.create, email.campaigns.edit, email.campaigns.delete, email.templates.manage

Scheduling & Calendar:

• Scheduling: scheduling.view, scheduling.create, scheduling.edit, scheduling.delete
• Calendar: calendar.view, calendar.create, calendar.edit, calendar.delete

Business Operations:

• HR: hr.view, hr.create, hr.edit, hr.delete
• Templates: templates.view, templates.create, templates.edit, templates.delete

Tenant Management:

• tenant.settings.view - View tenant settings
• tenant.settings.edit - Edit tenant settings
• tenant.modules.manage - Activate/deactivate modules
• tenant.users.manage - Invite and manage team members

Permission Scopes

Currently, permissions apply to all records in the tenant. Future enhancements may include:

• Own Records: Permissions only for records created by the user
• Team Records: Permissions for records within the user's team/department
• All Records: Full access to all tenant records

Default Roles

System Roles (Cannot be edited/deleted)

These roles are reserved and managed by the system:

• super-admin: Full system access (system-level, not tenant-scoped)
• owner: Full tenant access (tenant creator)
• tenant-owner: Alias for owner
• admin: Full access, can manage users and settings
• member: Standard access for team members
• guest: Read-only access

Management Roles

These roles come pre-configured with appropriate permissions:

• operations-manager: Day-to-day operations and team management
• account-manager: Client relationships and CRM
• project-manager: Project oversight and delivery
• finance-manager: Financial oversight and approvals
• sales-manager: Lead management and sales tracking
• hr-manager: Employee management and HR functions

Creating Custom Roles

Step 1: Create Role

1. Go to Settings → Roles & Permissions
2. Click "+ Create Role" button
3. Fill in:

• Role Name: Use lowercase letters, numbers, and hyphens (e.g., content-editor, customer-support)
• Description (optional): Describe what this role is for

Step 2: Assign Permissions

By Module:

• Expand each module section
• Check permissions you want to grant
• Use "Select All" to quickly grant all permissions for a module

Permission Groups:

The system organizes permissions by module. Each module may have multiple permission types:

• CRM: View, Create, Edit, Delete contacts/companies/leads
• Projects: View, Create, Edit, Delete projects/tasks
• Finance: View, Create, Edit, Delete, Approve invoices/payments
• Files: View, Upload, Delete files
• Proposals: View, Create, Edit, Delete, Send proposals
• Contracts: View, Create, Edit, Delete, Send contracts
• Workflows: View, Create, Edit, Delete, Execute automated workflows
• Communication: View messages, Send messages, Manage channels
• Email & Marketing: View emails, Send emails, Create/edit campaigns, Manage templates
• Scheduling: View, Create, Edit, Delete scheduled events
• HR: View, Create, Edit, Delete HR records (employees, departments, etc.)
• Calendar: View, Create, Edit, Delete calendar events
• Templates: View, Create, Edit, Delete templates
• Tenant Management: View/edit settings, manage modules, manage users

Example Custom Roles:

Content Editor:

• crm.view, crm.create, crm.edit
• files.view, files.upload
• No delete permissions, no finance/projects access

Customer Support:

• crm.view, crm.edit (view and update customer info)
• projects.view (view customer projects)
• files.view, files.upload (upload support documents)
• No create/delete permissions

Bookkeeper:

• finance.view, finance.create, finance.edit, finance.approve
• crm.view (view customer info for invoicing)
• No delete permissions, no project access

Step 3: Save Role

Click "Create Role" to save. The role is immediately available for assignment.

Editing Roles

Edit Custom Roles

1. Go to Settings → Roles & Permissions
2. Find the role you want to edit
3. Click "Edit"
4. Modify:

• Role name (must be unique)
• Description
• Permissions (add/remove as needed)

5. Click "Update Role"

Note: System roles (admin, member, guest, etc.) cannot be edited.

Deleting Roles

Delete Custom Roles

1. Go to Settings → Roles & Permissions
2. Find the custom role you want to delete
3. Click "Delete"
4. Confirm deletion

Important:

• System roles cannot be deleted
• Users with the deleted role will need to be reassigned to a different role
• Check team member assignments before deleting roles

Assigning Roles to Users

When Inviting Users

1. Go to Settings → Team
2. Click "+ Invite User"
3. Select role from dropdown:

• Management Roles: Default business roles
• Standard Roles: Basic access levels
• Custom Roles: Roles you've created

4. Send invitation

Changing User Roles

1. Go to Settings → Team
2. Find the user
3. Click "Edit"
4. Change their role from dropdown
5. Click "Save Changes"

Note: Changes take effect immediately.

Permission Best Practices

Principle of Least Privilege

Grant users minimum permissions they need to do their job:

• View-only users: Only view permissions
• Data entry: view + create + edit (no delete)
• Managers: All CRUD + approve where applicable
• Administrators: All permissions including tenant.users.manage

Role Naming Conventions

Use descriptive, lowercase names with hyphens:

✅ Good:

• content-editor
• customer-support
• finance-assistant
• project-lead

❌ Bad:

• ContentEditor (no capitals)
• content_editor (use hyphens, not underscores)
• role1 (not descriptive)

Common Role Patterns

Read-Only Access:

• All view permissions
• No create, edit, delete

Data Entry:

• view + create + edit for relevant modules
• No delete or approve

Manager/Team Lead:

• All CRUD permissions
• approve permissions (finance, etc.)
• Module-specific focus

Full Access (Admin-like):

• All permissions for all modules
• tenant.users.manage
• tenant.settings.edit

Troubleshooting

Role Not Showing in Dropdown

Issue: Custom role doesn't appear when inviting users.

Solution:

• Verify role was created successfully in Roles & Permissions
• Check role name doesn't match reserved names
• Refresh the page

Permission Not Working

Issue: User has permission but still can't perform action.

Solution:

• Verify user's role has the permission
• Check permission is checked in role editor
• Ensure user's role is assigned correctly (Settings → Team → Edit)
• Check if module is active for tenant (Settings → Modules)

Cannot Edit/Delete Role

Issue: Edit/Delete buttons are grayed out or missing.

Solution:

• System roles cannot be edited/deleted
• Only custom roles can be modified
• Verify you're logged in as Owner or Admin

Users Losing Access After Role Deletion

Issue: Users can't access features after their role was deleted.

Solution:

• Before deleting a role, assign all users to a new role
• Go to Settings → Team → Edit each user → Change role
• Then delete the old role

Examples: Creating Common Business Roles

Example 1: Customer Success Manager

Goal: Manage customer relationships, view projects, update CRM records.

Permissions:

• CRM: view, create, edit (no delete)
• Projects: view, edit (update project status)
• Files: view, upload
• Finance: view (see invoices, but not create)

Steps:

1. Create role: customer-success-manager
2. Select permissions above
3. Save and assign to team members

Example 2: Accounts Receivable Specialist

Goal: Manage invoices and payments, view customer info.

Permissions:

• Finance: view, create, edit, approve
• CRM: view (customer info for invoicing)
• Files: view, upload (payment receipts)
• No projects access

Steps:

1. Create role: accounts-receivable
2. Select finance permissions + CRM view + Files view/upload
3. Save and assign

Example 3: Project Coordinator

Goal: Manage projects and tasks, view customer info.

Permissions:

• Projects: view, create, edit, delete
• CRM: view, edit (update customer project status)
• Files: view, upload, delete (project files)
• No finance access

Steps:

1. Create role: project-coordinator
2. Select project permissions + CRM view/edit + Files all
3. Save and assign

Advanced: Role-Based Super Admin

Grant Super Admin via Role

Users can have super admin access via the super-admin role:

Via Filament Admin Panel:

1. Go to /admin
2. Navigate to Users
3. Edit the user
4. Assign them the super-admin role

Via Code:

$user->assignRole('super-admin'); // Global role (not tenant-scoped)

Via Artisan:

php artisan user:set-super-admin user@example.com

The isSuperAdmin() method checks both:

1. is_super_admin boolean field (system-level)
2. super-admin role (role-based)

This allows operations managers or senior staff to have super admin access without modifying the database directly.

Related Documentation

• User Invitations & Roles - Complete user management guide
• Team Management - Inviting and managing team members
• Business Roles Guide - Default business roles explained

Need help? Contact support or visit our knowledge base for more information.

Updated on: 13/03/2026