> 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/facilities.md).

# Facilities

A facility is a health facility, clinic or similar site that delivers care through SPICE. Each facility belongs to a district and a sub-district, is linked to the villages it serves, has a set of clinical workflows that are switched on for it, and has users assigned to it.

The Admin Portal shows facilities under the name configured for your deployment (for example, "Health Facility"), so the words on your screens may differ from this guide.

This page explains how to find, create, edit, deactivate and reactivate facilities, and how to review a facility's summary.

## Who can manage facilities

| Role                                                | What they can do                                                  |
| --------------------------------------------------- | ----------------------------------------------------------------- |
| Super administrator                                 | List, create, edit and deactivate facilities in any region.       |
| Region administrator                                | List and create facilities in the districts of the region.        |
| District administrator                              | List and create facilities in the district.                       |
| Sub-district administrator                          | List and create facilities in the sub-district.                   |
| Facility administrator                              | View and edit the facility they administer, and manage its users. |
| Manager roles (area, regional or head-office level) | List, create and view facilities across the region.               |

## Find facilities

1. Open the facility list. Depending on your role, select the facility count on a region, district or sub-district card, select **Health Facility** (or your deployment's name for it) in the side menu, or open the facility cards on your home page.
2. The list shows each facility's **Name**, **Type**, and its district and sub-district.
3. Use the search box to find a facility by name.
4. Select the filter icon to filter by **Type**, district or sub-district. Choosing a district enables the sub-district filter.
5. Select a row to open the facility summary.

Deactivated facilities stay in the list but are shown dimmed, and you cannot open them or edit them until they are reactivated.

## Create a facility

Creating a facility takes two steps, plus an optional or required third step to add the first user. Use **Back** to return to a previous step and **Cancel** on the first step to leave without saving.

### Step 1: facility details

1. On the facility list, select **Add**.
2. Fill in the fields.

| Field                     | Required                                                                    | Notes                                                                                                                                                       |
| ------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Health Facility Name**  | Yes                                                                         | At least 2 characters. Must be unique. The portal checks the name when you leave the field. The name cannot be changed later.                               |
| **Health Facility Type**  | Yes                                                                         | Choose from the facility types set up for your deployment.                                                                                                  |
| **Address**               | Yes                                                                         | Free text.                                                                                                                                                  |
| **District**              | Yes                                                                         | Pre-selected when you start from a district or sub-district.                                                                                                |
| **Sub District**          | Yes                                                                         | Choose after the district. Pre-selected when you start from a sub-district.                                                                                 |
| **Village** (or **City**) | Community-based deployments: required. Facility-based deployments: optional | In community-based deployments you choose a village under the sub-district. In facility-based deployments you type at least 3 letters to search for a city. |
| **Facility ID**           | Yes                                                                         | At least 3 digits, digits only, up to 10. Must be unique. The portal checks it when you leave the field.                                                    |
| **Language**              | Yes                                                                         | The default language of the facility.                                                                                                                       |
| **Linked Villages**       | Community-based deployments: required                                       | The villages the facility serves. You can only choose villages under the selected sub-district. Select all or pick individual villages.                     |
| **Latitude**              | Yes                                                                         | Between -90 and 90.                                                                                                                                         |
| **Longitude**             | Yes                                                                         | Between -180 and 180.                                                                                                                                       |

3. In community-based deployments, select **Show Map** next to the coordinates to check or adjust the position on a map.
4. Select **Next**.

### Step 2: workflows involved

1. In **Workflows Involved**, tick the clinical workflows that this facility will use. Customised workflows created by your administrators appear in a separate list. Workflows that are always on for your deployment are pre-selected and cannot be cleared.
2. Select at least one workflow. **Submit** and **Next** stay disabled until you do.
3. Some workflows depend on or exclude each other. When you tick one, the portal may switch another one off or make it available.

Workflows are set up in [Workflow & Form Configuration](https://spice.docs.medtroniclabs.org/admin-guide/clinical-workflow-customization.md).

### Step 3: first user

* **Community-based deployments.** Adding a user is optional. Select **Submit** to create the facility on its own, or select **Add User** to add the first user before saving.
* **Facility-based deployments.** Select **Next** to add the first user. A user is required.

Fill in the user as described in [Users, Roles & Access](https://spice.docs.medtroniclabs.org/admin-guide/users-roles-and-access.md), and select **Submit**. The facility is created and you return to the facility list.

### Validation errors

| Message                                                                         | Cause                                                                                                                             |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **This health facility name already exists** / **Facility name already exists** | Another active facility has the same name.                                                                                        |
| **This facility id already exists** / **Facility ID already exists**            | Another active facility has the same Facility ID.                                                                                 |
| **Facility ID is not validated.** or **Failed to validate Facility ID**         | The portal could not check uniqueness, usually because of a network problem. Select **Validate** next to the field and try again. |
| **Please enter a valid latitude** or **longitude**                              | The value is outside the allowed range or has too many decimals.                                                                  |
| A message that no villages are available                                        | The selected sub-district has no villages. Add villages to the hierarchy first.                                                   |

## Edit a facility

1. On the facility list, select the edit icon on the row, or open the facility summary and select **Edit Health Facility**.
2. Change the details. The name, district and sub-district cannot be changed.
3. Select **Next** to review the workflows, change the selection, and select **Submit**.

When you remove a linked village, the portal checks that nobody still uses it. If users or assignments depend on the village, the change is rejected, with a message such as **Villages with active users cannot be removed.** Reassign or deactivate those users first.

## Deactivate a facility

1. On the facility list, switch off the **Active** toggle on the row. The toggle is shown in community-based deployments.
2. Confirm the message **This health facility has users linked to it. Are you sure you want to deactivate it?**

Deactivating a facility:

* deactivates the users linked to it and removes their link to the facility,
* removes the facility's linked villages and any sub-village assignments made through it, and
* hides the facility from day-to-day use.

When a whole district is deactivated, its facilities are deactivated with it. See [Account Lock & Unlock](https://spice.docs.medtroniclabs.org/admin-guide/account-lock-and-unlock.md).

## Reactivate a facility

1. On the facility list, switch on the **Active** toggle on the dimmed row. The **Activate** window opens with the facility details.
2. Choose the **Linked Villages** the facility should serve. The other fields are read-only.
3. Select **Submit**.

The facility is activated again, and the users who were deactivated with it are restored. If a user cannot be reactivated because their facility is still deactivated, the portal shows **Unable to activate user due to site deactivated.** Reactivate the facility first.

## Facility summary

Select a facility in the list, or on your home page if you are a facility administrator, to open its summary.

The **Summary** section shows:

* **Health Facility Name** and **Health Facility Type**
* the district, sub-district and village
* **Address**, **Latitude** and **Longitude**
* **Facility ID** and **Language**
* **Linked Villages**
* **Workflows**

Select **Edit Health Facility** to change the details.

The **Users** section lists the facility's users with their **Name**, **Role**, **Username**, **Gender** and **Contact Number**. Use the search box to find a user by name, email or phone number. Select **Add User** to add a user, or use the row icons to edit or delete one. Facility administrators cannot edit or delete other facility administrators.

For community health workers, the row also has an **Active** toggle. Before you deactivate a user, the confirmation window shows when the user last synced their data, so you can check that no work is waiting on their device. See [Users, Roles & Access](https://spice.docs.medtroniclabs.org/admin-guide/users-roles-and-access.md).

## Tips

* Create the hierarchy first, because facilities cannot be created without districts, sub-districts and villages. See [Administrative Hierarchy](https://spice.docs.medtroniclabs.org/admin-guide/country-level-administrative-divisions.md).
* Choose the facility type carefully. It cannot be filtered or reported on correctly if types are used inconsistently.
* Link only the villages a facility really serves. Users who work in a village must be assigned to a facility that is linked to it.
