> 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/clinical-workflow-customization.md).

# Workflow & Form Configuration

The admin portal lets you control which clinical workflows are available at each health facility, adjust the standard patient forms, and create your own workflows with their own forms. This page explains what you can change, what you cannot, who can do it, and how a change reaches the mobile app.

## What you can configure

| Area                   | What it controls                                                                                    | Where                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Workflows per facility | Which built-in and customised workflows are switched on for a facility                              | Facility create and edit screens, **Workflows Involved** step                               |
| Customised workflows   | Your own workflow modules, each with its own form                                                   | **Workflow Customization** page                                                             |
| Standard patient forms | Field settings on the Screening, Enrollment and Assessment forms, kept separately for each language | The region customisation page, **Screening Form**, **Enrollment Form**, **Assessment Form** |
| Programmes             | Named groups of facilities                                                                          | **Program** page                                                                            |

## Who can do this

* **Create, edit and delete customised workflows, customise forms, and manage programmes:** super users, super admins and region admins.
* **Choose which workflows a facility uses:** administrators who can create or edit that facility. The facility screens are available to the administrator levels that manage the facility's area, so the exact roles depend on your hierarchy. See [Facilities](https://spice.docs.medtroniclabs.org/admin-guide/facilities.md) and [Users, Roles & Access](https://spice.docs.medtroniclabs.org/admin-guide/users-roles-and-access.md).

## Built-in and customised workflows

Every workflow is one of two types, shown in the **Type** column of the Workflow Customization list.

| Type                | Can be edited, deleted or have its form customised in the portal? | Notes                                 |
| ------------------- | ----------------------------------------------------------------- | ------------------------------------- |
| Clinical (built-in) | No. The edit, delete and customise icons are hidden.              | You switch it on or off per facility. |
| Customised          | Yes                                                               | Created by an administrator.          |

## Turn workflows on or off for a facility

Workflows are assigned to each facility. A facility only receives the forms and menu entries for the workflows selected for it.

1. Open the list of facilities and choose **Add**, or choose to edit an existing facility.
2. Complete the facility details and select **Next**.
3. On the **Workflows Involved** step, tick the workflows to enable. Built-in workflows are listed under **Clinical Workflows involved** and your own under **Customized Workflows involved**.
4. Select **Submit**.

Things to know:

* At least one workflow must be selected. The screen shows a warning until you select one.
* Some built-in workflows are pre-selected and cannot be unticked.
* Some built-in workflows depend on one another or cannot be selected together. The screen adjusts the other ticks for you when you make such a choice.
* When a built-in workflow is not selected for a facility, the sections of the standard forms that belong to that workflow are left out of what that facility's users download.

## Create a customised workflow

1. Open **Workflow Customization**.
2. Select **Add Workflow**.
3. Enter a **Workflow Name**.
4. Under **View Screens**, tick one or more of **Screening**, **Enrollment** and **Assessment**.
5. Select **Submit**.

| Field         | Rules                                                                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow Name | Required, at least 2 characters. Must be unique within the region, ignoring upper and lower case. Cannot be changed after the workflow is created. |
| View Screens  | At least one of Screening, Enrollment or Assessment. This can be changed later with the edit icon.                                                 |

To change the screens later, select the edit icon on the row, change **View Screens** and select **Submit**. To delete a workflow, select the delete icon and confirm. A workflow that is still selected for a facility cannot be deleted. Remove it from those facilities first.

## Build the form for a customised workflow

1. In the **Workflow Customization** list, select the **Customize Workflow** icon on the row.
2. Use **Add New Field** inside a section and choose a field type: **Text Input**, **Radio Input**, **Select Input**, **Multi Select Input**, **Single Selection**, **Slider** or **Instructions**.
3. Set the field's properties, for example its display name, whether it is mandatory, option lists, length or value limits, placeholder and error message.
4. Optionally add a **Condition** to a field so that another field is shown, hidden or enabled depending on its answer.
5. Use **Edit Order** to reorder fields within a section, and the delete link on a field to remove a field you added.
6. Select **Submit**.

Fields you add to your own workflow can be deleted. The form is saved for the region and the workflow.

## Adjust the standard patient forms

The standard Screening, Enrollment and Assessment forms are customised from the region's customisation page. This page is titled with your deployment's label for the top-level area, for example " Customization".

1. Open the region customisation page and select the edit icon on **Screening Form**, **Enrollment Form** or **Assessment Form**.
2. Use the language drop-down at the top right to choose which language's version of the form you are editing.
3. Expand a section, change the settings on a field, and use **Edit Order** or **Edit family order** to reorder fields or sections.
4. Select **Submit**.

What you can change on an existing field depends on the field type. Typical editable settings are:

| Setting                                                                 | Notes                                                             |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Visibility, Is Enabled, Is Mandatory                                    | Not editable on fields the platform marks as required by default. |
| Min Length, Max Length, Min Value, Max Value, Field Length, Starts With | Only the limits that apply to the field's input type are shown.   |
| Placeholder, Error Message                                              | Free text.                                                        |
| Condition                                                               | Show, hide or enable another field depending on the answer.       |

What you cannot change on the standard forms:

* You cannot add new fields. Use a customised workflow when you need new questions.
* The field name, display name, option lists and input type are read-only.
* Each language has its own copy of the form. Apply the same change to each language you use.

## How changes reach the mobile app

* The app downloads its configuration, including forms, workflows and the facility's workflow selection, when a user signs in and when a user switches facility. It replaces the previously stored copy.
* There is no push update. Users who are already signed in keep the copy they downloaded until they next sign in or switch facility, and the app keeps working offline from that stored copy.
* The platform does not hold a separate cache of these forms, so a saved change is available to the next download.

## What is server-configurable and what is built into the app

Configuration is split between the server and the app itself.

| Configurable from the portal and downloaded by the app                                                                                            | Built into the app                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Which workflows each facility has                                                                                                                 | Several built-in service forms and the registration forms, which change only with a new app release                      |
| Settings on the standard Screening, Enrollment and Assessment forms                                                                               | Clinical decision-support logic, such as referral and risk rules                                                         |
| Customised workflows and their forms                                                                                                              | Availability rules for some service tiles, for example limits on how often a service can be repeated for the same person |
| Medication and lab test catalogues (see [Medications & Lab Tests](https://spice.docs.medtroniclabs.org/admin-guide/medications-and-lab-tests.md)) | The age and sex eligibility of built-in workflows                                                                        |

The portal has no screens for editing clinical decision-support rules, so changing those requires a change to the app or platform rather than a portal setting.

## Programmes

A programme is a named group of health facilities. On the **Program** page, select **Add Program** and enter a **Program Name** (at least 2 characters) and one or more facilities. When editing, you can switch the programme's **Status** off. The name cannot be changed after creation.

## Related pages

* [Admin Portal Overview](https://spice.docs.medtroniclabs.org/admin-guide/admin-guide.md)
* [Medications & Lab Tests](https://spice.docs.medtroniclabs.org/admin-guide/medications-and-lab-tests.md)
* [Multi-Language Translation](https://spice.docs.medtroniclabs.org/admin-guide/multi-language-translation.md)
