# Departments

## Departments at a glance

A department is a named part of a company branch that you set up before assigning
employees to it. The Departments list keeps these named company-branch entries in one
place for company administration. Employees can then use a department association, and
signed-in users carry a list of departments for their administration context.

| If you need to… | Go to |
| --- | --- |
| Check what a department entry contains | [Understand the Departments screen](#understand-the-departments-screen) |
| Create or change a department | [Add or change a department](#add-or-change-a-department) |
| Enter the department name and save it | [Add or edit an entry](#add-or-edit-an-entry) |
| Remove a department or open export | [Remove or export departments](#remove-or-export-departments) |
| Resolve a validation or save message | [When a department action goes wrong](#when-a-department-action-goes-wrong) |
| Continue with user or related administration | [Continue after department maintenance](#continue-after-department-maintenance) |

## Before you start

You must be signed in and pass the Departments route guard. The Departments grid is
available when the subscription includes the required feature. The **New** action is
available when that feature is included and the configuration does not hide **New**.
Editing requires edit permission, and deleting requires delete permission.

| Access condition | What it controls |
| --- | --- |
| Signed-in user passes the route guard | Access to the Departments route |
| Subscription includes the feature | The department grid |
| Feature included and `hideNewButton` is false | **New** |
| Edit permission granted | Row edit action |
| Delete permission granted | Row delete action |

## Find Departments

The company-branch reference list is named **Departments**; **Branches** is a separate
sibling list.

**Prerequisites**

- You are signed in.
- Your signed-in user passes the Departments route guard.

**Steps**

1. Open company administration.
2. Select **Departments**.

**Result:** The Departments list is selected in the company configuration surface when
your access permits it.

## Understand the Departments screen

The Departments screen is a list of named department entries with an entry popup for
creating or changing one entry. **Name** is the only visible grid field and the only
visible form field. It is required. The entity also carries `DisplayOrder`,
`CompanyBranchDepartmentID`, `CompanyBranchID`, and `Description`, but these values do not
appear as visible form controls.

| Screen area | What to use it for |
| --- | --- |
| Department list | View the configured department entries |
| New/edit popup | Enter or change **Name** |
| **Name** | Enter the required department name |
| Hidden entity values | Preserve entity data that is not exposed as a form control |

The current list column set comes from the list configuration, so work from the headers
that appear in your list. The grid and the entry popup are separate containers within the
shared configuration surface.

> **Note:** A department name is the value employees and signed-in users use when the
> department relationship is assigned. Enter the name that colleagues recognise in
> company administration.

## Add or change a department

Use **New** for a department that does not yet exist. The action opens a new-item popup and
initializes the display order. Use the row edit action for an existing department; it opens
that row in the edit popup. The row edit action appears only when edit permission is
granted.

**Prerequisites**

- The subscription includes the Departments feature.
- The configuration does not hide **New** when you are creating an entry.
- You have edit permission when you are changing an existing entry.

**Steps**

1. Choose a maintenance path.

   | If you need to… | Select |
   | --- | --- |
   | Create a department | **New** |
   | Change an existing department | The row edit action for that department |

2. Continue in the entry popup described in [Add or edit an entry](#add-or-edit-an-entry).

**Result:** A new-item popup or the selected department's edit popup is open.

### Add or edit an entry

The entry popup accepts the required **Name**. **OK** submits the popup for both a new
entry and an edit.

**Prerequisites**

- The new-item or edit popup is open.
- You have the department name to enter.

**Steps**

1. In **Name**, enter the department name.
2. Select **OK**.

After you select **OK**, follow the action for the message that appears.

   | Result shown | Action |
   | --- | --- |
   | `Name is required` | Enter a value in **Name**. |
   | `Forbidden characters detected. Please remove them and try again.` | Remove the forbidden characters from **Name**. |
   | `Data saved Successfully` | Confirm that the new entry is saved. |
   | `Data updated Successfully` | Confirm that the existing entry is updated. |

**Result:** The department entry is submitted with the name you entered, or the popup
remains available for correction when validation stops submission.

## Remove or export departments

Removal changes the department list and is available only when delete permission is
granted. The **Delete** action applies when more than one item exists, preserving the
minimum-one-item rule. **Export** is a separate, non-destructive list action and is
available when export permission is granted.

| Need | Condition | Action |
| --- | --- | --- |
| Remove a department | Delete permission and more than one item exists | Delete row |
| Keep the list unchanged and open export | Export permission is granted | **Export** |

**Prerequisites**

- The Departments list is open.
- You have delete permission for removal or export permission for export.

**Steps**

1. Choose an action.

   | If you need to… | Select |
   | --- | --- |
   | Remove a row | The row delete action |
   | Open export | **Export** |

2. Continue with [Delete an entry or open export](#delete-an-entry-or-open-export).

**Result:** The department remains unchanged after **Cancel**, the selected department is
removed after confirmed deletion, or the export action is open.

### Delete an entry or open export

Deleting opens a confirmation path; export opens its separate export surface. The delete
confirmation gives you **Cancel** before the destructive action and **Delete** to confirm.

**Prerequisites**

- For deletion, delete permission is granted and more than one department item exists.
- For export, export permission is granted.

**Steps**

1. For deletion, read the confirmation `Are you sure you want to delete this item?`.
2. Select one confirmation action.

   | If you need to… | Select |
   | --- | --- |
   | Keep the department | **Cancel** |
   | Confirm removal | **Delete** |

3. For export, select **Export** to open the export surface.

**Result:** The delete menu closes without deletion, deletion is confirmed, or the export
surface opens.

## Handle surface variations

The Departments surface changes with subscription access, permissions, and the current
company's list configuration.

| Variation | What changes for you |
| --- | --- |
| Subscription feature unavailable | The subscription-required upgrade surface appears instead of the grid |
| **New** hidden or feature unavailable | **New** is not available |
| Edit permission unavailable | The row edit action is not available |
| Delete permission unavailable | The row delete action is not available |
| Export permission unavailable | **Export** is not available |
| List configuration differs | The department list and its visible columns can differ |
| Shared configuration surface | Sibling entities can appear in the same multi-entity component |

Use the selected entity name to distinguish **Departments** from sibling administration
tabs. A missing action reflects the current subscription or permission setup; it does not
add another field to the entry popup.

## When a department action goes wrong

Use the exact message on screen to choose the next action. The messages below cover name
validation, save and update results, deletion results, and the rule that keeps at least one
item in the list.

| Message | What to do |
| --- | --- |
| `Name is required` | Enter a value in **Name**, then select **OK**. |
| `Forbidden characters detected. Please remove them and try again.` | Remove the forbidden characters from **Name**, then select **OK**. |
| `Related to Saved data, Can't be deleted` | Keep the department and review the saved data related to it before attempting maintenance again. |
| `Failed to Delete` | Do not assume the row was removed; review the list and contact an administrator if it remains unchanged. |
| `Must have at least one item` | Keep at least one department entry in the list. |
| `Data Deleted Successfully` | Confirm that the selected department was removed, then check the list. |
| `Data saved Successfully` | Treat the new department as saved and continue with department maintenance. |
| `Data updated Successfully` | Treat the changed department as updated and continue with department maintenance. |

## Continue after department maintenance

Use the maintained department names when employee records or signed-in-user
administration assigns departments.

| Next need | Related surface |
| --- | --- |
| Assign or review departments for users | Users overview |
| Maintain a related administration reference list | Teams |
| Maintain the company branch associated with departments | Branches |

Use the product's administration navigation to open the related surface that your role
permits. Keep the department name consistent with the name colleagues select for employee
and signed-in-user administration.
