> For the complete documentation index, see [llms.txt](https://docs.cloudscaff.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudscaff.com/settings/user-management/role-builder-add-or-update-roles.md).

# Role Builder: Add or Update Roles

This section explains how to open the Role Builder, create new roles, or edit existing ones.

## Open Role Builder on desktop

Before you begin, confirm the intended company and the authority to manage its roles. A role preset, a person's profile and the site's Site Users selection are separate controls. Do not assume that adding someone to a site creates an account or grants a particular role.

### Open the list

1\. Click Settings in the navigation menu.

2\. Click the arrow on User Profiles.

3\. Click EDIT ROLES on the Users screen.

<figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FtTWWnrULWdf5qk92LITR%2Fclipboard.png?alt=media&amp;token=838d14fd-fd6e-4c78-a47c-58c6fb20ae49" alt="Desktop Users header with EDIT ROLES circled in red."><figcaption></figcaption></figure>

4\. Read the Available Roles list.

The list shows role names, description text, numeric badges, a Search role name or description box and a Name A-Z selector. The screenshot's names and counts are examples. Check the assigned permissions and the user's actual access, not only the role description.

### Inspect a new role form without creating it

5\. Click New Role.

<figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FpjvA5KG2cbZZozOBpUCd%2Fclipboard.png?alt=media&amp;token=5ca9d0ed-0dd1-46e8-9173-9ecc1c0a41ee" alt="Role Builder Available Roles list with New Role circled in red."><figcaption></figcaption></figure>

6\. Review Role Name and Description (optional).

<figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FCtlp01m6N6MdxaZI7inT%2Fclipboard.png?alt=media&amp;token=f79f5771-21b7-4a1d-afb8-eab6dc7842de" alt="Blank New Role form showing Role Name, optional Description, Add permissions and disabled Create Role."><figcaption></figcaption></figure>

The form also shows Add permissions with a Click Here control, a Permissions area, and Create Role. **Create Role** is disabled while the form is blank.

7\. Click the back arrow at the top-left to leave the unchanged form.

The back arrow returns to Available Roles. If you have made changes, read any prompts before leaving.

### Inspect an existing role without saving

8\. Click Permissions beside the role you intend to inspect.

<figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FqXhd7pusPlfNYGShCKP8%2Fclipboard.png?alt=media&amp;token=8a3615af-5c77-4b6c-ae16-13bc2d50a755" alt="Available Roles list with Permissions beside Site User - Scaffold Management circled in red."><figcaption></figcaption></figure>

9\. Read Role Name, Description and the displayed permission labels.

<figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2F0Wyk3bhWYhUOcgVAYyKm%2Fclipboard.png?alt=media&amp;token=eb7e9c3d-8809-43d5-8c78-a9037f56c43d" alt="Existing Site User - Scaffold Management role showing its name, description and 28 permission labels, with the permission area outlined in red."><figcaption></figcaption></figure>

The example **Site User - Scaffold Management** role shows 28 permissions, with **Save Role** disabled before changes. Read your own role's permissions; its name or count may differ.

10\. Click the back arrow at the top-left to return to Available Roles.

11\. Click the back arrow to return to Users.

### Before any actual change

Review Add or Update Permissions and the permission reference before changing a role. Confirm the intended role, affected users and required access. After saving, check the stored permissions and actual access with an affected user's account.

### Mobile

Follow these steps on desktop. Your mobile layout may differ.

***

The Role Builder allows administrators to **create new roles** or **update existing roles** within Cloudscaff. Roles define what users can see and do within the system — ensuring access, control, and security are maintained across all teams.

> **Note:** Only manage roles with the appropriate authorization. Check the saved role and affected users' access after a change.

***

## **Purpose**

The **Roles and Permissions** system in Cloudscaff is designed to control what each user can access, view, and perform within your organization’s account.

It ensures that every user — from site workers to administrators — operates within a clearly defined scope of authority, maintaining data security, operational control, and compliance across all sites and branches.

* **Roles** define **who** a user is in the system (for example, *Site Admin*, *Inventory User*, or *Supervisor*).
* **Permissions** define **what** that role can do — such as creating scaffolds, viewing reports, approving handovers, or managing inventory.

> **Notes:** By assigning specific roles with tailored permissions:
>
> * Administrators can ensure each user only accesses the areas relevant to their responsibilities.
> * Sensitive information and high-level tools remain restricted to authorized personnel.
> * Workflow consistency is maintained across teams, preventing accidental changes or unauthorized actions.

***

## **Accessing the Role Builder**

Use the route that matches where you are working:

1. **From User Profiles**
   * Navigate to **Settings → User Profiles → Edit Roles button.**
   * Click the "**Edit Roles**" Button in the top right corner
2. **From Edit User Page**
   * Navigate to **Settings → User Profiles → Click on a user.**
   * Select a user and click **Select Role** under **Set Role Permissions.**

On the Users screen, **EDIT ROLES** opens Role Builder. Use **New Role** to add a role or **Permissions** to open an existing role.

***

## **Role Builder**

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FEOCYDllLjS4wUMGNlrbd%2FScreenshot%202025-10-31%20at%2012.56.19.png?alt=media&amp;token=e659a6a7-4899-4ec5-a8d7-706910b0f3b8" alt=""><figcaption></figcaption></figure></div>

Once inside the Role Builder, you can either:

### **Create a new role**

Click New Role.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FCzRZsFFDuuRuC3OfU0d7%2FScreenshot%202025-10-30%20at%2011.10.42.png?alt=media&amp;token=502812b8-75a0-457d-a2e1-c881c4b93588" alt="" width="70"><figcaption></figcaption></figure></div>

This will display the blank Role Builder page

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FA5A2Nr1o49tI0nsncLgb%2FScreenshot%202025-10-31%20at%2010.56.05.png?alt=media&amp;token=ba83d8d7-74a7-4e04-b8f0-f894dc64e995" alt=""><figcaption></figcaption></figure></div>

### **Edit an existing role**

Click Permissions beside the intended role.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FoITIkyO8NtBxAix6H4DX%2FScreenshot%202025-10-31%20at%2010.14.48.png?alt=media&amp;token=458c202e-ad32-45dd-aede-fe8cd6e62c46" alt="" width="69"><figcaption></figcaption></figure></div>

This will display the Role Builder page already populated with the data of that role

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2Fn15xxrZ1DXEhv2FJ0Kfc%2FScreenshot%202025-10-31%20at%2011.00.08.png?alt=media&amp;token=26254e8b-0191-48fb-99df-7dd710d6b3bf" alt=""><figcaption></figcaption></figure></div>

***

## **Fields Overview**

### **Role Name**

Enter the name for the role you are creating or updating.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2Fcg1EEMQHOnoy313t31GD%2FScreenshot%202025-10-31%20at%2013.00.10.png?alt=media&amp;token=b4c978ac-7f4e-4cfa-9258-c4882f628fdd" alt="" width="563"><figcaption></figcaption></figure></div>

Use clear and descriptive titles that reflect the scope of permissions (e.g., *Inventory Admin*, *Site User – Scaffold Management*).

### **Description**

Provide a short summary of what this role allows users to do.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2Fh5jaB8zkjlCoTmL9dQoc%2FScreenshot%202025-10-31%20at%2013.00.17.png?alt=media&amp;token=9d09b75e-f487-4ce0-be5c-0194fb5d5257" alt="" width="563"><figcaption></figcaption></figure></div>

This description appears in the Role List and helps identify the role’s purpose.

### **Adding Permissions to a Role**

Click the "**Click here**" button. This will open the **Permissions Selector**, which displays all available permissions in the system.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2Fss45k6tDJIIJRN5dN6h5%2FScreenshot%202025-10-31%20at%2013.00.24.png?alt=media&amp;token=3d879e3b-b398-4fc9-9318-4f7d75b5a39c" alt="" width="563"><figcaption></figcaption></figure></div>

From here, you can choose exactly which permissions the role will be granted access to.

{% hint style="info" %}
[Learn how to add permissions to a role](https://docs.cloudscaff.com/settings/user-management/add-or-update-permissions.md)
{% endhint %}

***

## **Example: Creating a New Role**

When adding a new role:

1. Enter the **Role Name.**
2. Add a **Description.**
3. Click **Set Role Permissions – Click Here** to open the list of permissions.
4. Select all applicable permissions for this role.
5. Review the name and permissions, then use **Create Role** when you intend to create the role.

> **Tip:** Check the new role in Available Roles before assigning it to a user.

***

## **Example: Editing an Existing Role**

When editing an existing role:

1. The **Role Name** and **Description** fields will prefill with the current values.
2. The permissions currently assigned to the role will be displayed as highlighted tags below the **Permissions** heading.
3. You can add or remove permissions by reopening the permissions list using the **Click Here** button.
4. Review the intended changes, then use **Save Role**.

> **Note:** Check an affected user's actual access after changing a role.

***

## **Understanding Permissions in a Role**

Each permission represents a specific capability or access area within Cloudscaff.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FIJBdT1ExivnZ2kBZe4ow%2FScreenshot%202025-10-31%20at%2013.18.16.png?alt=media&amp;token=9362294c-d13f-4d2f-a591-e2e9f3edb30d" alt=""><figcaption></figcaption></figure></div>

Permissions are displayed as labeled tags (e.g., *sites-requests-create*, *sites-returns-view*, *sites-transfers-release*).

These define what a user can do in the system once assigned to the role.

> **Example:**\
> The role *Site User – Inventory Management* includes permissions such as creating, viewing, and updating site inventory requests, transfers, and returns.

***

## **Saving Changes**

When you are done configuring or updating a role:

The new-role form shows Create Role.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FMOM5XQRm1eSFFAc6cspV%2FScreenshot%202025-10-31%20at%2014.11.06.png?alt=media&amp;token=f410a642-61fc-4b3e-bb24-818293c602e1" alt="" width="92"><figcaption></figcaption></figure></div>

The existing-role form shows Save Role.

<div align="left" data-with-frame="true"><figure><img src="https://3532476255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVJ0qURLvzCOxTGXEZIZ%2Fuploads%2FP4pY7f6dQCFlDzhp3MMb%2FScreenshot%202025-10-31%20at%2014.10.49.png?alt=media&amp;token=e4361677-a2dd-4574-bc72-7302e086a2cf" alt="" width="95"><figcaption></figcaption></figure></div>

After saving, reopen the role and check its name, description and permissions. Check the actual access of users assigned to that role.

> **Important:**\
> Users assigned to the modified role may need to refresh their session to load the updated permissions.

***

### **Best Practices**

* Always use consistent naming conventions (e.g., *Site User – Scaffold Management*).
* Keep descriptions clear to make role selection easier for administrators.
* Review role permissions regularly to maintain security and compliance.
* Avoid duplicating roles unless they serve different departments or access levels.
* Restrict permission access to only what is required for the user’s function.

***

### **Example Workflow**

1. Navigate to **Settings → User Profiles.**
2. Click **Select Role** under a user’s profile to open the Role Builder.
3. Choose New Role to inspect a blank form, or Permissions to inspect an existing role.
4. Fill in the **Role Name** and **Description** fields.
5. Click **Set Role Permissions – Click Here** to choose applicable permissions.
6. The forms use Create Role or Save Role; use them only in an authorized change workflow.

Before assigning a role, check that it appears with the intended permissions.
