# Principal users

## Principal users at a glance

A principal user is an administration record for the identity, access choices, approval limits,
authentication choice, and profile image used by a principal user in PAMS. The **Principal users**
surface uses one screen for a new record and for an existing record.

| If you need to… | Go to |
|---|---|
| Understand the fields and choices | [Understand the principal-user screen](#understand-the-principal-user-screen) |
| Enter identity, branch, role, approval, or authentication details | [Maintain identity and access details](#maintain-identity-and-access-details) |
| Open a new or existing record | [Find or open a principal user](#find-or-open-a-principal-user) |
| Check what changes for your access or record state | [Handle access and record variations](#handle-access-and-record-variations) |
| Save, leave, or resolve a message | [Save, leave, and handle problems](#save-leave-and-handle-problems) |
| Review broader user administration | [Users](doc:users-overview) |
| Administer roles | [Roles](doc:roles) |
| Administer teams | [Teams](doc:teams) |
| Review two-factor configuration | [2-factor Authentications](doc:configuration-2factor-authentications) |

## Before you start

Prerequisites

- Know whether you are creating a principal-user record or changing an existing one.
- Have the identity information and access choices ready before you select a save action.
- You need edit access for **Save** and **Save and Close** to be available after you make a change.
- The record and its credential information must be loaded before their fields can appear.
- The form must pass its validation before it can save.

Unsaved changes affect the close action. When you have edit access and the current values differ from
the saved values, leaving the page opens a confirmation choice instead of leaving immediately.

> Note: Use the required markers beside the fields as your check before selecting a save action.

## Find or open a principal user

Use a principal-user record to maintain one person's identity and access settings.

Steps

1. Open the security users area.
2. Choose the route that matches your task:

   | If you need to… | Choose |
   |---|---|
   | Start a new record | Select the option to create a new principal user. |
   | Change an existing record | Select the principal user in the users list. |
   | Change a profile image | Select the principal user in the users list. |

3. Confirm that the page heading identifies the principal-user record before entering values.

![Check the route and the identity fields before entering a new principal user](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/0d46bb3ab739e619d655f36a47e15abc.png)

**Result:** The principal-user screen is open at the new-record route or at the existing record you
selected.

## Understand the principal-user screen

The screen groups identity information, access choices, approval settings, two-factor authentication,
and profile-image controls. The new-record screen shows **Email**, **Title**, the person's given name,
**Middle Name**, **Last Name**, **Display Name**, and **Mobile**.

The following fields are required on the new-record screen:

| Field | Type | Required marker |
|---|---|---|
| **Email** | Text | Yes |
| Given name | Text | Yes |
| **Last Name** | Text | Yes |
| **Display Name** | Text | Yes |
| **Mobile** | Text | Yes |

These fields are also present but are not marked required on the new-record screen:

| Field | Type | Details |
|---|---|---|
| **Title** | Text | Optional entry |
| **Middle Name** | Text | Optional entry |

The access area contains the **Allowed Branches** and **User Roles** groups. Their checkbox entries
come from the available branch and role data. The new-record screen showed five branch entries and
nineteen role entries. **Accessible account** appears as a readout on this screen rather than as a
visible selectable control.

![Review the branch checkboxes in the **Allowed Branches** group](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4d8df0987ff42c37d40541f113796879.png)

![Review the role checkboxes in the **User Roles** group](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4d8df0987ff42c37d40541f113796879.png)

The approval area contains three approval-limit groups. Each group has an **Up to** amount and an
**Unlimited** choice. The groups cover sales, purchasing, and invoicing. The amount uses the format
`#,##0.00` and cannot be below `0`.

The **Mobile** field accepts a maximum of 20 characters.

The authentication area offers **Apply 2-factor Authentication With This User** with the choices
**No** and **Yes**. Profile-image actions include an upload action and **Delete**. The screen has no
record list.

![Identify the required identity fields and the **Email** field](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1fd1b477727191a1bf61bac414f342a7.png)

## Maintain identity and access details

A principal-user record combines identity information with the branches, roles, approval limits, and
authentication choice that apply to that person.

Prerequisites

- The principal-user screen is open.
- The identity information is ready.
- The branches and roles that apply to the record are known.

Steps

1. Enter the address in **Email**.
2. Enter the person's given name in **First Name**.

![Check the given-name field before continuing to the family name](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1fd1b477727191a1bf61bac414f342a7.png)
3. Enter the person's family name in **Last Name**.
4. Enter the name used to identify the record in **Display Name**.
5. Enter the person's mobile number in **Mobile**.
6. Enter the person's title in **Title** when that detail applies.
7. Enter the person's middle name in **Middle Name** when that detail applies.
8. Select the checkboxes for the branches the principal user may access.
9. Select the checkboxes for the roles the principal user needs.
10. Set each approval limit in its **Up to** amount when the corresponding approval must be capped.
11. Select **Unlimited** for an approval area that has no amount cap.
12. Choose the required authentication setting:

    | If you need to… | Select |
    |---|---|
    | Leave two-factor authentication off | **No** |
    | Apply two-factor authentication | **Yes** |

13. Choose an image in the image dialog.
14. Use the upload action in the image dialog.
15. Select **Delete** in the image menu to remove the current profile image.

![Review the account readout and access groups before choosing branches and roles](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1fd1b477727191a1bf61bac414f342a7.png)

**Result:** The identity, access, approval, authentication, and profile-image values are set on the
screen and are ready for a save action.

## Handle access and record variations

The controls available to you change with your edit access, whether the record is new or existing,
and whether an approval area is unlimited.

| Situation | What you can use |
|---|---|
| You can edit and have changed a value | **Save** and **Save and Close** are available in the header. |
| You can edit and select the close control at the top-right of the screen with unsaved changes | A confirmation choice opens before you leave. |
| You cannot edit | The close control at the top-right of the screen leaves the page directly. |
| The record is new | The record fields appear after the new record loads. |
| **Unlimited** is selected for an approval area | The amount control for that approval area is replaced by an unlimited value. |
| **Unlimited** is not selected | The approval amount is shown and must be at least `0`. |

The **User Roles** and **Branches** panels do not contain separate fields; use the inline checkbox
groups in the user-information area. The username field and re-send activation-mail button are not
part of this screen.

## Save, leave, and handle problems

Saving commits the values after the form passes validation. Leaving with unsaved changes uses the
page's confirmation choices.

Prerequisites

- The fields you want to keep are completed.
- You have edit access for the save actions.
- The validation group passes before saving.

Steps

1. Select **Save** in the header to save while staying on the screen.
2. Select **Save and Close** in the header to save and leave the screen.
3. Select the close control at the top-right of the screen when you want to leave without starting
   a save.
4. When the unsaved-change prompt opens, choose the action that matches your desired outcome:

   | Desired outcome | Select |
   |---|---|
   | Leave without keeping the changes | **Don't Save** |
   | Keep the changes and leave | **Save** |
   | Stay on the screen | **Cancel** |

5. When validation stops the save, correct the field identified by the message.
6. Select the save action again.

![Check the header save actions before committing changes](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1fd1b477727191a1bf61bac414f342a7.png)

![Check the **Save and Close** action in the header](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1fd1b477727191a1bf61bac414f342a7.png)

| What appears | What to do |
|---|---|
| `This Field Is Required` | Enter a value in the field identified by the message. |
| `Just '_'‘-''.' And '&' Characters Accepted` | Remove characters that the field does not accept. |
| `Email is invalid` | Correct the address in **Email**. |
| `Are you sure you want to delete this item?` | Confirm that the current profile image is the one you want to remove before selecting **Delete**. |
| `Photo Deleted Successfully` | The profile image was removed. |
| `Server Error` | Check the screen and retry the action when the service is available. |
| `Error: This Email or User Name Already Exists` | Use a different email or user name. |
| `Error: Server Error` | Check the screen and retry the save when the service is available. |
| `Data saved Successfully .. An E-Mail was sent to this User` | Continue from the activation dialog. |
| `New user created` | Read the activation information in the dialog. |
| `A activation mail with instruction sent to user [record email]` | The activation message identifies the address receiving the message. |
| `to activate his account Whenever user activate his account You’ll be notified by mail` | Follow the activation instructions for the new account. |
| `Do you want to save your changes?` | Choose `Don't Save`, `Save`, or `Cancel` in the unsaved-change prompt. |
| `Do you want to save your changes?` | Choose the required unsaved-change action in the prompt. |
| `No` | Choose `No` in the authentication control when that is the required setting. |
| `Yes` | Choose `Yes` in the authentication control when that is the required setting. |
| `Ok` | Close the activation alert. |

The phrases `Import instructions and file-size notices` belong to import workflows in the shared
popup. `Subscription-upgrade content` belongs to the subscription-upgrade workflow.

**Result:** The screen either remains open with the saved values, leaves after **Save and Close**,
or presents the message that tells you which correction or confirmation is needed.

## What comes next

After you finish the principal-user administration task, continue from the result that appears on
screen. A successful new-user save can open the activation information; a leave action returns you
to the surrounding security area.

Use these related pages for the next administration concern:

- [Users](doc:users-overview) for the user list and existing-record entry point.
- [Roles](doc:roles) for broader role administration.
- [Teams](doc:teams) for team administration.
- [2-factor Authentications](doc:configuration-2factor-authentications) for related authentication configuration.
- [General error messages](doc:general-error-messages) for common application message handling.

**Result:** You know which related administration page to open after the current principal-user
screen.