# Units

## What Units are for

A unit is a reusable value attached to a sales item. Maintain it in the **Sales**
configuration area before using it in sales-item work.

| If you need to… | Go to |
|---|---|
| Check access and prepare a unit name | [Before you start](#before-you-start) |
| Open the list or an existing row | [Find the Units list](#find-the-units-list) |
| Identify the visible field and shared controls | [Understand the Units list](#understand-the-units-list) |
| Choose the maintenance action | [Add, edit, and remove a unit](#add-edit-and-remove-a-unit) |
| Add a new value | [Add a unit](#add-a-unit) |
| Change an existing value | [Edit a unit](#edit-a-unit) |
| Remove an existing value | [Remove a unit](#remove-a-unit) |
| Leave an open form | [Cancel an open unit form](#cancel-an-open-unit-form) |
| Understand permission and list differences | [Handle access and list variations](#handle-access-and-list-variations) |
| Correct a blocked maintenance action | [When maintenance does not work](#when-maintenance-does-not-work) |
| Continue to sales-item work | [Use the units in sales items](#use-the-units-in-sales-items) |

![Units list with the Name column and the available list controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4987b9255c5c4960a602ee4e145a1c05.png)

## Before you start

The Units page is an authenticated configuration page. Before maintaining a unit, have
the unit name that you want to add or change and confirm that your subscription and
permissions expose the required actions.

| Check | What applies | What it changes |
|---|---|---|
| Sign-in | You have signed in. | A signed-in session is required to open the page. |
| Subscription | Your subscription includes the required configuration. | The Units list and its controls are available. |
| New access | **New** is visible. | You can open a new-item form. |
| Edit access | The row edit action is visible. | You can change an existing unit. |
| Delete access | The row delete action is visible. | You can start the deletion flow. |
| Import access | The shared import action is visible. | You can open the import flow. |
| Export access | The shared export action is visible. | You can open the export choices. |
| Required information | **Name** is required. | A unit cannot be saved without a value in **Name**. |

Use the saved list to add a value that is not present or edit an existing value.

## Find the Units list

The Units list is the Sales configuration page for units.

In the configuration area, open **Sales**, then **Units**. The page title is **Units**
under **Sales**. The list displays one column, **Name**.

To work with an existing value, select its row in the **Name** column. The available row
action depends on your permissions.

![The Units list under Sales configuration](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4987b9255c5c4960a602ee4e145a1c05.png)

## Understand the Units list

The Units list stores one visible value for each sales item unit: **Name**. The list
showed 12 rows and displayed **Name** as its only column.

| Field or control | Where it appears | What to use it for |
|---|---|---|
| **Name** | List and new/edit form | Read or enter the unit name; the field is required. |
| Hidden system fields | Hidden from the list and form | They are not editable Units fields. |
| **New** | Units list | Open a new-item form when new entry is available. |
| **Refresh** | Units list | Refresh the visible list. |
| **Settings** | Units list | Open the shared list settings. |

Use the column headers shown in the list. This list showed only **Name**. Edit, delete,
import, and export actions vary with permissions and may not appear in every account.

## Add, edit, and remove a unit

Choose the maintenance action that matches the row's condition.

| If you need to… | Select or use | Result |
|---|---|---|
| Create a value that is not in the list | **New**, then **Name**, then the save action | A successful new save appends the new row to the list. |
| Correct an existing value | The existing row, then **Name**, then the save action | A successful edit replaces the matching row and closes the popup. |
| Remove an existing value | **Delete**, then confirm the deletion | A successful deletion removes the row. |

After a new item is saved, the list receives the new row. After an edit is saved, the
matching row is replaced and the popup closes. A deletion can be refused when related
saved data uses the unit or when it would remove the last remaining row.

### Add a unit

Add a unit when its value is not already in the Units list.

**Prerequisites**

- You are signed in and can see **New**.
- You know the unit name to enter.

**Steps**

1. In the Units list, select **New**.
2. In the new-item popup, enter the value in **Name**.
3. Select the popup save action labelled **OK**.

4. If the form rejects the value, correct **Name** according to the message shown:

   | Message | Correction |
   |---|---|
   | `Name is required` | Enter a value in **Name**. |
   | `Just '_' '-' And '.' Characters Accepted` | Use only the characters accepted by the form. |
   | `Forbidden characters detected. Please remove them and try again.` | Remove the forbidden characters from **Name** and select **OK** again. |

5. After a successful save, confirm that the new value is present in the **Name** column.

**Result:** The new unit appears as a row in the Units list. The save-success message is
`Data saved Successfully`.

![New Unit popup with the required Name field and modal action](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/fd92a21f24d37e2495e64eadfd1ac0b7.png)

### Edit a unit

Edit a unit when an existing value needs a different name and your account has edit
access.

**Prerequisites**

- You are signed in and the row edit action is available.
- You know the replacement value for **Name**.

**Steps**

1. In the Units list, select the existing unit row.
2. Open the row's edit action.
3. In the edit popup, replace the value in **Name**.
4. Select the popup save action labelled **Save** when it is shown.
5. Confirm that the row now shows the changed value in the **Name** column.

**Result:** The matching row shows the changed name, the popup closes after a successful
update, and the update-success message is `Data updated Successfully`.

### Remove a unit

If **Delete** is available, it removes a row after the confirmation prompt. Deletion is
refused when related saved data uses the unit or when only one row remains. The prompt
reads `Are you sure you want to delete this item?`; successful deletion displays
`Data Deleted Successfully`.

### Cancel an open unit form

Cancel an open unit form when you need to leave it without saving.

**Prerequisites**

- A new or edit popup is open.

**Steps**

1. In the open popup, select **Cancel**.
2. If the popup presents these action variants, select the one that matches your intent:

   | If you need to… | Select |
   |---|---|
   | Leave without saving | **Don't Save** |
   | Commit the current changes | **Save** |
   | Keep the popup open | **Cancel** |

**Result:** The popup closes without saving.

![The page shown after selecting Cancel](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/7908c98f08e107b18cb6966ae064403a.png)

## Handle access and list variations

The Units page uses common list controls, so the subscription, permissions, and saved
list layout determine which controls and columns you see.

| Variation | What to expect |
|---|---|
| If your subscription includes the required configuration | The Units content is available. |
| If **New** is available | You can open a new-item form. |
| If the row edit action is available | You can change an existing unit from this list. |
| If the row delete action is available | You can start deletion from this list. |
| If the shared import action is available | You can open the import flow. |
| If the shared export action is available | You can open the export choices. |
| If your saved list layout supplies different columns | Use the column headers shown in the list. |

This list has no entity-specific import control or entity-specific select, date, numeric,
or multi-line field. The Units form uses **Name**. Shared export surfaces, when available,
use the messages `Exporting List:`, `Export to Excel`, and `Export to PDF`, with **Cancel**
and **Export** as modal actions.

## When maintenance does not work

Use the message on screen to choose the correction before repeating the action.

| What you see | What it means | What to do |
|---|---|---|
| `Name is required` | **Name** has no value. | Enter the unit name in **Name**. |
| `Just '_' '-' And '.' Characters Accepted` | The value does not meet the accepted-character rule. | Replace disallowed characters in **Name**. |
| `Forbidden characters detected. Please remove them and try again.` | The value contains a forbidden character. | Remove it and select **OK** again. |
| `Related to Saved data, Can't be deleted` | Saved data uses the unit. | Keep the unit and remove or revise the related saved data through its owning task. |
| `Failed to Delete` | The deletion did not succeed. | Keep the row and repeat the action only after checking access and the row's saved-data relationships. |
| `Must have at least one item` | The list has reached its minimum of one item. | Keep at least one unit in the list. |

If the visible action labels, available permissions, row contents, or toast timing differ,
follow the controls shown on your screen. Permission-dependent actions and list columns
vary with the shared configuration.

## Use the units in sales items

After you maintain a unit here, continue on the sales-item page when you need to assign
that value. The Units list is the reference list for sales items.

The separate reference-list category question units entity is a different list, even
though it uses similar unit wording. For the sales-item task, continue with the Sales job
items page.
