# Roles

## Roles

A role defines which parts of PAMS a person can access through a hierarchical
**Sections** matrix. Use roles to organise access permissions rather than to maintain
business records.

| If you need to… | Go to |
| --- | --- |
| Check what the role list offers | [Understand the role surfaces](#understand-the-role-surfaces) |
| Open a role or start a new one | [Find and open a role](#find-and-open-a-role) |
| Set a role's access permissions | [Create or maintain role permissions](#create-or-maintain-role-permissions) |
| Continue after saving | [After saving a role](#after-saving-a-role) |
| Resolve an unavailable action or missing history | [Resolve role problems](#resolve-role-problems) |

## Before you start

Role controls depend on both your permissions and the record you opened. The list shows
**New** only when role creation is allowed. The edit link requires edit permission, and
**Delete** requires delete permission and an inactive row. A system role is a role whose
name and permission matrix are disabled and whose record actions are hidden.

## Find and open a role

Use the Roles list to inspect role records, open a permitted record, start a new role,
export the list, or remove an inactive role.

**Prerequisites**

- You have access to security administration.
- You know whether the role you want to remove is inactive.

**Steps**

1. Open the Roles list.
2. Choose the action that matches your task.

   | If you need to… | Action |
   | --- | --- |
   | Start a role | Select **New**. |
   | Open a permitted existing role | Select its row. |
   | Open a permitted existing role through its edit link | Select the edit link in the role's row. |
   | Prepare list data | Select **Export**. |
   | Remove an inactive role | Select **Delete** on the inactive row. |
   | Close the export choices | Select **Cancel**. |

![The Roles list with its available actions and visible rows](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/537eba0de9e046f9a78c5da3e0838415.png)

![The new-role screen after selecting New](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c2afcfebbe9e6e96a1bcd0c3693430e6.png)

![The export choices with Export and Cancel](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/fe0ce15aba8e2dd9acda33cdce460c79.png)

**Result:** You have the selected role screen, the new-role screen, the export choices, the
or the deletion confirmation on screen.

Next, review the role surfaces before creating or maintaining permissions.

### Confirm deletion of an inactive role

When **Delete** opens the confirmation for an inactive role, confirm the deletion only for
the intended record.

**Prerequisites**

- The deletion confirmation is open.
- The inactive role is the intended record.

**Steps**

1. Read `Are you sure you want to delete?`.
2. Confirm the deletion choice.

**Result:** The application shows `Data Deleted Successfully`.

## Understand the role surfaces

The Roles area has a list surface for finding records and a role surface for identifying a
role and changing its access. The role surface also provides saved history for eligible
roles.

| Surface | What it is for | What you can identify |
| --- | --- | --- |
| Role list | Locate and act on role records | The list shows **Role Name** and **Active** columns |
| List tools | Adjust or prepare the list | **Refresh**, **Table Layout**, **Settings**, filters, grouping, and export choices |
| Role identity | Name the role | **Role Name**; the value is disabled for a system role |
| Permission matrix | Set access by section and access type | **All**, the hierarchical **Sections** tree, and access-type choices |
| Permission groups | Move between permission areas | **Configuration**, **Security**, and **Other** |
| Tree tools | Find or change the matrix view | **Expand all** and **Collapse all** |
| History | Review saved changes | After saving a non-system role, select **Last Modifications** |
| Supporting popup | Complete list actions | The shared popup used by export and confirmation surfaces |

The new-role access matrix shows these columns:

| Matrix columns |
| --- |
| **Modules** |
| **View** |
| **New** |
| **Edit** |
| **Delete** |
| **Import** |
| **Export** |
| **Enable Editing** |
| **Print** |
| **Validate** |

Its visible module names include `Dashboard`, `Tasks`, `Activities`, `Sales`, `Projects`,
`Accounts`, `Contacts`, `Invoices`, `Payments`, `Letters of guarantee`, `Products`,
`Project management`, `Purchasing`, `Warehouse`, `Reports`, `Payables`, `job profitability`,
and `Tickets`.

The list's data columns come from the saved layout, so work from the headers visible in your
list. The list grid appears when a saved layout is available. Filters and grouping are part
of the configurable list surface.

Use these surfaces to create a role or maintain an existing role.

## Create or maintain role permissions

A role permission record combines a role name with access choices in the hierarchical
**Sections** matrix. Create a role when you need a new permission set; maintain a saved
non-system role when you need to change or copy an existing set.

### Create a role

When **New** opens the new-role screen, complete the role.

**Prerequisites**

- The new-role screen is open.
- You know the name that identifies the permission set.

**Steps**

1. In **Role Name**, enter the role name.
2. Select **Configuration**, **Security**, or **Other** to open the corresponding
   permission tree.
3. Select **Expand all** when you need to see the hierarchy.
4. Select **Collapse all** when you need to reduce the hierarchy.
5. Use **All** to select all applicable permissions in the displayed matrix.
6. Select the applicable access types for the required **Sections**.
7. Select **Save** to validate and save the role while staying on the record.
8. Select **Save and Close** to validate, save, and leave the page.

If **Role Name** is empty, the form shows `This Field Is Required`. If its value contains
an unsupported character, the form shows `Just '_'‘-''.' And '&' Characters Accepted`.

**Result:** The saved role remains on screen after **Save**, or the application leaves the
page after **Save and Close**. A successful save shows `Data saved Successfully`.

### Maintain an existing role

For a saved non-system role with a permitted edit surface, copy the role or change its
permissions. System roles have their identity, matrix, and record actions restricted by the
screen.

**Prerequisites**

- A saved non-system role is open.
- The role has a permitted edit surface.

**Steps**

1. Select **Copy new role** to copy the existing role into a new-role flow.
2. In the new-role flow, change **Role Name** when the copy needs a different name.
3. Select the permission tree to maintain.

   | If you need to maintain… | Select |
   | --- | --- |
   | Configuration permissions | **Configuration** |
   | Security permissions | **Security** |
   | Other permissions | **Other** |

4. Adjust the applicable **Sections** and access-type selections.
5. Choose the save action that matches your next step.

   | If you need to… | Select |
   | --- | --- |
   | Save without leaving the record | **Save** |
   | Save and leave the record | **Save and Close** |
   | Review saved history | **Last Modifications** after saving a non-system role |

**Result:** The maintained role is saved, or the copied permissions are available in a new
role record. A successful save shows `Data saved Successfully`.

To prepare list data, use the export procedure.

### Export the role list

After opening the Roles list, use the export popup to prepare the list data.

**Prerequisites**

- The Roles list is open.
- The list contains data to export.

**Steps**

1. Select **Export** on the Roles list.
2. Choose the required filter or grouping settings in the export surface.
3. Choose the export outcome.

   | If you need to… | Select |
   | --- | --- |
   | Start the export | **Export** |
   | Close the choices without exporting | **Cancel** |

When the list has no exportable data, the application shows `NO Data to Export`.

**Result:** The export starts, the export choices close without exporting, or the empty-list
message remains on screen.

## Resolve role problems

Use the condition that matches what you see rather than looking for a control on a different
role surface.

| What you see | What it means | What to do |
| --- | --- | --- |
| **New** is unavailable | Creation is controlled by the list permission and subscription limit | Confirm that role creation is allowed, then return to the Roles list |
| **Delete** is unavailable on a row | The row is not inactive, or delete permission is unavailable | Open an inactive row or ask an administrator to review the permission |
| **Role Name** or the matrix is disabled | The role is a system role | Use a non-system role for editable permissions |
| Record actions are hidden | The opened role is a system role | Return to the Roles list and open a permitted non-system role |
| **Last Modifications** is missing | The role is new or a system role | Save a non-system role, then reopen its history |
| The list grid is missing | No saved list layout is available | Ask an administrator to review the list layout |
| Saving shows `This Role Name Already Exists` | The role name is already in use | Change **Role Name**, then select **Save** again |
| A required-name validation appears | **Role Name** is empty | Enter a value in **Role Name** |
| The name validation appears as `Just '_'‘-''.' And '&' Characters Accepted` | The name contains a character the form does not accept | Replace the unsupported character in **Role Name** |
| Delete asks `Are you sure you want to delete?` | The application is waiting for the deletion choice | Confirm the deletion only when the inactive role is the intended record; otherwise select **Cancel** |

### Return to the Roles list after an empty export

When the export shows `NO Data to Export`, return to the Roles list.

**Prerequisites**

- `NO Data to Export` is on screen.

**Steps**

1. Return to the Roles list.

**Result:** The Roles list is on screen.

### Select data before retrying an export

After returning to the Roles list from an empty export, select data before retrying.

**Prerequisites**

- The Roles list is open.

**Steps**

1. Select data in the Roles list.

**Result:** The list has data ready for export.

## After saving a role

After a non-system role is saved, review its history with **Last Modifications** or return
to the Roles list to find the record and continue working with its permissions.
