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 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 and a user account whose organisation units and program access cover the cases the laboratory reports on.

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 provides in its static form.

In the Dashboard, open Security ▹ Bearer tokens.
Click Create a Bearer token definition and select the Static tokens tab.
Enter DHIS2 as the Name.
Leave Authorization as the Header.
Enter ApiToken as the Prefix.
Paste the personal access token into Token.
Click OK.

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, or with enmasse together with the security definition above.

The configuration files

Identifiers and code mappings are kept in configuration files 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:

# 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. 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:

# config/user-conf/lab_tests.ini

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

# 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.

Write a result uses these connections and files to find a case by its specimen ID and write the result event to it.

Feature	What it does
Bearer tokens	Static token definitions for API keys and personal access tokens
Calling REST APIs	REST outgoing connections and how services invoke them
Config tables	Translate one party's codes into another's
Enmasse	Define connections and security in a YAML file