Roles & Permissions

Overview

Roles define what users can see and do in Forz. Each user is assigned exactly one role. Permissions are grouped by feature (called a "policy" in Forz) and toggled individually. Forz ships with default system roles (Admin, Worker) and lets you create custom roles to match your organization's structure — for example, a "Dispatcher" role that can manage jobs and schedules but cannot change billing settings.

Before You Begin

Prerequisites:

1. You have the Admin role (or master admin access).

2. The Custom Roles module is enabled (Settings > Modules).

System Roles

Forz creates two default system roles when your account is set up:

• Admin — full access to all features. This role is locked and cannot be edited or deleted. Every account must have at least one Admin user.

• Worker — limited access intended for field technicians. This role is a default but is hidden from the roles list in Settings.

Warning: System roles (Admin and Worker) cannot be viewed in the role editor, renamed, or deleted. To customize permissions for technicians or other staff, create a custom role.

Creating a Custom Role

1. Click Settings in the sidebar navigation.

1. Click the Custom Roles tab.

1. Click + New Role.

1. Enter a Display Name for the role (e.g., "Dispatcher", "Office Manager", "Foreman"). Role names must be unique within your account.

1. Click Save.

Expected result: Forz creates the role with all permissions disabled. The role editor opens so you can toggle individual permissions.

Note: New roles start with zero permissions. You must enable each permission the role needs. This prevents accidental over-granting of access.

Configuring Permissions

Permissions are organized by policy group (feature area). Each group contains individual actions you can enable or disable.

1. Open the role you want to configure (click its name in the Custom Roles list).

1. Permissions are displayed in groups (e.g., "Jobs", "Customers", "Invoices", "Calendar").

1. Click the toggle next to any individual permission to enable or disable it.

Expected result: The permission updates immediately. All users assigned to this role see the change on their next page load (the permissions cache is invalidated automatically).

Tip: Review permissions from top to bottom within each group. Typical groups include actions like "View", "Create", "Edit", and "Delete". Most roles need at least "View" enabled for the features they use.

Cloning a Role

When you need a new role similar to an existing one, clone it to save time.

1. Open the role you want to copy.

1. Click the Clone button.

1. Enter a Display Name for the new role.

1. Click Save.

Expected result: Forz creates a new role with the same permissions as the original. You can then adjust individual permissions on the clone without affecting the source role.

Editing a Role Name

1. Open the role from the Custom Roles list.

1. Click Edit.

1. Change the Display Name.

1. Click Save.

Expected result: The role name updates everywhere it appears, including on user profiles. The role_name field on each user assigned to this role updates the next time the user record is saved.

Warning: You cannot rename or edit locked roles. The Admin role is always locked. Roles marked as default can be renamed but not deleted if users are assigned to them.

Deleting a Role

1. Open the role from the Custom Roles list.

2. Click Delete.

Expected result: The role is removed from the system.

Warning: You can only delete a role if: it is not locked, it is not a default system role, and no users are currently assigned to it. Reassign all users to a different role before deleting.

What Happens After Changing Permissions

When a role's permissions are updated, Forz automatically:

• Invalidates the permissions cache — every user on that role gets fresh permission checks on their next request.

• Invalidates sidebar caches — if role-based sidebar visibility changed, users see updated navigation items.

• Applies immediately — no logout/login required; changes take effect on the next page load.

Common Scenarios

Creating a "Dispatcher" role for office staff

Your office coordinator needs to create and schedule jobs, manage customers, and view the calendar, but should not access billing or account settings.

1. Go to Settings > Custom Roles and click + New Role.

2. Name it "Dispatcher".

3. Enable permissions: Jobs (View, Create, Edit), Customers (View, Create, Edit), Calendar (View), Route Planner (View, Create), and Schedule Suggestions (View).

4. Leave Invoices, Payments, Estimates, and Settings permissions disabled.

5. Assign the dispatcher user to this role in Settings > Users.

Setting up a read-only "Auditor" role

An external auditor needs view-only access to jobs, invoices, and reports for a compliance review.

1. Create a new role named "Auditor".

2. Enable only "View" permissions for Jobs, Invoices, Custom Reports, and Dashboards.

3. Leave all Create, Edit, and Delete permissions disabled.

4. Create a user account for the auditor and assign this role.

Cloning a role for a new team

Your plumbing division needs the same permissions as your HVAC dispatchers, but with access to the Devices module added.

1. Open the "HVAC Dispatcher" role and click Clone.

2. Name the clone "Plumbing Dispatcher".

3. Enable the Devices permissions (View, Create, Edit) on the new role.

Troubleshooting