# Roles

Roles control which areas and actions are available to people in your company.
Use this page to find the role list, create a role, or maintain an existing role's
permission matrix, the grid of pages and access choices for that role.

## Roles

The Roles area contains a list of roles and separate routes for creating and editing a
role.

| If you need to… | Go to |
|---|---|
| Find a role or start role administration | [Find and open a role](#find-and-open-a-role) |
| Understand the list and permission matrix | [Understand the role surfaces](#understand-the-role-surfaces) |
| Create or change permissions | [Create or maintain role permissions](#create-or-maintain-role-permissions) |
| Choose the correct branch for a system or inactive role | [Handle role conditions](#handle-role-conditions) |
| Respond to a validation or service message | [Resolve role problems](#resolve-role-problems) |
| Continue after saving | [After saving a role](#after-saving-a-role) |
| Administer users who receive roles | [Users overview](doc:users-overview) |
| Create a user and assign access | [Create user](doc:create-user) |
| Administer principal users | [Principal users](doc:principal-users) |
| Administer teams | [Teams](doc:teams) |

## Before you start

Prerequisites

- You are signed in. The three role routes use the application sign-in guard.
- You have the permission needed for the action you are about to take. The list checks
  separate permissions for creating, editing, deleting, importing, and exporting, and the
  record screen checks whether editing is allowed.
- The role is saved before you use controls that require an existing role. The
  **Last Modifications** area is only available for an existing role that is not a system
  role.
- You know whether the role is a system role. A system role disables the role name and the
  permission checkboxes.
- Your subscription permits another role when you select **New**. If the role limit has been
  reached, the list uses the limit branch instead of opening the new-role route.

The list and record screens also use a leave-page guard. If you leave a record with unsaved
changes, the application can interrupt the departure before the next route opens.

With these conditions in place, continue to [Find and open a role](#find-and-open-a-role).

## Find and open a role

A role is a named set of access choices shown in the role list and maintained on its record
surface.

Prerequisites

- You are signed in and have reached the Security area.
- You know whether you want to open the list, start a new role, or open an existing role.

Steps

1. Choose the route that matches your task.

   | If you need to… | Choose |
   |---|---|
   | View the role list | Select **Roles** in Security. |
   | Create a role | Select **New** on the role list. |
   | Edit an existing role | Select the edit action on the role's row. |

![The Roles list with its role rows and list controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4cfef0d96c94de79dd1ccb6fe1c6a7dd.png)

**Result:** The list, the new-role form, or the existing-role form is on screen.

Continue to [Understand the role surfaces](#understand-the-role-surfaces) to identify the
list headers and permission matrix.

## Understand the role surfaces

The role list is a searchable administration surface, and the role record combines a name
with a matrix of pages and access choices.

The active list displayed **Role Name** and **Active**, with 22 role rows. The headers come
from the list layout in use, so work from the headers visible in your list.

The new-role surface displayed the permission columns listed below.

| Area | What you use it for |
|---|---|
| Permission columns | All, Sections, View, **New**, **Edit**, **Delete**, **Import**, **Export**, Enable Editing, Send Email, Print, and Validate. |
| **Role Name** | Enter the role name. The field is required and also checks the permitted character pattern. |
| **All** | Select or clear the permission choices across the matrix. |
| **Sections** | Identify the page or section represented by each matrix row. |
| Access columns | Select a permission for a page, or use an access-type selection for the column. |
| Page rows | Expand a row when its child pages are available. |
| List controls | Use the configurable grid, filters, grouping, export, and row opening features when they are available in your layout. |
| **Copy new role** | Copy an existing role when editing is allowed. |
| **Last Modifications** | Open the history area for an existing non-system role. |

The role history area has no action-types filter.

The history area includes Action users and Fields filters. The **Comments** tab is
commented out and is not available.

![The new-role permission matrix and its access columns](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/8e9e7d11307df318fac29bc0cdea34ab.png)

Continue to [Create or maintain role permissions](#create-or-maintain-role-permissions) when
you are ready to enter a name or change access choices.

## Create or maintain role permissions

A role permission record gives a named role access choices for the pages and actions shown in
the matrix.

### Create a role

Prerequisites

- You are on the new-role screen.
- You know the name to give the role and the access choices it needs.

Steps

1. Select the **Role Name** field.

2. Enter the role name.

3. Select the required choices in the permission matrix. Use **All** for the complete matrix,
   an access column's selection for a complete access type, or an individual page checkbox
   for a narrower choice.

4. Select the save action that matches where you want to continue.

   | If you need to… | Choose |
   |---|---|
   | Keep working on the role record | **Save** |
   | Leave the role record after saving | **Save and Close** |

If the name is empty, the application displays `This Field Is Required`. If the name contains
an unsupported character, it displays `Just '_'‘-''.' And '&' Characters Accepted`.

**Result:** After a successful create, the application displays `Data saved Successfully` and
opens the role's edit screen when you use **Save**; **Save and Close** leaves the role screen.

![The role-name field on the new-role form](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9c6fc45e5d3905d23441083ed8d43821.png)

### Maintain an existing role

Prerequisites

- You have opened an existing role from the role list.
- The role is not a system role when you need to change its name or permission choices.

Steps

1. Select **Copy new role** when you need a new role based on the existing role.

2. Select the page or access checkbox you want to change.

3. Select **All** when the whole matrix needs the same permission change.

4. Select **Save** to remain on the role record, or select **Save and Close** to leave it.

**Result:** After a successful update with **Save**, the application displays `Data saved Successfully`
and refreshes the history area; **Save and Close** leaves the role screen.

![The new-role save controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9c6fc45e5d3905d23441083ed8d43821.png)

### Export the role list

Use the role-list export when you need a file containing the selected format.

Prerequisites

- You are on the role list.
- The export control is available in your list layout.

Steps

1. Select **Export**.

2. Select the format in the export popup.

3. Select **Export** in the popup.

**Result:** The selected role-list format is exported.

Continue to [Handle role conditions](#handle-role-conditions) when the role is a system role,
inactive, or subject to an authorization or subscription branch.

## Handle role conditions

Role administration branches according to whether you are creating, editing, deleting an
inactive role, or viewing a system role.

| Situation | What the screen does |
|---|---|
| You may create roles and the limit permits another role | **New** opens the new-role route. |
| You may create roles but the limit has been reached | **New** opens the role-limit branch instead. |
| You may edit a role | The edit action and save controls are available according to the record conditions. |
| The row is inactive and deletion is allowed | The row has a delete menu with **Cancel** and **Delete**. |
| The role is a system role | The role name and permission checkboxes are disabled. |
| The role is saved and is not a system role | **Last Modifications** is available in the record surface. |

### Delete an inactive role

Prerequisites

- The role row is inactive.
- You have permission to delete roles.

Steps

1. Open the row's delete menu.

2. Read the confirmation `Are you sure you want to delete?`.

3. Select **Cancel** to close the menu without deleting the role.

4. Select **Delete** to delete the inactive role.

**Result:** The role is removed after a successful delete, and the application displays
`Data Deleted Successfully`.

## Resolve role problems

Use the exact message on screen to decide whether to correct the role name, review the role
state, or retry the operation with the applicable permission.

| Message | What to do |
|---|---|
| `This Field Is Required` | Enter a value in **Role Name**. |
| `Just '_'‘-''.' And '&' Characters Accepted` | Correct the role name so it uses the accepted characters. |
| `This Role Name Already Exists` | Choose a different role name. |
| `NO Data to Export` | Confirm that the list contains data before exporting. |
| `Are you sure you want to delete?` | Select **Cancel** if you do not intend to delete the inactive role. |
| `Data Deleted Successfully` | The delete request completed successfully. |
| `Error: Please Refresh the Page and Try Again.` | Refresh the page and try the role operation again. |
| `A duplicate occurred with the existing data` | Review the role name and try again. |
| `Action not allowed` | Check that your account has the required role permission. |
| `This record is related to saved data and cannot be deleted` | Keep the role and review the related saved data. |
| `You’ve reached the maximum storage limit` | Resolve the storage-limit condition before retrying. |
| `Some products are not available in stock` | Review stock availability before retrying. |
| `An error occurred while processing your request` | Retry the operation or ask an administrator to review the failure. |

When a delete request fails, the application selects an error message from the returned error.
When an update request fails, the application displays the text returned for that error.

After resolving the message, continue to [After saving a role](#after-saving-a-role) for the
next administration task.

## After saving a role

After role administration, continue from the route that matches the work you need to do next.

| If you need to… | Continue with |
|---|---|
| Review users who receive the role | [Users overview](doc:users-overview) |
| Create a user who needs the role | [Create user](doc:create-user) |
| Review principal-user access | [Principal users](doc:principal-users) |
| Review team administration | [Teams](doc:teams) |
| Review two-factor security settings | [Two-factor authentication](doc:configuration-2factor-authentications) |

After a successful new-role save, the application opens the role's edit screen. After a
successful update with **Save**, it displays `Data saved Successfully` and refreshes the history
area; **Save and Close** leaves the role screen.

The role record's audit entry point is **Last Modifications** when the role is saved and is
not a system role.

**Result:** The role is either open for further editing or you are on the related security page
for the next administration task.