> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.swellsystem.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Roles & Permissions Manager Guide

# 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:**
```php
$user->assignRole('super-admin'); // Global role (not tenant-scoped)
```

**Via Artisan:**
```bash
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](https://help.swellsystem.com/en/article/user-invitations-roles-permissions-guide-1k9k848/) - Complete user management guide
- [Team Management](https://help.swellsystem.com/en/article/team-management-1x692m2/) - Inviting and managing team members
- [Business Roles Guide](https://help.swellsystem.com/en/article/business-roles-permissions-guide-f60uo3/) - Default business roles explained

---

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