> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/admin-guide/country-level-administrative-divisions.md).

# Administrative Hierarchy

The administrative hierarchy is the geographic structure that SPICE uses to organise work. Facilities are linked to villages, users are assigned to facilities or areas, and administrators manage only the part of the hierarchy that sits under them. Reports and dashboards also group data by these levels, so it is worth getting the hierarchy right before you create facilities and users.

This page explains how the hierarchy is modelled, how to view and bulk-upload it, and how to add, rename, deactivate and reactivate units in the Admin Portal.

## How the hierarchy is modelled

The hierarchy is a tree. Every deployment has one or more **regions** at the top, and each region contains levels of smaller areas beneath it. The number of levels and the names shown on screen (for example, "District" or "Sub District") are configured for your deployment, so the words in your portal may differ from this guide.

| Level            | Description                                                        | Notes                                                          |
| ---------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Region**       | The top-level area, such as a whole country or programme area.     | Created by a super administrator.                              |
| **Division**     | An optional grouping of districts.                                 | Community-based deployments only. Optional in the upload file. |
| **District**     | The first administrative level under the region (or division).     | Has a numeric code in community-based deployments.             |
| **Sub-district** | The level under a district.                                        | Has a short code in community-based deployments.               |
| **Village**      | The level under a sub-district. Facilities are linked to villages. | Has a code in community-based deployments.                     |
| **Sub-village**  | The smallest unit.                                                 | Community-based deployments only. Optional.                    |

The portal supports two deployment types, chosen when the region is created (the **App Type** option offers **Community** and **Non Community**):

* **Community-based** deployments use the full structure above, with codes at every level.
* **Facility-based** deployments use three levels under the region (district, sub-district and village) and do not use codes or divisions.

Within a level, a unit is identified by its **code** and its parent. Codes matter most for the bulk upload, because the upload uses codes to decide whether a row refers to an existing unit or a new one.

## View the hierarchy

1. Sign in as a super administrator, region administrator, a manager-level user (area, regional or head-office).
2. Open the region. Super administrators select a region card on the home page; region administrators and the manager roles open their own region.
3. The region page lists every village with its full chain of parent areas. Each cell shows the name and, when it has one, the code, for example `Name - 12`.
4. Use **Search Name** to find a unit.
5. Super administrators can also select the filter icon to narrow the list by division, district, sub-district and village. Filters work top-down: changing a filter clears the ones below it.

Only super administrators can upload or download the hierarchy. Other roles see the page as read-only.

## Create a region

Super administrators create regions from the region list.

1. On the home page, select **Create Region**.
2. In the region details section, enter **Region Name**, **Country Code** (the telephone country code used for phone numbers in this region, 1 to 5 digits) and select the **App Type**: **Community**, **Non Community**, or both.
3. In the region administrator section, enter the details of the first region administrator. See [Users, Roles & Access](https://spice.docs.medtroniclabs.org/admin-guide/users-roles-and-access.md) for the user fields.
4. Select **Submit**.

The region name must be at least 2 characters long. A region starts empty. Upload the hierarchy next.

## Upload the hierarchy

The bulk upload is the main way to load the hierarchy. It creates divisions, districts, sub-districts, villages and sub-villages in one step from a spreadsheet.

### Prepare the file

1. Open the region page. If the region has no data yet, select **Download Template**. If it already has data, select **Download** to export the current hierarchy in the same layout.
2. Open the downloaded `.xlsx` file. Do not rename, reorder or delete the column headers. The header text follows the level names configured for your deployment, and matching is not case-sensitive.
3. Add one row for each lowest-level unit. Repeat the names and codes of the parent levels on every row.

The portal accepts `.xlsx` spreadsheets only, and reads the first sheet.

#### Columns for community-based deployments

| Column            | Required                       | Rules                                                                                                                                                                |
| ----------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Region name       | Yes                            | Must match the name of an existing region. Rows for a region that does not exist are skipped.                                                                        |
| Region code       | No                             | 2 or 3 letters. Lower-case letters are converted to upper case. It is stored only if the region does not already have a code, and is ignored if the format is wrong. |
| Division          | No                             | Name of the division. If you fill in a division name or code, the division is created or matched.                                                                    |
| Division code     | No                             | Must be unique within the region.                                                                                                                                    |
| District          | Yes                            | Name of the district.                                                                                                                                                |
| District code     | Yes                            | Digits only, 1 to 4 digits, no leading zero (for example `52`, not `033`). Must be unique across all active districts.                                               |
| Sub-district      | Yes                            | Name of the sub-district.                                                                                                                                            |
| Sub-district code | Yes                            | Up to 3 characters. Must be unique within its district.                                                                                                              |
| Village           | Yes                            | Name of the village.                                                                                                                                                 |
| Village code      | Yes                            | Up to 10 characters. Must be unique within its sub-district.                                                                                                         |
| Sub-village       | No                             | Name of the sub-village.                                                                                                                                             |
| Sub-village code  | Yes, if a sub-village is given | Letters, numbers, spaces and hyphens only. Must be unique within its village.                                                                                        |

Names of districts, sub-districts and villages, and codes of sub-districts and villages, can contain letters, numbers, spaces and the characters `. , ' ( ) / -`. They cannot be blank.

#### Columns for facility-based deployments

| Column       | Required | Rules                                      |
| ------------ | -------- | ------------------------------------------ |
| Region name  | Yes      | Must match the name of an existing region. |
| District     | Yes      | Name of the district.                      |
| Sub-district | Yes      | Name of the sub-district.                  |
| Village      | Yes      | Name of the village.                       |

There are no code columns in facility-based deployments.

### Upload the file

1. On the region page, select **Upload**. If the region is empty, use the **Upload Region Mapping** area instead.
2. Drag your `.xlsx` file into the window, or select **Browse** and choose it.
3. Select **Upload** and wait for the process to finish. Large files can take several minutes. Do not close the page.
4. A success message confirms the upload. Check the result in the table, or use **Download** to export the hierarchy and compare it with your file.

The portal shows the success message when the file itself is accepted. **Rows that fail validation are skipped without an error message on screen**, so always check the result after an upload.

### How the upload treats existing data

* A unit is matched by its code under its parent. A row that matches an existing unit changes nothing.
* The upload does not rename units. If a row has the code of an existing unit but a different name, the row is skipped. To rename a district or sub-district, use the edit form described below.
* Uploading the same file again creates nothing new, so it is safe to repeat an upload after you correct the file.
* If you upload the same file again while the first upload is still being processed, the second upload is rejected.

### Validation and common errors

| Message or symptom                                         | Cause                                                                                                                                                                                                                                                                                              | What to do                                                                                         |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Please upload a valid file**                             | The file is not an `.xlsx` spreadsheet.                                                                                                                                                                                                                                                            | Save the file as `.xlsx` and try again.                                                            |
| **Invalid file.**                                          | The file is empty, has no sheets or cannot be read.                                                                                                                                                                                                                                                | Check that the file opens in a spreadsheet application and that the first sheet contains the data. |
| **Please upload excel with column names as per template.** | A required column is missing or the headers do not match the template.                                                                                                                                                                                                                             | Start again from the downloaded template and keep the headers unchanged.                           |
| This file is already being processed.                      | The same file is still being processed from an earlier upload.                                                                                                                                                                                                                                     | Wait for the first upload to finish.                                                               |
| Some rows are missing after the upload                     | The row failed validation and was skipped: a blank or invalid code, a code that is too long, a district code with a leading zero, a name with unsupported characters, a missing required value, a region name that does not exist, or a code that is already used by a unit with a different name. | Compare the downloaded export with your file, correct the missing rows and upload again.           |
| Villages are not under the expected sub-district           | The parent name or code on the row differs from the one used on other rows.                                                                                                                                                                                                                        | Use identical parent names and codes on every row.                                                 |

## Manage districts

Super administrators and region administrators manage districts. The names of the buttons follow your deployment's level name; this section uses "District".

### Add a district

1. Go to the district list. Region administrators land on it after signing in, where they can select **Create District**. Super administrators open the region from the home page and select the district count on the region card (or **District** in the side menu, if your menu includes it).
2. Select **Add District** (or **Create District**).
3. Enter the **District Name**. The name must be 2 to 64 characters long, contain at least one letter, and use only letters, numbers, spaces and the characters `' . / , & ( ) + -`.
4. In the **District Admin** section, enter the details of the district administrator.
5. Select **Submit**.

A district name must not already be in use.

### Edit a district

1. In the district list, select the edit icon on the row, or select the district to open its summary and select **Edit District**.
2. Change the name and select **Submit**.

District administrators can view the summary but cannot edit it.

### Deactivate a district

Deactivating a district hides it from day-to-day use together with everything beneath it.

1. Open the edit window for the district.
2. Select **Deactivate District**.
3. Choose a **Reason**: **Unable to pay**, **Contract expired**, **Site closure**, **Inactive site** or **Other**. Optionally describe the reason in **Describe the reason in detail**.
4. Select **Submit**.

Deactivating a district also deactivates its sub-districts, its facilities and their users. They cannot access the district or its data until it is reactivated.

### Reactivate a district

1. Open the user menu and select **Deactivated Records**.
2. Find the district. The list shows the **Name**, **Deactivated Date** and **Deactivated Reason**.
3. Select the activate icon on the row and confirm.

Reactivating the district reactivates the sub-districts, facilities and users that were deactivated with it. See [Account Lock & Unlock](https://spice.docs.medtroniclabs.org/admin-guide/account-lock-and-unlock.md).

### Consent forms

A district can have its own consent text for the **Screening** and **Enrollment** forms.

1. In the district list or on the district summary, select **Consent form**.
2. Choose the **Form Type**.
3. Enter or edit the text in the editor.
4. Select **Submit**. To remove the consent text, select **Delete Consent** and confirm.

The editor cannot be submitted empty (**Consent data should not be empty.**).

## Manage sub-districts

Super administrators, region administrators and district administrators can add sub-districts.

### Add a sub-district

1. Go to the sub-district list. District administrators land on it after signing in. Super and region administrators select the sub-district count on a region or district card.
2. Select **Add Sub District** (or **Create Sub District**).
3. Enter the **Sub District Name** using the same rules as a district name.
4. Select the **District** it belongs to. This is filled in when you start from a district, and shown to super and region administrators only.
5. Optionally, in **Villages**, type a village name and press Enter to add it. Repeat for each village. Only letters, numbers and spaces are accepted.
6. In the **Sub District Admin** section, enter the details of the sub-district administrator.
7. Select **Submit**.

A sub-district name must be unique. If it already exists you see a message that the name already exists in the regional database.

### Edit a sub-district

1. In the sub-district list, select the edit icon, or open the sub-district summary and select **Edit Sub District**.
2. Change the name and select **Submit**. The district cannot be changed.

Sub-district administrators can view the summary but cannot edit it. Sub-districts are deactivated and reactivated together with their district; there is no separate deactivate action.

## Tips

* Load the whole hierarchy in a single upload where you can, then use the forms only for small changes.
* Keep a copy of the spreadsheet you uploaded. Use **Download** at any time to export the current hierarchy.
* Keep codes stable. Codes are how the upload recognises existing units, so changing a code in the file creates a new unit.
* Create facilities only after the villages they will serve exist. See [Facilities](https://spice.docs.medtroniclabs.org/admin-guide/facilities.md).
