# Reference categories

## Reference categories

A reference category is a category entry with questions for the Reference list. The related category-question
units use these categories and questions.

The list currently shows `No data` and `Count: 0`. When records exist, the list identifies them
through the **Name** and **Questions** columns.

| If you need to… | Go to |
|---|---|
| Check the list and its available maintenance controls | [Find and review the reference-category list](#find-and-review-the-reference-category-list) |
| Understand which fields are required or hidden | [Understand the fields and screen rules](#understand-the-fields-and-screen-rules) |
| Add or review a category and its questions | [Add or review categories and questions](#add-or-review-categories-and-questions) |
| Configure the related category-question units | [Reference-category question units](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-reference-list-reference-category-question-units-view) |
| Continue with another Reference list resource | [Serial Status](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-reference-list-reference-serial-status-view) |
| Return to the configuration entry point | [Configuration](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-home) |

## Before you start

Reference-category maintenance is available only when your account can use the configured feature and the
corresponding maintenance action is allowed.

**Prerequisites**

- The configured subscription includes this feature. Otherwise, the page shows an upgrade surface instead of
  the data grid.
- Edit access is available if you need to open a row for editing.
- Delete access is available if you need to open a row's delete menu.
- The **New** control is available when the page permits it.
- Start with a saved row when you need to edit an entry.

Open **Category** to see the category options available in your environment.
Continue with [Find and review the reference-category list](#find-and-review-the-reference-category-list).

## Find and review the reference-category list

Use this procedure to reach the list and identify the controls available in the current configuration.

**Prerequisites**

- The configured subscription includes this feature.
- You have access to the Configuration area.

**Steps**

1. Open **Configuration**.
2. Open **Reference list**.
3. Open **Categories questions**.

   ![Identify the Reference list page, its Name and Questions columns, and the empty-list message.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3a4d02493d81b486e006d028d8b1555d.png)

4. Check the list headers.

   | What you need to recognize | What appears |
   |---|---|
   | Category name column | **Name** |
   | Question summary column | **Questions** |
   | Create control | **New** |
   | List refresh control | **Refresh** |
   | List settings control | **Settings** |

5. Select **New** to open a new-entry popup.
6. If **Export** is available in the shared toolbar, select **Export** to open its export options.
7. If the row edit action is available, select the row edit control to open the selected row in edit mode.
8. If the row delete action is available, select the row delete control to open the delete menu.

**Result:** The Reference categories list is open. You can see its columns, its current row count, and the
maintenance controls that your access and shared-toolbar configuration make available.

## Understand the fields and screen rules

The maintenance popup contains the category selection and a collection of questions. The list shows the
columns for the selected reference-list resource.

| Surface | What you use it for | Rule or visibility |
|---|---|---|
| **Category** | Select the category for the entry. | Required select field; form-only. |
| **Category questions** | Maintain the questions belonging to the selected category. | Required collection field; form-only. |
| **Question** | Enter one question in a collection row. | Required text box in each collection row. |
| **Add more** | Add another question row. | Available when the **Category questions** collection is shown. |
| Remove control | Remove a question row from the collection. | Shown with the collection. |
| **Name** | Read the category name in the list. | Visible list column. |
| **Questions** | Read the question summary in the list. | Visible list column. |
| Display order | — | Hidden in the list and the form. |
| Supporting child fields | — | Hidden from the list and form. |

The page does not show a search panel, and paging is disabled. Captions and columns can change with the
page configuration and the selected reference-list resource, so use the labels and headers visible on your page.

Use these fields and rules when you continue to [add or review categories and questions](#add-or-review-categories-and-questions).

## Add or review categories and questions

Use this procedure to start a new entry or review a saved row, maintain its question collection, and close
the popup.

**Prerequisites**

- The Reference categories list is open.
- For a new entry, **New** is available.
- For review or editing, a saved row and edit access are available.
- You know the category to select and the questions to enter.

**Steps**

1. Choose the entry point that matches your task.

   | If you need to… | Select |
   |---|---|
   | Start a new category entry | **New** |
   | Review or edit a saved entry | The row edit control for the saved entry |

   The selected entry opens in a popup.
2. In **Category**, select the category for this entry.
3. Review **Category questions**.
4. If the collection is available, select **Add more** for each additional question you need to enter.
5. In each **Question** row that is available, enter the question text.
6. Select **OK** after the validation group is valid.
7. If you do not want to keep the popup changes, select **Cancel** to close the popup.

For a new entry, complete the required **Category** and **Category questions** fields. If **Questions** is
disabled, use the controls that are enabled. Enter **Question** when its row is available.

**Result:** After you select **OK**, the Reference categories list refreshes when the entry is saved or updated.
After **Cancel**, the popup closes.

When a new entry saves successfully, the screen displays `Data saved Successfully`. When an existing entry
updates successfully, it displays `Data updated Successfully`.

## Handle reference-list variations

Reference-list maintenance uses one shared configuration screen. Its fields and actions change with the
reference-list resource and the access available to the account.

| Variation | What changes for you |
|---|---|
| Reference-list resource | The shared screen supports 11 resource values. |
| Field type and form visibility | The field control can be a select box, text box, date box, number box, or collection text box, and appears in the popup when it is enabled for the form. |
| Subscription | If the subscription excludes the feature, an upgrade surface replaces the grid. |
| Edit access | The row edit control is available only when edit access is allowed. |
| Delete access | The row delete control is available only when delete access is allowed. |
| List columns | The list headers come from the selected reference-list configuration. |
| Question collection | **Question** is available when a question collection is shown and enabled. |

The options shown in **Category** and the maintenance controls available to you depend on your environment.
Open **Category** to see the choices you can select before using the maintenance procedure above.

## When maintenance goes wrong

Use the message you see to identify whether a required value, a character rule, or a deletion condition
needs attention.

| What you see | What it means | What to do |
|---|---|---|
| `Category is required` | **Category** has no selection. | Choose a value in **Category**. |
| `This Field Is Required` | A required field is empty. | Enter or select the missing value. |
| `Required` | A required collection-row value is empty. | Enter the required **Question** value in the row. |
| `Just '_' '-' And '.' Characters Accepted` | The entered value does not meet the accepted character pattern. | Replace the value with one that uses the accepted characters. |
| `Forbidden characters detected. Please remove them and try again.` | The entered value contains a forbidden character. | Remove the forbidden character. |
| `Data saved Successfully` | A new entry was saved. | Check the refreshed list for the entry. |
| `Data updated Successfully` | An existing entry was updated. | Check the refreshed list for the updated row. |
| `Data Deleted Successfully` | The selected row was deleted. | Check the refreshed list. |
| `Related to Saved data, Can't be deleted` | The selected row is related to saved data. | Keep the row and remove or change the related saved-data dependency through its owning configuration. |
| `Failed to Delete` | The deletion did not complete. | Keep the row, then retry after checking that delete access is available. |
| `Must have at least one item` | The list cannot be reduced below one item. | Keep at least one item in the list. |
| Delete is unavailable when only one item remains | The last item cannot be deleted. | Maintain the remaining item. |

> **Note:** The delete success and failure messages apply to the row-delete action when it is available.

## After maintaining reference categories

After a successful maintenance action, the Reference categories list is refreshed. Use it to review the
resulting category rows.

Reference categories supply categories and questions to [Reference-category question units](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-reference-list-reference-category-question-units-view).
For another resource in the same area, open [Serial Status](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-reference-list-reference-serial-status-view).
