# Cost items

Use this page to review, add, edit, remove, and export the cost-item reference entries used
in sales configuration.

## Cost items

Cost items are the additional-cost descriptions maintained for sales configuration. The
Cost items screen is a reference-data list: its entries are available to sales records
that use sales configuration reference data. The screen is titled **Additional cost items**
and contains the **Item Description** column.

| If you need to… | Go to |
|---|---|
| Check access and conditions before maintenance | [Before you start](#before-you-start) |
| Open the list and start a new or existing-item action | [Find Cost items](#find-cost-items) |
| Understand the visible list and form | [Understand the Cost items screen](#understand-the-cost-items-screen) |
| Add, edit, cancel, or export a cost item | [Add and maintain a cost item](#add-and-maintain-a-cost-item) |
| Remove an item or respond to a refusal | [Handle ordering and removal](#handle-ordering-and-removal) |
| Match a message to the next safe action | [When maintenance does not work](#when-maintenance-does-not-work) |
| Continue to related sales reference data | [After maintaining cost items](#after-maintaining-cost-items) |

![Cost items list with Item Description rows and the list controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6b83d39b2165f41051aa4e965d265b79.png)

## Before you start

Cost items maintenance depends on the subscription and access conditions for the action you
want to take. Check the condition that matches your task before relying on a control being
available.

| Task | Condition | What to check |
|---|---|---|
| View the list | The subscription feature is included. | The Cost items list is available instead of the subscription upgrade surface. |
| Add an item | The subscription feature is included and the new action is not hidden. | **New** is visible. |
| Edit an item | The subscription feature is included and edit access is allowed. | The row's edit action is available. |
| Delete an item | Delete access is allowed. | The row's delete action is available. |
| Complete the form | The new/edit popup is open, an item is selected, the column is visible in the form, and its type is `text-box`. | **Item Description** is available in the form. |
| Check required data | The visible column has its required flag set. | **Item Description** carries a required marker. |

The list's columns come from the configuration for the entity. The field label,
visibility, type, and required state therefore follow that configuration.

> **Note:** Use the headers and required marker currently visible in your list and form.

## Find Cost items

The Cost items list is the place to inspect the additional-cost entries before opening a
new-item or existing-item action. Look for the page title **Additional cost items**.

The list shows **Item Description** and the buttons **New**, **Refresh**, and **Settings**.

| If you need to… | Select or use |
|---|---|
| Start a new item | **New** |
| Reload the list | **Refresh** |
| Open list settings | **Settings** |
| Open an existing item | The edit action for the row in **Additional costs** |
| Remove an existing item | The delete action for the row in **Additional costs** |
| Export list data | The list action that opens **Export** |

**Steps**

1. Open the page titled **Additional cost items**.
2. Choose the action for the task.

   | If you need to… | Select |
   |---|---|
   | Start a new item | **New** |
   | Edit an existing item | The edit action for the row in **Additional costs** |

**Result:** The Cost items list remains open, or the selected new-item or existing-item form
is open.

![Additional cost items list with Item Description and the New, Refresh, and Settings controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6f6db7bfd79799c00b579cde35b536e5.png)

## Understand the Cost items screen

The Cost items screen combines a list with a new/edit popup. Export opens a list of export
choices. Use the values and controls visible in your list and popup.

| Surface | What appears or applies |
|---|---|
| List container | The list displays the configured cost-item entries. |
| Export surface | Export opens a list of export choices. |
| List data | The visible column list comes from the Cost items configuration. |
| Visible form field | **Item Description** is the visible form field. |
| Required state | **Item Description** is required when its configured required flag is set. |
| Hidden form values | `DisplayOrder`, `Id`, and `CompanyID` are hidden. |
| Other form fields | The Cost items settings declare no other visible form field. |
| List navigation | The list shows no column headers or paging. |
| List filtering | Search-panel, filter-row, and header-filter controls are disabled for this configuration. |

The form displays a field only when the new/edit popup is open, an item is selected, the
column is visible in the form, and the field is a text box. The visible form is therefore
centered on **Item Description** rather than on the hidden identifier values.

![New Additional cost items form with the required Item Description field](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ec7eb40f260cb9b6a39e8271eeb68ec6.png)

## Add and maintain a cost item

Use this procedure to create or change a cost-item description, cancel a change, or export
the list. The form's visible field is **Item Description** and its required validation message
is `Item Description is required`.

**Prerequisites**

- The Cost items list is open.
- The subscription feature is included.
- **New** is visible for a new item, or the edit action for the row in **Additional costs** is available for an existing item.
- You have the description to enter.

**Steps**

1. Choose the maintenance action.

   | If you need to… | Select |
   |---|---|
   | Create an item | **New** |
   | Change an existing item | The edit action for the row in **Additional costs** |
2. In **Item Description**, enter the cost-item description.
3. Check that **Item Description** carries its required marker.
4. Choose the form action.

   | If the form shows… | Select |
   |---|---|
   | The shared save action | **Save** |
   | The new-item action | **OK** |
   | No commit is wanted | **Cancel** |
5. Choose the next maintenance action.

   | If you need to… | Select |
   |---|---|
   | Add another entry | **Add more** |
   | Finish without another entry | **Cancel** |
6. Open the list action that provides **Export**.
7. Select **Export**.

The new-item form shows the title `New Additional cost items` and the action `OK`. A
successful new save uses `Data saved Successfully`; a successful update uses
`Data updated Successfully`.

**Result:** The new or edited cost item is submitted through the visible commit control, or
the form closes without a commit after **Cancel**. When the save succeeds, the corresponding
success message appears.

## Handle ordering and removal

Removal is the row-maintenance branch for a cost item. Check that the selected row is the one
you intend to remove; saved data can prevent deletion.

**Prerequisites**

- The Cost items list is open.
- Delete access is allowed.
- The delete action for the row in **Additional costs** is available.

**Steps**

1. Select the delete action for the row in **Additional costs**.
2. Read the confirmation message: `Are you sure you want to delete this item?`.
3. Choose the confirmation action.

   | If you want to… | Select |
   |---|---|
   | Remove the item | **Delete** |
   | Keep the item | **Cancel** |
4. Choose the next maintenance action.

   | If you need to… | Select |
   |---|---|
   | Add another entry | **Add more** |
   | Finish maintenance | **Cancel** |

**Result:** The selected row is submitted to the delete branch after **Delete**, or the
confirmation branch closes without deletion after **Cancel**. A successful deletion uses
`Data Deleted Successfully`.

## When maintenance does not work

Use the exact message on screen to choose the next safe action. These messages apply to Cost
items validation, filtering, saving, updating, and deletion.

| Message | What to do |
|---|---|
| `Item Description is required` | Enter a value in **Item Description**, then submit the form again. |
| `Just '_' '-' And '.' Characters Accepted` | Replace unsupported characters in **Item Description** with characters accepted by the form. |
| `Forbidden characters detected. Please remove them and try again.` | Remove the forbidden characters from the filter input, then submit the filter again. |
| `Must have at least one item` | Keep at least one cost item in the list. |
| `Related to Saved data, Can't be deleted` | Keep the item because saved data is related to it. |
| `Failed to Delete` | Do not assume the item was removed; return to the list and verify the row before taking another action. |
| `Data saved Successfully` | Check the list for the new cost item. |
| `Data updated Successfully` | Check the selected row for the updated description. |
| `Data Deleted Successfully` | Check the list to verify that the selected item was removed. |

## After maintaining cost items

After maintenance, return to **Additional costs** and confirm that the list is open. Use
**Refresh** when you need to reload the list after a change.

Cost items are sales configuration reference data. Continue with the related reference or
sales-record page for the next task:

- [Margin items](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-sales-margin-items)
- [Item units](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-sales-item-units)
- [Sales job record](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-record)

**Result:** The **Additional costs** list is open and ready for the next sales-configuration
task.
