> 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/medications-and-lab-tests.md).

# Medications & Lab Tests

The admin portal holds two catalogues for each region: the **medication catalogue** that clinicians search when prescribing, and the **lab and imaging catalogue** that clinicians choose from when ordering investigations. This page explains how to maintain both, what the validation rules are, and how the entries appear in the mobile app.

## Who can manage the catalogues

Super users, super admins and region admins can add, edit and delete medications and lab tests. Each catalogue belongs to a region. Entries added for one region are not visible in another.

In the side menu the two pages are normally called **Medication Database** and **Lab/Imaging Database**.

## Medication catalogue

### View and search

Open **Medication Database** to see the list with the columns **Name**, **Classification**, **Brand Name** and **Dosage Form**. Use the search box to find a medication by name, or the filters for **Classification**, **Brand** and **Dosage Form**. Choosing a classification narrows the brand filter to the brands of that classification.

### Add medications

1. Select **Add**.
2. Fill in the fields in the table below.
3. Select the **Add** (plus) icon to start another row. You can enter several medications in one visit. Each row is checked for duplicates as you add it.
4. Select **Submit**.

| Field           | Required         | Notes                                                                                                                                                 |
| --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Medication Name | Yes              | 2 to 64 characters. Letters, digits, spaces and these symbols are allowed: `' . / , & ( ) + -`. Must contain at least one letter.                     |
| Code            | Yes              | The medication's code in your coding standard. Letters, digits, spaces and `- _ / ,` are accepted. Enter several codes separated by commas if needed. |
| URL             | Yes              | The address that identifies the coding standard the code belongs to. It applies to all codes on the row.                                              |
| Classification  | Yes              | Chosen from the existing list.                                                                                                                        |
| Brand           | Yes              | Chosen from the brands available for the selected classification. Changing the classification clears the brand.                                       |
| Dosage Form     | Yes              | Chosen from the existing list.                                                                                                                        |
| Category        | Depends on setup | Optional in some deployments and required in others.                                                                                                  |
| Group           | No               | One or more medication groups.                                                                                                                        |
| Recommended     | No               | Tick to offer the medication as a quick choice in the app.                                                                                            |

The **Code** and **URL** labels may carry the name of a coding standard in some deployments.

Classifications, brands, dosage forms, categories and groups are selected from lists. They cannot be created from these screens.

### Validation

* A medication is a duplicate if another medication in the region has the same name, classification, brand and dosage form. The portal shows "This medication is already available in the database." and nothing is saved.
* If two rows on the same form are identical, the portal shows a message and does not add the second row.
* If any row is rejected on save, no medication from that submission is created.

### Edit a medication

1. Select the edit icon on the row.
2. Change **Classification**, **Brand**, **Dosage Form**, **Code**, **URL**, **Category**, **Group** or **Recommended**.
3. Select **Submit**.

The **Medication Name** is read-only once the medication exists. To use a different name, add a new medication and delete the old one.

### Delete a medication

Select the delete icon on the row and confirm. The medication is removed from the catalogue and no longer appears in lists or searches.

## Lab and imaging catalogue

Each lab or imaging test has a name, a code, and a **result form** that defines what a clinician records when entering results, including the normal ranges to show.

### View and search

Open **Lab/Imaging Database**. The list shows **Name**, **Updated On**, and in some deployments **Display Order**. Use the search box to find a test.

### Add a lab test

1. Select **Add Lab Test**.
2. Enter the details in the table below and select **Next**.
3. The portal checks that the name is not already in use in the region, then opens the result form builder (see below).
4. Build the result form and select **Submit**.

| Field         | Required | Notes                                                                               |
| ------------- | -------- | ----------------------------------------------------------------------------------- |
| Lab Test Name | Yes      | At least 2 characters. Must be unique in the region, ignoring upper and lower case. |
| Code          | Yes      | Letters, digits, spaces, hyphens and underscores only.                              |
| URL           | Yes      | The address that identifies the coding standard the code belongs to.                |
| Recommended   | No       | Tick to offer the test as a quick choice in the app.                                |

The **Code** and **URL** labels may carry the name of a coding standard in some deployments.

### Build the result form

The result form is a short form with one section named after the test.

1. Every form starts with a mandatory **Tested On** date field. It cannot be removed or made optional, and it does not accept future dates.
2. Select **Add New Field** and choose **Text**, **Dropdown** or **Date**.
3. Set the field's properties:

| Property                 | Notes                                                                        |
| ------------------------ | ---------------------------------------------------------------------------- |
| Field Name, Display Name | The name used for the result and the label shown to the clinician.           |
| Input Type               | Number, Decimal values, Date or Text.                                        |
| Min Value, Max Value     | For numeric inputs.                                                          |
| Min Length, Max Length   | For text inputs.                                                             |
| Placeholder              | Hint text shown in the field.                                                |
| Is Mandatory             | Whether a value must be entered.                                             |
| Is Result                | Marks the field as a result value.                                           |
| Unit Types               | The units a result can be recorded in, chosen from the platform's unit list. |
| Code, URL                | Optional coding for the result value.                                        |
| Ranges                   | Reference ranges, described below.                                           |

4. Use **Edit Order** to reorder fields.
5. Select **Submit**.

A form must have at least two mandatory fields, including **Tested On**. Otherwise the portal shows "At least two fields need to be mandatory." and does not save.

### Result ranges

For a numeric result field, add one or more ranges to describe the reference values. Select the field's name first, then add a row.

| Range field   | Rules                                                              |
| ------------- | ------------------------------------------------------------------ |
| Unit          | Required. Chosen from the units of the field.                      |
| Gender        | Required. Male or Female.                                          |
| Min Value     | Required. A number.                                                |
| Max Value     | Required. A number that must be greater than the minimum.          |
| Display Range | Required. The text shown to the clinician, for example "70 - 100". |

### Edit and delete a lab test

* To change the name, code, URL or **Recommended** setting, select the edit icon, change the values and select **Submit**.
* To change the result form, select the **Customize Lab Test** icon.
* To delete a test, select the delete icon and confirm. It is removed from the catalogue.

## How the catalogues appear in the mobile app

* **Prescribing.** In the prescription step of a medical review, the clinician searches the medication catalogue by name. Results show the medication name with its dosage form, and may include medication groups. When the search box is empty, medications marked **Recommended** appear as quick choices. The search and the quick choices are requested from the server at the time, so the device needs a connection.
* **Investigations.** In the investigation step, lab tests marked **Recommended** appear as quick choices. When the clinician records results, the entry fields come from the test's result form, with units and reference ranges taken from the ranges you defined. Tests the clinician has already ordered for the patient are listed with their results.

Changes you save in the portal are available the next time the app requests the catalogue. They do not need a new app release.

## Related pages

* [Admin Portal Overview](https://spice.docs.medtroniclabs.org/admin-guide/admin-guide.md)
* [Workflow & Form Configuration](https://spice.docs.medtroniclabs.org/admin-guide/clinical-workflow-customization.md)
