Role-Based Access Control (RBAC) - Configuration Guide

---

Overview

Role-Based Access Control (RBAC) in the Permitting System provides a comprehensive framework for managing user permissions. The system uses a hierarchical structure of Roles, Resources, Modules, and Actions to control access to features and data throughout the platform.

Key Concepts

---

Prerequisites

Before configuring RBAC, ensure:

• User has System Administrator or Super Admin role
• User has access to the Administration section
• Understanding of organizational role requirements
• Documentation of required permission mappings

---

Quick Start: Step-by-Step Instructions

This section provides simple, direct instructions for common role management tasks.

How to Create a New Role

Step 1: Open Role Management

1. Click Administration in the main navigation menu
2. Click Settings in the sidebar
3. Click Roles

Step 2: Add the New Role

1. Click the Add New Role button (top right)
2. Fill in the form:
   • Role Name: Enter a descriptive name (e.g., "Permit Technician", "Inspector")
   • Role Description: (Optional) Describe what this role does
3. Click Next or scroll to the permissions section

Step 3: Select Permissions

1. Permissions are grouped by module. Expand each module to see available permissions.
2. For a typical Permit Technician role, select:
   • ENTITY_RECORD module: VIEW_ENTITY_RECORD, CREATE_ENTITY_RECORD, EDIT_ENTITY_RECORD
   • ENTITY_VIEWS module: VIEW
3. For an Inspector role, also add:
   • CALENDAR_ADMIN: VIEW, MANAGE (for scheduling)
4. Click Save to create the role

---

How to Assign a Role to a User

Step 1: Open User Management

1. Click Administration in the main navigation menu
2. Click User Management in the sidebar
3. Find the user you want to modify (use the search bar if needed)

Step 2: Edit User Roles

1. Click on the user's row to open their profile, OR click the Edit (pencil) icon
2. Scroll to the Roles section
3. Click the Roles dropdown
4. Check the box next to each role you want to assign (e.g., "Permit Technician")
5. Click Save or Update User

Step 3: Verify the Assignment

1. The user must log out and log back in for the new permissions to take effect
2. To verify, check the user's profile shows the assigned roles

---

How to Remove a Role from a User

1. Go to Administration > User Management
2. Click on the user to edit
3. In the Roles section, uncheck the role you want to remove
4. Click Save
5. The user must log out and log back in for changes to take effect

---

Recommended Roles for Permitting

---

Troubleshooting

Common Issues

User Cannot Access Feature

Check:

1. User's role has the required resource permission
2. User's role includes the required module
3. User has logged out and back in after permission changes
4. Check browser console for authorization errors

Permission Changes Not Taking Effect

Check:

1. Clear browser cache and local storage
2. User must log out and log back in
3. Verify the role was saved successfully
4. Check that user is assigned to the updated role

---

Related Documentation

• View Configuration
• Entity Builder
• Form Builder
• Process Library

---

Technical Reference

The sections below provide detailed technical information for developers and advanced administrators.

---

Section 1: System Roles

1.1 Built-in Roles

The system includes the following predefined roles:

1.2 Role Hierarchy

---

Section 2: Resources

2.1 Core System Resources

2.2 Entity Management Resources

2.3 Document Processing / Process Library Resources

These resources control access to the Document Processing module (also known as Process Library). This module provides AI-powered permit evaluation, criteria management, and the permit dashboard for analytics.

Note: These resources are specific to the Document Processing (Process Library) module. Staff who only process permits through Entity Manager views do not need access to these resources.

2.4 Calendar/Scheduling Resources

2.5 Administration Resources

2.5 Communication Resources

2.6 Reporting & Analytics Resources

---

Section 3: Modules

3.1 Permitting Solution Modules

The following modules are used in the Permitting Solution. When configuring roles, focus on these modules:

Note: Other platform modules (Workforce, AI-EMS, EDS, Contract Analysis, Legal Assistant, Constituent Complaints) are not used in the Permitting Solution and are not covered in this guide.

---

Section 4: Actions

4.1 Standard CRUD Actions

4.2 View & Manage Actions

4.3 Entity Record Actions

4.4 Workflow Actions

4.5 Message Actions

4.6 Channel Actions

4.7 Communication Actions

4.8 Department Actions

4.9 Access & Tracking Actions

4.10 Reporting Actions

---

Section 5: Creating and Managing Roles

5.1 Navigate to Role Management

Navigation: Administration → Settings → Roles

5.2 Create New Role

1. Click Add New Role
2. Enter role details:

5.3 Assign Permissions to Role

Permissions are grouped by Application/Module for easier management.

Application Management Filter: The following modules are managed separately and excluded from the standard application permissions filter:

• USER_MANAGEMENT
• ENTITY_VIEWS
• ENTITY
• AUTOMATION_BUILDER
• ENTITY_RECORD

5.4 Role CRUD Operations

---

Section 6: View-Specific Permissions

6.1 Entity View Permissions

Views in the Entity Manager have their own permission system:

6.2 Combining RBAC with View Permissions

The permission check follows this order:

1. Module Access: User must have access to ENTITY_VIEW module
2. Resource Permission: User must have appropriate action on ENTITY_VIEW resource
3. View Visibility: View's visibility setting must allow user access

---

Section 7: Best Practices

7.1 Role Design Principles

1. Principle of Least Privilege: Grant minimum permissions needed
2. Role Grouping: Create roles based on job functions
3. Avoid Individual Permissions: Use roles, not user-specific permissions
4. Regular Audits: Review role assignments periodically

7.2 Permission Naming Conventions

7.3 Recommended Role Templates

Basic Staff Role:

Supervisor Role:

Administrator Role:

---

Code Reference

Source Files

API Routes

Role management uses the following API service files:

• useCreateRole.ts - Create new role
• useDeleteRole.ts - Delete role
• useGetRoles.ts - List all roles
• useGetRolePermission.ts - Get role permissions
• useUpdateRole.ts - Update role
• useGetBasePermissionsData.ts - Get available permissions
• useGetBasePermissionsDataForModule.ts - Get module-specific permissions

---

This guide is aligned with the role-base-auth package and govt-assist-host codebase as of December 2025.