How It Works
The permission system has three main components:- Permissions — Individual actions users can perform (e.g., “view users”, “create ranks”)
- Roles — Collections of permissions grouped together (e.g., “Admin”, “Recruiter”, “Member”)
- Users — Have one or more roles assigned, granting them all permissions from those roles
Default Roles
PERSCOM includes one built-in role:| Role | Description |
|---|---|
| Admin | Full access to all features and settings. Cannot be modified or deleted. |
Permission Types
Permissions are automatically generated for three categories:Resource Permissions
Control access to data and records. Each resource has multiple permission levels:| Permission | Description |
|---|---|
view_any | View the list of records |
view | View individual record details |
create | Create new records |
update | Edit existing records |
delete | Delete records |
restore | Restore soft-deleted records |
force_delete | Permanently delete records |
reorder | Change the order of records |
view_any_user and view_user can browse and view user profiles, but cannot create, edit, or delete users.
Page Permissions
Control access to specific pages in the application:| Permission | Description |
|---|---|
view_calendar | Access the calendar page |
view_roster | Access the roster page |
view_forms | Access the forms page |
view_widgets | Access the widgets page |
Widget Permissions
Control which dashboard widgets users can see:| Permission | Description |
|---|---|
view_calendar_widget | See the calendar widget |
view_recent_records_widget | See recent records widget |
view_organization_info_widget | See organization info widget |
Create A Custom Role
- Navigate to Settings > Users > Roles.
- Select New role.
- Enter a Name for the role (e.g., “Recruiter”, “Training Officer”).
- Configure permissions in each tab:
- Resources — Data access permissions
- Pages — Page access permissions
- Widgets — Widget visibility permissions
- Select Create.
Permission Selection
When creating or editing a role, permissions are organized by category. For each resource, you can:- Select All — Grant all permissions for that resource
- Select Individual — Choose specific permissions (view, create, update, etc.)
Tip: Start with minimal permissions and add more as needed. It’s easier to grant additional access than to revoke it.
Example Roles
Here are common role configurations:Recruiter
A role for users who process new applications: Resources:- Users:
view_any,view,create,update - Submissions:
view_any,view,update,delete - Forms:
view_any,view
- Forms:
view
Training Officer
A role for users who manage training records: Resources:- Users:
view_any,view - Training Records:
view_any,view,create,update,delete - Qualifications:
view_any,view,create,update - Qualification Records:
view_any,view,create,update,delete
Read-Only Member
A basic role for members who can only view information: Resources:- Users:
view_any,view - Ranks:
view_any,view - Units:
view_any,view - Positions:
view_any,view - Awards:
view_any,view - Announcements:
view_any,view
- Roster:
view - Calendar:
view
Assign Roles To Users
Assign During User Creation
- Navigate to Users and select New user.
- In the user form, select the Roles to assign.
- Complete the form and select Create.
Assign To Existing Users
- Navigate to Users and select a user.
- Select Edit.
- Select the Roles tab.
- Select Add role to attach roles to the user.
- Select Save.
Remove Roles
- Navigate to the user’s profile and select Edit.
- Select the Roles tab.
- Select the delete icon next to the role to remove it.
- Select Save.
Configure Default Roles
Set roles that are automatically assigned to new users:- Navigate to Settings > Users > Permissions.
- In the Defaults tab, select the Role(s) to assign to new users.
- Optionally, select individual Permission(s) to grant directly.
- Select Save.
Note: Default roles apply to users created through registration or the dashboard. API-created users may need roles assigned separately.
Permission Inheritance
Users inherit all permissions from their assigned roles:- A user with Role A (10 permissions) and Role B (5 permissions) has all 15 permissions
- Permissions are additive — there’s no way to “deny” a permission
- The Admin role automatically includes all permissions
Settings Access
Access to settings pages requires specific permissions:| Settings Section | Required Permission |
|---|---|
| Dashboard Settings | view_settings_dashboard |
| Registration Settings | view_settings_registration |
| Organization Settings | view_settings_organization |
| Permission Settings | Admin role only |
| Role Management | view_any_role, view_role |
Resource Permissions Reference
- Personnel
- Organization
- Content
- Calendars
- System
| Resource | Permissions |
|---|---|
| Users | view_any_user, view_user, create_user, update_user, delete_user |
| Assignment Records | view_any_assignment_record, view_assignment_record, create_assignment_record, update_assignment_record, delete_assignment_record |
| Award Records | view_any_award_record, view_award_record, create_award_record, update_award_record, delete_award_record |
| Rank Records | view_any_rank_record, view_rank_record, create_rank_record, update_rank_record, delete_rank_record |
| Service Records | view_any_service_record, view_service_record, create_service_record, update_service_record, delete_service_record |
| Training Records | view_any_training_record, view_training_record, create_training_record, update_training_record, delete_training_record |
| Combat Records | view_any_combat_record, view_combat_record, create_combat_record, update_combat_record, delete_combat_record |
| Qualification Records | view_any_qualification_record, view_qualification_record, create_qualification_record, update_qualification_record, delete_qualification_record |
Best Practices
Role Design
- Use descriptive names — “Recruiter” is better than “Role 1”
- Follow least privilege — Only grant permissions users actually need
- Create role hierarchies — Build roles that progressively add permissions (Member → NCO → Officer → Admin)
- Document your roles — Keep notes on what each role is intended for
User Management
- Assign multiple roles — Combine roles for users with multiple responsibilities
- Review periodically — Audit user roles regularly to ensure they’re still appropriate
- Use default roles — Configure defaults to ensure new users have basic access
Security
- Limit Admin access — Only trusted users should have the Admin role
- Separate duties — Different people should manage users vs. manage roles when possible
- Audit changes — Review the activity log for permission-related changes
Troubleshooting
User Can’t Access A Feature
- Check which roles the user has assigned
- Verify the role includes the required permission
- Ensure the user has refreshed their browser after role changes
Permission Changes Not Taking Effect
- Have the user log out and log back in
- Clear the application cache if using Redis or file caching
- Verify the role was saved correctly
Can’t Delete A Role
- The Admin role cannot be deleted
- Roles with users assigned cannot be deleted — remove users first
- Ensure you have the
delete_rolepermission