# Principal users

A principal user is a person whose sign-in identity, account access, branches, roles,
approval limits, and two-factor choice are maintained on one administration form.
Use this page to open or start a record, maintain those details, and respond to
validation or server messages.

## Principal users at a glance

The same details screen opens for a new record and an existing record.

| If you need to… | Go to |
|---|---|
| Open an existing principal-user record | [Find or open a principal user](#find-or-open-a-principal-user) |
| Start a principal-user record | [Find or open a principal user](#find-or-open-a-principal-user) |
| Review the fields and access areas | [Understand the principal-user screen](#understand-the-principal-user-screen) |
| Change identity or access details | [Maintain identity and access details](#maintain-identity-and-access-details) |
| Resolve a validation or server response | [Troubleshooting validation and server messages](#troubleshooting-validation-and-server-messages) |
| Review the principal-user list | [Users overview](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/users-overview) |
| Create a new user record through the dedicated procedure | [Create a user](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/create-user) |
| Maintain reusable roles | [Roles](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/roles) |
| Maintain teams | [Teams](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/teams) |

## Before you start

The form opens around a person record and its credential data. The following
conditions determine which fields and actions you can use.

| Check | What it affects |
|---|---|
| The person record has loaded | The form and its controls appear. |
| Credential details have loaded | **Email**, **Mobile**, and the two-factor choice can appear. |
| You are allowed to edit | **Save** and **Save and Close** appear. |
| The record is read-only | **Accessible account** and account-dependent controls are read-only. |
| The person has an ID | **Active user** becomes available; it is disabled without an ID. |
| You are ready to leave the page | The page protects unsaved changes when you leave. |

When these checks are complete, continue to [Find or open a principal user](#find-or-open-a-principal-user).

## Find or open a principal user

Use this procedure to reach the form. Continue to [Understand the principal-user
screen](#understand-the-principal-user-screen) when it opens.

**Prerequisites**

- You are signed in and have reached the principal-user administration area.

**Steps**

1. Open [Users overview](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/users-overview) to reach the user administration list.
2. Choose the route that matches your task.

   | If you need to… | Select or follow |
   |---|---|
   | Review an existing record | Open the principal-user record. |
   | Start a new record | Follow [Create a user](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/create-user). |

![The principal-user form with identity fields and Save actions](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f13f53445105c4993f689d321bb87031.png)

**Result:** The principal-user details form is open for an existing record or a new
user record. Continue to [Understand the principal-user screen](#understand-the-principal-user-screen).

## Understand the principal-user screen

The form groups the person's identity, account access, branch and role choices,
approval limits, two-factor choice, and photo actions.

| Screen area | What to look for |
|---|---|
| Credential and account | **Email** and **Accessible account** identify the sign-in contact and account choice. |
| Identity | **Active user**, **Title**, **First Name**, **Middle Name**, **Last Name**, **Display Name**, and **Mobile** hold the person's account identity. |
| Branches and roles | **Allowed Branches** and **User Roles** are repeated checkbox lists. |
| Permissions | **Up to** and **Unlimited** appear for Sales, Purchasing, and Invoicing. |
| Two-factor area | **Apply 2-factor Authentication With This User** offers **No** and **Yes**. |

![The email and identity fields on the principal-user form](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/042bbc05563221a0ccd9b3c5b0a14bc2.png)

![The branch area and its repeated choices](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/042bbc05563221a0ccd9b3c5b0a14bc2.png)

Continue to [Maintain identity and access details](#maintain-identity-and-access-details)
when you are ready to enter or change values.

## Maintain identity and access details

Use this procedure after the form opens. Continue to [Handle access and record
variations](#handle-access-and-record-variations) when you need to review limits,
two-factor settings, or photo actions.

**Prerequisites**

- The principal-user form is open.
- Credential data is present when you need to edit **Email** or **Mobile**.
- You have edit permission when you need to save changes.

**Steps**

1. Review **Email**.
2. Enter a valid address in **Email** when you need to change the sign-in contact.
3. Enter the person's given name in **First Name**.
4. Enter the person's family name in **Last Name**.
5. Enter the person's displayed name in **Display Name**.
6. Enter the person's phone number in **Mobile**.
7. Optionally enter a value in **Title** or **Middle Name**.
8. In **Allowed Branches**, select the applicable branch checkboxes.
9. In **User Roles**, select the applicable role checkboxes.
10. Review **Active user** and leave it disabled when the person has no identifier.
11. Review **Accessible account**. When the record is read-only, the control is read-only.

![The required First Name field on the new-user form](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ba07038774b6fd5263f57da9e6436c59.png)

![The required Mobile field on the new-user form](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ba07038774b6fd5263f57da9e6436c59.png)

**Result:** The form contains the identity and access details you reviewed or changed. Required
markers appear on **Email**, **First Name**, **Last Name**, **Display Name**, and
**Mobile**. **Title** and **Middle Name** have no required marker.

## Handle access and record variations

After maintaining identity and access details, use the applicable option below before
you save.

| If you see… | Use this choice or action |
|---|---|
| An amount under Sales, Purchasing, or Invoicing | Review or enter the amount in **Up to**. |
| A disabled infinity display | Leave the amount unchanged; the matching unlimited value is active. |
| The two-factor choice | Select **No** or **Yes** under **Apply 2-factor Authentication With This User**. |
| A photo-delete dropdown | Select **Delete** to start deletion, or **Cancel** to close the dropdown. |
| The avatar upload area | Select **Upload** to open it. |

**Prerequisites**

- The principal-user form is open.
- The relevant limit, two-factor, or photo area is visible.

**Steps**

1. Review the applicable limit under **Up to** when an amount is shown.
2. Select **No** or **Yes** under **Apply 2-factor Authentication With This User**.
3. Choose the applicable photo action.

   | If you want to… | Select |
   |---|---|
   | Open the avatar upload area | **Upload** |
   | Begin the photo-delete branch | **Delete** |
   | Close the photo-delete dropdown without continuing | **Cancel** |

![The permissions and role choices on the principal-user form](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/042bbc05563221a0ccd9b3c5b0a14bc2.png)

**Result:** The form shows the applicable amount or unlimited display, the selected
two-factor option when visible, or the photo action area you opened. Continue to
[Save, leave, and handle problems](#save-leave-and-handle-problems).

## Save, leave, and handle problems

After you review the applicable variations, save the form or leave it. **Save** and
**Save and Close** appear only when editing is allowed and are disabled when the form
detects no changes.

**Prerequisites**

- You have completed the required fields.
- You have edit permission.

**Steps**

1. Choose the save outcome that matches your task.

   | If you want to… | Select |
   |---|---|
   | Run the save flow and remain on the form | **Save** |
   | Run the save-and-leave flow | **Save and Close** |

2. In the leave-protection prompt, choose the option that keeps your changes or the option
   that leaves the form.

![The Save and Save and Close actions on the new-user form](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ba07038774b6fd5263f57da9e6436c59.png)

**Result:** You remain on the form after **Save**, or the save-and-leave flow runs
after **Save and Close**. If a message appears, continue to [Troubleshooting validation
and server messages](#troubleshooting-validation-and-server-messages).

### Troubleshooting validation and server messages

Use the message to identify the correction or outcome.

| Message | Action or meaning |
|---|---|
| `This Field Is Required` | Complete the field marked as required. |
| `Email is invalid` | Correct the value in **Email** before saving. |
| `Just '_'‘-''.' And '&' Characters Accepted` | Remove unsupported characters from the name value. |
| `Are you sure you want to delete this item?` | Confirm the photo deletion or cancel the delete action. |
| `Photo Deleted Successfully` | The photo-delete flow completed successfully. |
| `Server Error` | The photo-delete operation returned a server error. |
| `Data saved Successfully .. An E-Mail was sent to this User` | The new-user save branch completed and sent an email to the user. |
| `Error: This Email or User Name Already Exists` | Use an email or user name that is not already in use. |
| `Error: Server Error` | The save operation returned a server error. |

After correcting the value or reviewing the response, continue to [What comes next](#what-comes-next).

## What comes next

After saving or reviewing the principal-user form, continue with the administration
task that follows.

| Next task | Page |
|---|---|
| Find a principal user in the list | [Users overview](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/users-overview) |
| Create a user record | [Create a user](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/create-user) |
| Maintain reusable roles | [Roles](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/roles) |
| Maintain teams | [Teams](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/teams) |
