# Setup

The security definition, the REST connections and the configuration files the lab results services use.

This page is the first of the [Lab results](https://zato.io/docs/dev/healthcare/dhis2/lab-results/index.html) series. It covers what is configured once, before any service is written. DHIS2 itself is assumed to be configured already, with the program described on the [overview page](https://zato.io/docs/dev/healthcare/dhis2/lab-results/index.html#the-dhis2-program) and a user account whose organisation units and program access cover the cases the laboratory reports on.

## The security definition {#the-security-definition}

DHIS2 authenticates API clients with personal access tokens. The token is sent in the `Authorization` header with the `ApiToken` prefix, which a Zato [bearer token definition](https://zato.io/docs/security/bearer-tokens/index.html) provides in its static form.

1. In the Dashboard, open **Security** ▹ **Bearer tokens**.
2. Click **Create a Bearer token definition** and select the **Static tokens** tab.
3. Enter `DHIS2` as the **Name**.
4. Leave `Authorization` as the **Header**.
5. Enter `ApiToken` as the **Prefix**.
6. Paste the personal access token into **Token**.
7. Click **OK**.

![DHIS2 personal access token](https://zatosource-production.b-cdn.net/docs/gfx/dhis2/lab-results-bearer-token-create.webp?v=1791212088)

Dashboard menu: Security > Bearer tokens

## The REST connections {#the-rest-connections}

A URL path placeholder in a REST outgoing connection fills one path segment, so each DHIS2 endpoint has a connection of its own. All three use the `DHIS2` security definition and `JSON` as the data format.

| Name | URL path | Used by |
| --- | --- | --- |
| `DHIS2 Events` | `/api/tracker/events` | Finding the case a specimen belongs to |
| `DHIS2 Tracker` | `/api/tracker` | Writing the lab result event |
| `DHIS2 Data Values` | `/api/dataValueSets` | Sending the weekly counts |

The connections are created in the Dashboard under **Connections** ▹ **Outgoing** ▹ **REST**, as described in [Calling REST APIs](https://zato.io/docs/dev/rest/calling-apis.html), or with [enmasse](https://zato.io/docs/admin/enmasse.html) together with the security definition above.

[Video: DHIS2 Tracker connection](https://zatosource-production.b-cdn.net/docs/gfx/dhis2/lab-results-rest-tracker-create.webm?v=1791212150)

Dashboard menu: Connections > Outgoing > REST

## The configuration files {#the-configuration-files}

Identifiers and code mappings are kept in [configuration files](https://zato.io/docs/dev/examples/config.html) in `config/user-conf`, not in the services. The services read them through `self.config`.

`dhis2.ini` holds the identifiers of the program, its stages and its data elements, the cache keys the FHIR and held results services use, and the codes of the organisation unit and data set the weekly counts are reported to:

```ini
# config/user-conf/dhis2.ini

[program]
id = kla3mAPgvCH
stage_lab_request = ZkbAXlQUYJG
stage_lab_result = Nd4hWmBtx3E

[element]
specimen_id = Pg3hQfkCzWy
test = v1CBtvSrdXw
result = Mq7kDcXzYbR

[fhir]
marker_key = dhis2.lab.fhir.since

[held]
cache_key = dhis2.lab.held

[weekly]
org_unit = LAB_CENTRAL
data_set = LAB_WEEKLY
```

`lab_tests.ini` and `lab_results.ini` are [config tables](https://zato.io/docs/dev/examples/config-tables.html). Each maps a code the laboratory sends to the option code DHIS2 expects. The section name is the code system the laboratory's codes come from, which is what `translate` takes as its `source`:

```ini
# config/user-conf/lab_tests.ini

[LOINC]
94500-6 = COVID19_PCR
600-7   = BLOOD_CULTURE
```

```ini
# config/user-conf/lab_results.ini

[SNOMED]
260373001 = POSITIVE
260415000 = NEGATIVE
```

Adding a test or a result is a line in one of these files. The services do not change.

## Next {#next}

[Write a result](https://zato.io/docs/dev/healthcare/dhis2/lab-results/write.html) uses these connections and files to find a case by its specimen ID and write the result event to it.

## See also {#see-also}

- [Bearer tokens](https://zato.io/docs/security/bearer-tokens/index.html) - Static token definitions for API keys and personal access tokens
- [Calling REST APIs](https://zato.io/docs/dev/rest/calling-apis.html) - REST outgoing connections and how services invoke them
- [Config tables](https://zato.io/docs/dev/examples/config-tables.html) - Translate one party's codes into another's
- [Enmasse](https://zato.io/docs/admin/enmasse.html) - Define connections and security in a YAML file

## Learn more {#learn-more}

- [Healthcare interface engine](https://zato.io/docs/dev/healthcare/) - Clinical messages, FHIR, conversion and operations
- [HL7 v2 parsing](https://zato.io/docs/dev/healthcare/hl7/v2/parsing/) - Messages as typed objects, with field access and validation
- [MLLP channels](https://zato.io/docs/dev/healthcare/hl7v2/mllp/) - Receiving and sending HL7 v2 over MLLP sockets
- [FHIR integrations](https://zato.io/docs/dev/healthcare/hl7/fhir/) - Read and write FHIR resources, with paths, bundles and extensions
- [HL7 v2 to FHIR](https://zato.io/docs/dev/healthcare/hl7/to-fhir/) - Converting v2 messages into FHIR bundles, codes and references included
- [EDIFACT](https://zato.io/docs/dev/healthcare/edifact/) - Parsing interchanges, dialects and the transports they arrive on
- [Transformation](https://zato.io/docs/dev/healthcare/transformation/) - One message in, another standard out, in ordinary Python
- [Audit log](https://zato.io/docs/dev/healthcare/audit-log.html) - Every message with its acknowledgment, searchable by patient identifier
- [AI in clinical interfaces](https://zato.io/docs/dev/healthcare/ai/) - Services calling LLMs and AI agents calling clinical services as tools