Overview

The Web API is a component which makes it possible for external systems to access and manipulate data stored in an instance of DHIS2. More precisely, it provides a programmatic interface to a wide range of exposed data and service methods for applications such as third-party software clients, web portals and internal DHIS2 modules.

Introduction

The Web API adheres to many of the principles behind the REST architectural style. To mention some important ones:

1. The fundamental building blocks are referred to as resources. A resource can be anything exposed to the Web, from a document to a business process - anything a client might want to interact with. The information aspects of a resource can be retrieved or exchanged through resource representations. A representation is a view of a resource's state at any given time. For instance, the visualizations resource in DHIS2 represents visualizations of aggregated data for a certain set of parameters. This resource can be retrieved in a variety of representation formats including JSON and CSV.
2. All resources can be uniquely identified by a URI (also referred to as URL). All resources have a default representation. You can indicate that you are interested in a specific representation by supplying an Accept HTTP header, a file extension or a format query parameter. So in order to retrieve a CSV representation of an analytics data response you can supply an Accept: application/csv header or append .csv or ?format=csv to your request URL.
3. Interactions with the API requires the correct use of HTTP methods or verbs. This implies that for a resource you must issue a GET request when you want to retrieve it, POST request when you want to create one, PUT when you want to update it and DELETE when you want to remove it.

Authentication

The DHIS2 Web API supports three protocols for authentication:

• Basic Authentication
• Personal Access Tokens (PAT)
• OAuth 2

Verify and get information about the currently authenticated user by making a GET request to the following endpoint.

GET /api/me

Get the list of authorities for the currently authenticatd user.

GET /api/me/authorization

Check whether the currently authenticated user has the given authority.

GET /api/me/authorization/{authority}

For example, to check whether the user has the F_CONSTANT_ADD authority.

GET /api/me/authorization/F_CONSTANT_ADD

The response will be either true or false in JSON format.

Basic Authentication

The DHIS2 Web API supports Basic authentication. Basic authentication is a technique for clients to send login credentials over HTTP to a web server. Technically speaking, the username is appended with a colon and the password, Base64-encoded, prefixed Basic and supplied as the value of the Authorization HTTP header. More formally that is:

Authorization: Basic base64encode(username:password)

Most network-aware development environments provide support for Basic authentication, such as Apache HttpClient and Spring RestTemplate. An important note is that this authentication scheme provides no security since the username and password are sent in plain text and can be easily observed by an attacker. Using Basic is recommended only if the server is using SSL/TLS (HTTPS) to encrypt communication with clients. Consider this a hard requirement in order to provide secure interactions with the Web API.

Two-factor authentication

DHIS2 supports two-factor authentication. This can be enabled per user. When enabled, users will be asked to enter a 2FA code when logging in. You can read more about 2FA here.

Personal Access Token

Personal access tokens (PATs) are an alternative to using passwords for authentication to DHIS2 when using the API.

PATs can be a more secure alternative to HTTP Basic Authentication, and should be your preferred choice when creating a new app/script etc.

HTTP Basic Authentication is considered insecure because, among other things, it sends your username and password in clear text. It may be deprecated in future DHIS2 versions or made opt-in, meaning that basic authentication would need to be explicitly enabled in the configuration.

Important security concerns!

Your PATs will automatically inherit all the permissions and authorizations your user has. It is therefore extremely important that you limit the access granted to your token depending on how you intend to use it, see Configuring your token.

If you only want the token to have access to a narrow and specific part of the server, it is advised to rather create a new special user that you assign only the roles/authorities you want it to have access to.

Creating a token

To create a new PAT, you have two choices: * A. Create a token in the UI on your account's profile page. * B. Create a token via the API.

A. Creating a token on the account page

Log in with your username and password, go to your profile page (Click top right corner, and chose "Edit profile" from the dropdown). On your user profile page, choose "Personal access tokens" from the left side menu. You should now be on the "Manage personal access tokens" page and see the text: "You don't have any active personal access tokens". Click "Generate new token" to make a new token. A "Generate new token" popup will be shown and present you with two choices:

1. Server/script context

"This type is used for integrations and scripts that won't be accessed by a browser".

If you plan to use the token in an application, a script or similar, this type should be your choice.

2. Browser context

"This type us used for applications, like public portals, that will be accessed with a web browser".

If you need to link to DHIS2 on a webpage, or e.g. embed in an iframe, this is probably the type of token you want.

Configuring your token

After choosing what token type you want, you can configure different access constraints on your token. By constraint, we mean how to limit and narrow down how your token can be used. This can be of crucial importance if you plan on using the token in a public environment, e.g. on a public dashboard on another site, embedded in an iframe. Since tokens always have the same access/authorities that your user currently has, taking special care is needed if you intend to use it in any environment you don't have 100% control over.

NB: If anyone else gets their hands on your token, they can do anything your user can do. It is not possible to distinguish between actions performed using the token and other actions performed by your user.

Important: It is strongly advised that you create a separate unique user with only the roles/authorities you want the token to have if you plan on using PAT tokens in a non-secure and/or public environment, e.g. on a PC or server, you don't have 100% control over, or "embedded" in a webpage on another server.

Constraint types

• Expiry time
• Allowed UP addresses
• Allowed HTTP methods
• Allowed HTTP referrers

Expiry time

Expiry time simply sets for how long you want your token to be usable, the default is 30 days. After the expiry time, the token will simply return a 401 (Unauthorized) message. You can set any expiry time you want, but it is strongly advised that you set an expiry time that is reasonable for your use case.

IP addresses

This is a comma-separated list of IP addresses you want to limit where the token requests can come from.

Important: IP address validation relies on the X-Forwarded-For header, which can be spoofed. For security, make sure a load balancer or reverse proxy overwrites this header.

HTTP methods

A comma-separated list of HTTP methods you want your token to be able to use. If you only need your token to view data, not modify or delete, selecting only the GET HTTP method makes sense.

HTTP referrers

HTTP referer is a header added to the request, when you click on a link, this says which site/page you were on when you clicked the link. Read more about the HTTP referer header here: https://en.wikipedia.org/wiki/HTTP_referer

This can be used to limit the use of a "public" token embedded on another page on another site. Making sure that the referer header match the site hostname in should come from, can help avoid abuse of the token, e.g. if someone posts it on a public forum.

Important: this is not a security feature. The referer header can easily be spoofed. This setting is intended to discourage unauthorized third-party developers from connecting to public access instances.

Saving a token

When you are done configuring your token, you can save it by clicking the "Generate new token" button, on the bottom right of the pop-up. When doing so the token will be saved and a secret token key will be generated on the server. The new secret token key will be shown on the bottom of the PAT token list with a green background, and the text "Newly created token". The secret token key will look similar to this:

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Creating a token with the API

Example of how to create a new Personal Access Token using the API:

POST /api/apiToken
Content-Type: application/json
Authorization: Basic admin district

{}

This will return a response containing a token similar to this:

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "response": {
     "responseType": "ApiTokenCreationResponse",
     "key": "d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092",
     "uid": "jJYrtIVP7qU",
     "klass": "org.hisp.dhis.security.apikey.ApiToken",
     "errorReports": []
  }
}

Note: The token key will only be shown once here in this response. You need to copy and save this is in a secure place for use later!

The token itself consists of three parts: 1. Prefix: (d2pat_) indicates what type of token this is. 2. Random bytes Base64 encoded: (5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ) 3. CRC32 checksum: (1151814092) the checksum part is padded with 0 so that it always stays ten characters long.

Configure token with the API

To change any of the constraints on your token, you can issue the following HTTP API request.

Note: Only the constraints are possible to modify after the token has been created.

PUT /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: Basic admin district

{
  "version": 1,
  "type": "PERSONAL_ACCESS_TOKEN",
  "expire": 163465349603200,
  "attributes": [
      {
        "type": "IpAllowedList",
        "allowedIps": ["192.168.0.1"]
      },
      {
        "type": "MethodAllowedList",
        "allowedMethods": ["GET"]
      }
  ]
}

Using a Personal Access Token

To issue a request with your newly created token, use the Authorization header accordingly. The authorization header format is:

Authorization: ApiToken [YOUR_SECRET_API_TOKEN_KEY]

For example:

GET /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Deleting a Personal Access Token

You can delete your PATs either in the UI on your profile page where you created it, or via the API like this:

DELETE /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

OAuth2

DHIS2 supports the OAuth2 authentication protocol. OAuth2 is an open standard for authorization which allows third-party clients to connect on behalf of a DHIS2 user and get a reusable bearer token for subsequent requests to the Web API. DHIS2 does not support fine-grained OAuth2 roles but rather provides applications access based on user roles of the DHIS2 user.

Each client for which you want to allow OAuth 2 authentication must be registered in DHIS2. To add a new OAuth2 client go to Apps > Settings > OAuth2 Clients in the user interface, click Add new and enter the desired client name and the grant types.

Create a Client

An OAuth2 client can be added through the Web API. As an example, we can send a payload like this:

{
  "name": "OAuth2 Demo Client",
  "cid": "demo",
  "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
  "grantTypes": [
    "password",
    "refresh_token",
    "authorization_code"
  ],
  "redirectUris": [
    "http://www.example.org"
  ]
}

The payload can be sent with the following command:

SERVER="https://play.dhis2.org/dev"
curl -X POST -H "Content-Type: application/json" -d @client.json
  -u admin:district "$SERVER/api/oAuth2Clients"

This client will be used as the basis for the next grant type examples.

Grant type password

The simplest of all grant types is the password grant type. This grant type is similar to basic authentication in the sense that it requires the client to collect the user's username and password. As an example we can use our demo server:

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d grant_type=password -d username=admin -d password=district

This will give you a response similar to this:

{
  "expires_in": 43175,
  "scope": "ALL",
  "access_token": "07fc551c-806c-41a4-9a8c-10658bd15435",
  "refresh_token": "a4e4de45-4743-481d-9345-2cfe34732fcc",
  "token_type": "bearer"
}

For now, we will concentrate on the access_token, which is what we will use as our authentication (bearer) token. As an example, we will get all data elements using our token:

SERVER="https://play.dhis2.org/dev"
curl -H "Authorization: Bearer 07fc551c-806c-41a4-9a8c-10658bd15435" "$SERVER/api/33/dataElements.json"

Grant type refresh_token

In general the access tokens have limited validity. You can have a look at the expires_in property of the response in the previous example to understand when a token expires. To get a fresh access_token you can make another round trip to the server and use refresh_token which allows you to get an updated token without needing to ask for the user credentials one more time.

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"
REFRESH_TOKEN="a4e4de45-4743-481d-9345-2cfe34732fcc"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d "grant_type=refresh_token" -d "refresh_token=$REFRESH_TOKEN"

The response will be exactly the same as when you get a token to start with.

Grant type authorization_code

Authorized code grant type is the recommended approach if you don't want to store the user credentials externally. It allows DHIS2 to collect the username/password directly from the user instead of the client collecting them and then authenticating on behalf of the user. Please be aware that this approach uses the redirectUris part of the client payload.

Step 1: Visit the following URL using a web browser. If you have more than one redirect URIs, you might want to add &redirect_uri=http://www.example.org to the URL:

SERVER="https://play.dhis2.org/dev"
$SERVER/uaa/oauth/authorize?client_id=demo&response_type=code

Step 2: After the user has successfully logged in and accepted your client access, it will redirect back to your redirect uri like this:

http://www.example.org/?code=XYZ

Step 3: This step is similar to what we did in the password grant type, using the given code, we will now ask for an access token:

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -u demo:$SECRET -H "Accept: application/json" $SERVER/uaa/oauth/token
-d "grant_type=authorization_code" -d "code=XYZ"

Error and info messages

The Web API uses a consistent format for all error/warning and informational messages:

{
  "httpStatus": "Forbidden",
  "message": "You don't have the proper permissions to read objects of this type.",
  "httpStatusCode": 403,
  "status": "ERROR"
}

Here we can see from the message that the user tried to access a resource I did not have access to. It uses the http status code 403, the HTTP status message forbidden and a descriptive message.

Date and period format

Throughout the Web API, we refer to dates and periods. The date format is:

yyyy-MM-dd

For example, if you want to express March 20, 2014, you must use 2014-03-20.

The period format is described in the following table (also available on the API endpoint /api/periodTypes)

Relative Periods

In some parts of the API, like for the analytics resource, you can utilize relative periods in addition to fixed periods (defined above). The relative periods are relative to the current date and allow e.g. for creating dynamic reports. The available relative period values are described in the table below.

It is possible retrieve the ISO representations of these relative periods by making a GET request to the /api/relativePeriods/{RELATIVE_PERIOD_KEYWORD}

The endpoint supports the following parameters: - startDate: Represents the start date to calculate the relative period from. Format: yyyy-MM-dd. Default is today if not provided. - financialYearStart: Should be one of FINANCIAL_YEAR_FEBRUARY, FINANCIAL_YEAR_APRIL, FINANCIAL_YEAR_JULY, FINANCIAL_YEAR_AUGUST, FINANCIAL_YEAR_SEPTEMBER, FINANCIAL_YEAR_OCTOBER. Default is FINANCIAL_YEAR_OCTOBER if not provided.

As an example, to get the ISO representation of the relative period LAST_3_MONTHS from the date 2021-08-15, you can issue the following request: GET /api/relativePeriods/LAST_3_MONTHS?startDate=2021-08-15

The response in this case would be:

{
[
"202105",
"202106",
"202107"
]
}

Custom date periods

Analytics query resources support extra parameters to express periods.

Default pe dimension will fall back to:

• eventDate for /analytics/events/query
• enrollmentDate for /analytics/enrollments/query

Adding conditions on one or more date fields and combining them are allowed.

Usage of custom date periods

In resources supporting custom date periods, there are extra query parameters that will be combined to express conditions on the time dimension.

Conditions can be expressed in the following format:

/api/analytics/events/query/...?...&eventDate=2021&...

It's possible to combine more time fields in the same query:

/api/analytics/events/query/...?...&eventDate=2021&incidentDate=202102&...

All of these conditions can be combined with pe dimension:

/api/analytics/events/query/...?...&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&...

Supported formats are described in "date and period format" above. An extra format is provided to express a range of dates: yyyyMMdd_yyyyMMdd and yyyy-MM-dd_yyyy-MM-dd.

In the example bellow, the endpoint will return events that are scheduled to happen between 20210101 and 20210104:

/api/analytics/events/query/...?...&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&scheduledDate=20210101_20210104&...

Authorities

All available system authorities can be listed with identifiers and names using the following endpoint.

GET /api/authorities

It returns the following format:

{
  "systemAuthorities": [
    {
      "id": "ALL",
      "name": "ALL"
    },
    {
      "id": "F_ACCEPT_DATA_LOWER_LEVELS",
      "name": "Accept data at lower levels"
    }
  ]
}

Metadata

Identifier schemes

This section provides an explanation of the identifier scheme concept. Identifier schemes are used to map metadata objects to other metadata during import, and to render metadata as part of exports. Note that not all schemes work for all API calls, and not all schemes can be used for both input and output. This is outlined in the sections explaining the various API endpoints.

The full set of identifier scheme object types available are listed below, using the name of the property to use in queries:

• idScheme
• dataElementIdScheme
• categoryOptionComboIdScheme
• orgUnitIdScheme
• programIdScheme
• programStageIdScheme
• trackedEntityIdScheme
• trackedEntityAttributeIdScheme

The general idScheme applies to all types of objects. It can be overridden by specific object types.

The default scheme for all parameters is UID (stable DHIS2 identifiers). The supported identifier schemes are described in the table below.

Note that identifier schemes is not an independent feature but needs to be used in combination with resources such as data value import, metadata import and GeoJson import.

As an example, to specify CODE as the general id scheme and override with UID for organisation unit id scheme you can use these query parameters:

?idScheme=CODE&orgUnitIdScheme=UID

As another example, to specify an attribute for the organisation unit id scheme, code for the data element id scheme and use the default UID id scheme for all other objects you can use these parameters:

?orgUnitIdScheme=ATTRIBUTE:j38fk2dKFsG&dataElementIdScheme=CODE

Browsing the Web API

The entry point for browsing the Web API is /api. This resource provides links to all available resources. Four resource representation formats are consistently available for all resources: HTML, XML, JSON, and JSONP. Some resources will have other formats available, like MS Excel, PDF, CSV, and PNG. To explore the API from a web browser, navigate to the /api entry point and follow the links to your desired resource, for instance /api/dataElements. For all resources which return a list of elements certain query parameters can be used to modify the response:

An example of how these parameters can be used to get a full list of data element groups in XML response format is:

/api/dataElementGroups.xml?links=false&paging=false

You can query for elements on the name property instead of returning a full list of elements using the query query variable. In this example we query for all data elements with the word "anaemia" in the name:

/api/dataElements?query=anaemia

You can get specific pages and page sizes of objects like this:

/api/dataElements.json?page=2&pageSize=20

You can completely disable paging like this:

/api/indicatorGroups.json?paging=false

To order the result based on a specific property:

/api/indicators.json?order=shortName:desc

To order the result based on created datetime property first (descending order) and then by name property (ascending order):

/api/indicators.json?order=created:desc,name:asc

You can find an object based on its ID across all object types through the identifiableObjects resource:

/api/identifiableObjects/<id>

Translation

DHIS2 supports translations of database content, such as data elements, indicators, and programs. All metadata objects in the Web API have properties meant to be used for display / UI purposes, which include displayName, displayShortName, displayDescription and displayFormName (for data elements and tracked entity attributes).

Translation API

The translations for an object is rendered as part of the object itself in the translations array. Note that the translations array in the JSON/XML payloads is normally pre-filtered for you, which means they can not directly be used to import/export translations (as that would normally overwrite locales other than current users).

Example of data element with translation array filtered on user locale:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute French",
  "translations": [
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    }
  ]
}

Example of data element with translations turned off:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
  "translations": [
    {
      "property": "FORM_NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "Accute Flaccid Paral"
    },
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "DESCRIPTION",
      "locale": "en_FK",
      "value": "aa"
    }
  ]
}

Note that even if you get the unfiltered result, and are using the appropriate type endpoint i..e /api/dataElements we do not allow updates, as it would be too easy to make mistakes and overwrite the other available locales.

To read and update translations you can use the special translations endpoint for each object resource. These can be accessed by GET or PUT on the appropriate /api/<object-type>/<object-id>/translations endpoint.

As an example, for a data element with identifier FTRrcoaog83, you could use /api/dataElements/FTRrcoaog83/translations to get and update translations. The fields available are property with options NAME, SHORT_NAME, FORM_NAME, DESCRIPTION, locale which supports any valid locale ID and the translated property value.

Example of NAME property for French locale:

{
  "property": "NAME",
  "locale": "fr",
  "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
}

This payload would then be added to a translation array, and sent back to the appropriate endpoint:

{
  "translations": [
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
    }
  ]
}

For a data element with ID FTRrcoaog83 you can PUT this to /api/dataElements/FTRrcoaog83/translations. Make sure to send all translations for the specific object and not just for a single locale (if not you will potentially overwrite existing locales for other locales).

The status code will be 204 No Content if the data value was successfully saved or updated, or 404 Not Found if there was a validation error (e.g. more than one SHORT_NAME for the same locale).

Web API versions

The Web API /api can be used with a DHIS2 version number, example:

/api/42/dataElements

Versions 28-43 are supported. Calling an endpoint with or without a version does not change the behaviour of the API. The behaviour is the same no matter which approach is used. We aim to remove supporting API calls with versions, so please use API calls without the use of a version number.
The support for using versions is due to legacy design, which didn't evolve as originally envisioned.

Metadata object filter

To filter the metadata there are several filter operations that can be applied to the returned list of metadata. The format of the filter itself is straight-forward and follows the pattern property:operator:value, where property is the property on the metadata you want to filter on, operator is the comparison operator you want to perform and value is the value to check against (not all operators require value).

Please see the schema section to discover which properties are available. In addition to the listed properties filters can apply to custom attribute values by using the attribute's ID as property name.

Recursive filtering, ie. filtering on associated objects or collection of objects, is supported as well.

Operators will be applied as logical and query. If you need a or query, you can have a look at the in filter and the section below. The filtering mechanism allows for recursion. See below for some examples.

Get data elements with id property ID1 or ID2:

/api/dataElements?filter=id:eq:ID1&filter=id:eq:ID2

Get data elements, ignoring case, with name property MyDataElement:

/api/dataElements?filter=name:ieq:mydataelement

Get all data elements which have a data set with id ID1:

/api/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

Get all data elements with aggregation operator sum and value type int:

/api/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

You can do filtering within collections, e.g. to get data elements which are members of the ANC data element group you can use the following query using the id property of the associated data element groups:

/api/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

To get data elements with a particular attribute value for a metadata attribute, a filter for the attribute ID and the attribute value can be specified using the same collection query syntax:

/api/dataElements.json?filter=attributeValues.attribute.id:eq:n2xYlNbsfko&filter=attributeValues.value:eq:AFP

Get data elements which have any option set:

/api/dataElements?filter=optionSet:!null

Since all operators are and by default, you can't find a data element matching more than one id, for that purpose you can use the in operator.

/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

Logical operators

As mentioned in the section before, the default logical operator applied to the filters is AND which means that all object filters must be matched. There are however cases where you want to match on one of several filters (maybe id and code field) and in those cases, it is possible to switch the root logical operator from AND to OR using the rootJunction parameter.

Example: Normal filtering where both id and code must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

Example: Filtering where the logical operator has been switched to OR and now only one of the filters must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR

Identifiable token filter

In addition to the specific property based filtering mentioned above, we also have token based AND filtering across a set of properties: id, code, and name (also shortName if available). These properties are commonly referred to as identifiable. The idea is to filter metadata whose id, name, code or short name containing something.

Example: Filter all data elements containing 2^nd in any of the following: id,name,code, shortName

/api/dataElements.json?filter=identifiable:token:2nd

It is also possible to specify multiple filtering values.

Example: Get all data elements where ANC visit is found in any of the identifiable properties. The system returns all data elements where both tokens (ANC and visit) are found anywhere in identifiable properties.

/api/dataElements.json?filter=identifiable:token:ANC visit

It is also possible to combine the identifiable filter with property-based filter and expect the rootJunction to be applied.

/api/dataElements.json?filter=identifiable:token:ANC visit&filter=displayName:ilike:tt1

/api/dataElements.json?filter=identifiable:token:ANC visit
  &filter=displayName:ilike:tt1&rootJunction=OR

Metadata field filter

In many situations, the default views of the metadata can be too verbose. A client might only need a few fields from each object and want to remove unnecessary fields from the response. To discover which fields are available for each object please see the schema section. In addition to the listed properties custom attributes can be included for top level objects by using the attribute's ID as property name.

The format for include/exclude allows for infinite recursion. To filter at the "root" level you can just use the name of the field, i.e. ?fields=id,name which would only display the id and name fields for every object. For objects that are either collections or complex objects with properties on their own, you can use the format ?fields=id,name,dataSets[id,name] which would return id, name of the root, and the id and name of every data set on that object. Negation can be done with the exclamation operator, and we have a set of presets of field select. Both XML and JSON formats are supported.

Example: Get id and name on the indicators resource:

/api/indicators?fields=id,name

Example: Get id and name from data elements, and id and name from the associated data sets:

/api/dataElements?fields=id,name,dataSets[id,name]

Example: Get id, name and the value of a user defined attribute with ID DnrLSdo4hMl for organisation units:

/api/organisationUnits?fields=id,name,DnrLSdo4hMl

The attribute is then included as property DnrLSdo4hMl of each matching object in the response. This can be renamed using the rename transformer as shown in the next section.

To exclude a field from the output you can use the exclamation ! operator. This is allowed anywhere in the query and will simply not include that property as it might have been inserted in some of the presets.

A few presets (selected fields groups) are available and can be applied using the : operator.

Example: Include all fields from data sets except organisation units:

/api/dataSets?fields=:all,!organisationUnits

Example: Include only id, name and the collection of organisation units from a data set, but exclude the id from organisation units:

/api/dataSets/BfMAe6Itzgt?fields=id,name,organisationUnits[:all,!id]

Example: Include nameable properties from all indicators:

/api/indicators.json?fields=:nameable

Field transformers

Field transforms can be used to transform properties. The syntax is described below.

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

This will rename the id property to i and name property to n.

Multiple transformers can be applied to a single property by repeating the transformer operator:

/api/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements)

The supported transformer operators are described in the table below.

Examples

Examples of transformer usage are found below.

Get the size of a collection:

/api/dataElements?fields=dataSets~size

Test if a collection is empty:

/api/dataElements?fields=dataSets~isEmpty

Test if a collection is not empty:

/api/dataElements?fields=dataSets~isNotEmpty

Rename properties:

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

Apply paging to a collection:

/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)

Get array with IDs of organisation units:

/api/categoryOptions.json?fields=id,organisationUnits~pluck

Get array with names of organisation units:

/api/categoryOptions.json?fields=id,organisationUnits~pluck[name]

Key the dataElements array by the id field:

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy[id,name,valueType]

Key the dataElements array by the valueType field, since multiple hits this will results in arrays (of data elements):

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy(valueType)[id,name,valueType]

Metadata create, read, update, delete, validate

All metadata entities in DHIS2 have their own API endpoint which supports CRUD operations (create, read, update and delete). The endpoint URLs follows this format:

/api/<entityName>

The entityName uses the camel-case notation. As an example, the endpoint for data elements is:

/api/dataElements

NOTE: When updating objects, all existing property values will be overwritten, even if the new value is null. Please use JSON Patch API in case you want do partial update to an object.

Create / update parameters

The following request query parameters are available across all metadata endpoints.

Creating and updating objects

For creating new objects you will need to know the endpoint, the type format, and make sure that you have the required authorities. As an example, we will create and update a constant. To figure out the format, we can use the new schema endpoint for getting format description. So we will start with getting that info:

http://<server>/api/schemas/constant.json

From the output, you can see that the required authorities for create are F_CONSTANT_ADD, and the important properties are: name and value. From this, we can create a JSON payload and save it as a file called constant.json:

{
  "name": "PI",
  "value": "3.14159265359"
}

The same content as an XML payload:

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

We are now ready to create the new constant by sending a POST request to the constants endpoint with the JSON payload using curl:

curl -d @constant.json "http://server/api/constants" -X POST
  -H "Content-Type: application/json" -u user:password

A specific example of posting the constant to the demo server:

curl -d @constant.json "https://play.dhis2.org/api/constants" -X POST
  -H "Content-Type: application/json" -u admin:district

If everything went well, you should see an output similar to:

{
  "status": "SUCCESS",
  "importCount": {
    "imported": 1,
    "updated": 0,
    "ignored": 0,
    "deleted": 0
  },
  "type": "Constant"
}

The process will be exactly the same for updating, you make your changes to the JSON/XML payload, find out the ID of the constant, and then send a PUT request to the endpoint including ID:

curl -X PUT -d @pi.json -H "Content-Type: application/json"
  -u user:password "http://server/api/constants/ID"

Deleting objects

Deleting objects is very straight forward, you will need to know the ID and the endpoint of the type you want to delete, let's continue our example from the last section and use a constant. Let's assume that the id is abc123, then all you need to do is the send the DELETE request to the endpoint + id:

curl -X DELETE -u user:password "http://server/api/constants/ID"

A successful delete should return HTTP status 204 (no content).

Adding and removing objects in collections

The collections resource lets you modify collections of objects.

Adding or removing single objects

In order to add or remove objects to or from a collection of objects you can use the following pattern:

/api/{collection-object}/{collection-object-id}/{collection-name}/{object-id}

You should use the POST method to add, and the DELETE method to remove an object. When there is a many-to-many relationship between objects, you must first determine which object owns the relationship. If it isn't clear which object this is, try the call both ways to see which works.

The components of the pattern are:

• collection object: The type of objects that owns the collection you want to modify.

• collection object id: The identifier of the object that owns the collection you want to modify.

• collection name: The name of the collection you want to modify.

• object id: The identifier of the object you want to add or remove from the collection.

As an example, in order to remove a data element with identifier IDB from a data element group with identifier IDA you can do a DELETE request:

DELETE /api/dataElementGroups/IDA/dataElements/IDB

To add a category option with identifier IDB to a category with identifier IDA you can do a POST request:

POST /api/categories/IDA/categoryOptions/IDB

Adding or removing multiple objects

You can add or remove multiple objects from a collection in one request with a payload like this:

{
  "identifiableObjects": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ]
}

Using this payload you can add, replace or delete items:

Adding Items:

POST /api/categories/IDA/categoryOptions

Replacing Items:

PUT /api/categories/IDA/categoryOptions

Delete Items:

DELETE /api/categories/IDA/categoryOptions

Adding and removing objects in a single request

You can both add and remove objects from a collection in a single POST request to the following URL:

POST /api/categories/IDA/categoryOptions

The payload format is:

{
  "additions": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ],
  "deletions": [{
      "id": "IDD"
    }, {
      "id": "IDE"
    }, {
      "id": "IDF"
    }
  ]
}

Validating payloads

DHIS 2 supports system wide validation of metadata payloads, which means that create and update operations on the API endpoints will be checked for valid payload before allowing changes to be made. To find out what validations are in place for a specific endpoint, have a look at the /api/schemas endpoint, i.e. to figure out which constraints a data element have, you would go to /api/schemas/dataElement.

You can also validate your payload manually by sending it to the proper schema endpoint. If you wanted to validate the constant from the create section before, you would send it like this:

POST /api/schemas/constant

A simple (non-validating) example would be:

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/schemas/dataElement"

Which will yield the result:

[
   {
      "message" : "Required property missing.",
      "property" : "type"
   },
   {
      "property" : "aggregationOperator",
      "message" : "Required property missing."
   },
   {
      "property" : "domainType",
      "message" : "Required property missing."
   },
   {
      "property" : "shortName",
      "message" : "Required property missing."
   }
]

Partial updates

For our API endpoints that deal with metadata, we support partial updates (PATCH) using the JSON patch standard. The payload basically outlines a set of operation you want applied to a existing metadata object. For JSON patch details and examples, see jsonpatch.com. Three operators are supported: add, remove and replace.

Below is a few examples relevant to DHIS2. Note that any update to a payload should be thought of as a HTTP PUT operation, i.e. any mutation must result in a valid PUT metadata payload.

The default importReportMode for JSON patch is ERRORS_NOT_OWNER which implies that when updating any property which is not owned by that particular object (for example trying to add a indicator group directly to an indicator) you will get an error.

As per the JSON patch specification you must always use the mimetype application/json-patch+json when sending patches.

Examples

Update name and value type of data element

PATCH /api/dataElements/{id}

[
  {"op": "add", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/valueType", "value": "INTEGER"}
] 

Add new data element to a data element group

PATCH /api/dataElementGroups/{id}

[
  {"op": "add", "path": "/dataElements/-", "value": {"id": "data-element-id"}}
]

Remove all data element associations from a data element group

PATCH /api/dataElementGroups/{id}

[
  {"op": "remove", "path": "/dataElements"}
]

Change domain and value type of a data element

PATCH /api/dataElements/{id}

[
    {"op": "add", "path": "/domainType", "value": "TRACKER"},
    {"op": "add", "path": "/valueType", "value": "INTEGER"}
]

Remove a specific orgUnit from an orgUnit group

PATCH /api/organisationUnitGroups/{id}

[
  {"op": "remove", "path": "/organisationUnits/1"}
]

Blocked add dataElementGroup to dataElement

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "add", "path": "/dataElementGroups/-", "value": {"id": "data-element-group-id"}}
]

Blocked update name of dataElementGroup in dataElement

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "add", "path": "/dataElementGroups/0", "value": {"name": "new-name"}}
]

Remove collection item by id

PATCH /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/organisationUnits", "id": "u6CvKyF0Db5"}
]

Patch request with invalid path

If path property is invalid or does not exist the patch service will return an error as below

PATCH /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/test", "id": "u6CvKyF0Db5"}
]

{
    "httpStatus": "Bad Request",
    "httpStatusCode": 400,
    "status": "ERROR",
    "message": "Invalid path /test"
}

Metadata CSV export

Field filtering works almost the same for CSV (please note that using CSV on the /api/metadata endpoint is not supported), but not that field fransformations are not yet supported.

For endpoints that support CSV (our metadata endpoints like /api/dataElements /api/organisationUnits) you can either use the Accept header with value text/csv or you can use the extension .csv. Be aware that complex objects are not supported, and we only support id-object collections (so a list of UIDs will be returned).

Examples

Get all data elements including their group associations

/api/dataElements.csv?fields=id,displayName,dataElementGroups

Get all org units including geometry (which will get ignored)

/api/organisationUnits.csv?fields=id,displayName,organisationUnitGroups,geometry

Metadata export

This section explains the metatada API which is available at /api/metadata. XML and JSON resource representations are supported.

/api/metadata

The most common parameters are described below in the "Export Parameter" table. You can also apply this to all available types by using type:fields=<filter> and type:filter=<filter>. You can also enable/disable the export of certain types by setting type=true|false.

Metadata export examples

Export all metadata. Be careful as the response might be very large depending on your metadata configuration:

/api/metadata

Export all metadata ordered by lastUpdated descending:

/api/metadata?defaultOrder=lastUpdated:desc

Export metadata only including indicators and indicator groups:

/api/metadata?indicators=true&indicatorGroups=true

Export id and displayName for all data elements, ordered by displayName:

/api/metadata?dataElements:fields=id,name&dataElements:order=displayName:desc

Export data elements and indicators where name starts with "ANC":

/api/metadata?filter=name:^like:ANC&dataElements=true&indicators=true

Metadata export with dependencies

When you want to exchange metadata for a data set, program, category combo, dashboard, option set or data element group from one DHIS2 instance to another instance there are six dedicated endpoints available:

/api/dataSets/{id}/metadata.json

/api/programs/{id}/metadata.json

/api/categoryCombos/{id}/metadata.json

/api/dashboards/{id}/metadata.json

/api/optionSets/{id}/metadata.json

/api/dataElementGroups/{id}/metadata.json

These exports can then be imported using /api/metadata.

These endpoints also support the following parameters:

Metadata import

This section explains the metadata import API. XML and JSON resource representations are supported. Metadata can be imported using a POST request.

/api/metadata

The importer allows you to import metadata payloads which may include many different entities and any number of objects per entity. The metadata export generated by the metadata export API can be imported directly.

The metadata import endpoint support a variety of parameters, which are listed below.

NOTE When updating objects, all property values will be overwritten even if the new values are null. Please use JSON Patch API in case you want do partial update to an object.

An example of a metadata payload to be imported looks like this. Note how each entity type have their own property with an array of objects:

{
  "dataElements": [
    {
      "name": "EPI - IPV 3 doses given",
      "shortName": "EPI - IPV 3 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    },
    {
      "name": "EPI - IPV 4 doses given",
      "shortName": "EPI - IPV 4 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    }
  ],
  "indicators": [
    {
      "name": "EPI - ADS stock used",
      "shortName": "ADS stock used",
      "numerator": "#{LTb8XeeqeqI}+#{Fs28ZQJET6V}-#{A3mHIZd2tPg}",
      "numeratorDescription": "ADS 0.05 ml used",
      "denominator": "1",
      "denominatorDescription": "1",
      "annualized": false,
      "indicatorType": {
        "id": "kHy61PbChXr"
      }
    }
  ]
}

When posting this payload to the metadata endpoint, the response will contain information about the parameters used during the import and a summary per entity type including how many objects were created, updated, deleted and ignored:

{
  "importParams": {
    "userOverrideMode": "NONE",
    "importMode": "COMMIT",
    "identifier": "UID",
    "preheatMode": "REFERENCE",
    "importStrategy": "CREATE_AND_UPDATE",
    "atomicMode": "ALL",
    "flushMode": "AUTO",
    "skipSharing": false,
    "skipTranslation": false,
    "skipValidation": false,
    "metadataSyncImport": false,
    "firstRowIsHeader": true,
    "username": "UNICEF_admin"
  },
  "status": "OK",
  "typeReports": [
    {
      "klass": "org.hisp.dhis.dataelement.DataElement",
      "stats": {
        "created": 2,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 2
      }
    },
    {
      "klass": "org.hisp.dhis.indicator.Indicator",
      "stats": {
        "created": 1,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 1
      }
    }
  ],
  "stats": {
    "created": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0,
    "total": 3
  }
}

GeoJSON import

The GeoJSON import is used to attach geometry data to organisation units.

For a bulk import a GeoJSON file with a feature collection is expected. Each feature in the collection requires a reference to the organisation unit it should be linked to.

By default, the geometry from the file is stored as the geometry property of an organisation unit. To store additional geometries attributes of type GEOJSON can be created. When attributes are use all geometries from a file are stored for the same attribute which is provided with an additional parameter attributeId.

GeoJSON Bulk Data Import

Uasge:

POST /api/organisationUnits/geometry

The post body is the GeoJSON file. Content type should be application/json or application/geo+json. The file may be .zip or .gzip compressed.

For example, a default file where id is used to refer to an organisation unit id has this structure:

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "O6uvpzGd5pu",
      "geometry": { ... }
    },
    ...
  ]
}

A file where a feature property is used to refer to the organisation unit code would have this structure:

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "code": "OU1_CODE" },
      "geometry": { ... }
    },
    ...
  ]
}

A geometry may also be null to effectively clear or delete the geometry for specific organisation units. There is a special bulk deletion API that is described in the next section.

When run synchronously an import report is returned directly. The HTTP status code is always OK, the status in the message payload indicates if all rows were imported successfully. The import counts statistics contained in the report give further information:

• imported: number of organisation units that were successfully updated with a geometry that did not have one before for the updated property
• updated: number of organisation units that were successfully updated with a geometry that did have value for the updated property already
• ignored: number of organisation units that failed to update
• deleted: number of organisation units that where successfully update with a empty geometry

When the import is run asynchronous the request returns immediately with status OK and job configuration response that contains a relative reference to the task endpoint that allows to track the status of the asynchronous import. For example:

/api/system/tasks/GEOJSON_IMPORT/{job-id}

The summary that is returned directly for synchronous execution is available at

/api/system/taskSummaries/GEOJSON_IMPORT/{job-id}

once the import is finished.

GeoJSON Bulk Data Deletion

To clear or unset the geometry data for all organisation units use:

DELETE /api/organisationUnits/geometry

To clear or unset the geometry data for a specific GEOJSON attribute for all organisation units use:

DELETE /api/organisationUnits/geometry?attributeId={attr-id}

Clearing is always synchronous and returns a similar report as the bulk import. It does not support any other parameters. No dry-run can be performed. Bulk clearing requires the F_PERFORM_MAINTENANCE authority.

GeoJSON Single Data Import

The single import allows to update the geometry of a single organisation unit.

POST /api/organisationUnits/{id}/geometry

The post body only contains the GeoJSON geometry value, for example:

{
  "type": "Polygon",
  "coordinates": [...]
}

GeoJSON Single Data Deletion

To clear the geometry GeoJSON data of an individual organisation unit use:

DELETE /api/organisationUnits/{id}/geometry

Similarly to clear a GEOJSON attribute value for an individual organisation unit use:

DELETE /api/organisationUnits/{id}/geometry?attributeId={attr-id}

Clearing is always synchronous returns a similar report as single import. The dry-run parameter is supported as well. The performing user requires authority to modify the target organisation unit.

Schema

A resource which can be used to introspect all available DXF 2 objects can be found on /api/schemas. For specific resources you can have a look at /api/schemas/<type>.

To get all available schemas in XML:

GET /api/schemas.xml

To get all available schemas in JSON:

GET /api/schemas.json

To get JSON schema for a specific class:

GET /api/schemas/dataElement.json

Icons

DHIS2 includes a collection of icons that can be used to give visual context to metadata. There are two different kind of icons: - Default icons: they are pre-installed in the application and are not possible to modify nor delete. - Custom icons: can be created, updated and deleted at will.

Both of them be accessed through the icons resource.

GET /api/icons

This endpoint returns a list of information about the available default and custom icons. By default key, description, keywords and href will be included in response. But fields parameter can be used to change this behaviour.

{
  key: "mosquito_outline",
  description: "Mosquito outline",
  keywords: [
    "malaria",
    "mosquito",
    "dengue"
  ],
  "created": "2024-02-12T09:50:11.794",
  "lastUpdated": "2024-02-12T09:50:11.794",
  href: "<dhis server>/api/icons/mosquito_outline/icon.svg"
}

It's also possible to get a particular icon directly by filtering by its key, in the example below, the key is mosquito_outline.

GET /api/icons/mosquito_outline

Custom icon operations

A list of custom icons can be fetched retrieved certain request parameters

GET /api/icons?type=CUSTOM

Request parameters for pagination

Request parameters for ordering

Request parameter to filter responses

The endpoints accept a fields parameter which controls which fields will be returned in the JSON response. fields parameter accepts a comma separated list of field names. If nothing is specified, default fields will be used and those are

key,keywords,description,fileResourceUid,createdByUserUid,href

A custom icon resource can be downloaded by providing the icon key:

GET /api/icons/{key}/icon

Custom icons can be created, modified and deleted. To create a custom icon, use the resource below.

POST /api/icons

It expects a payload containing the icon key, description, list of keywords and the file resource uid to be linked to the data.

{
    "key": "iconKey",
    "description": "description",
    "keywords": ["keyword 1","keyword 2"],
    "fileResourceUid": "ARsqBjfB2cf"
}

Only custom icons can be updated using below resource.

PUT /api/icons

With the following payload, the icon's description and keywords would be updated.

{
    "key": "iconKey",
    "description": "new description",
    "keywords": ["new keyword 1", "new keyword 2"] 
}

Please notice that's also possible to just update one of the two. That means in case we would like to update the description while keeping the keywords, we would just need to provide the icon key and the descripton json field. Same would work the other way around, to update the keywords and leave the original description untouched.

Only custom icon can be deleted using below resource.

DELETE /api/icons/{icon_key}

Render type

Some metadata types have a property named renderType. The render type property is a map between a device and a renderingType. Applications can use this information as a hint on how the object should be rendered on a specific device. For example, a mobile device might want to render a data element differently than a desktop computer.

There is currently two different kinds of renderingTypes available:

1. Value type rendering

2. Program stage section rendering

There is also 2 device types available:

1. MOBILE

2. DESKTOP

The following table lists the metadata and rendering types available. The value type rendering has addition constraints based on the metadata configuration, which will be shown in a second table.

Since handling the default rendering of data elements and tracked entity attributes are depending on the value type of the object, there is also a DEFAULT type to tell the client it should be handled as normal. Program Stage Section is LISTING as default.

A complete reference of the previous table can also be retrieved using the following endpoint:

GET /api/staticConfiguration/renderingOptions

Value type rendering also has some additional properties that can be set, which is usually needed when rendering some of the specific types:

The renderingType can be set when creating or updating the metadata listed in the first table. An example payload for the rendering type for program stage section looks like this:

{
  "renderingType": {
    "type": "MATRIX"
  }
}

For data element and tracked entity attribute:

{
  "renderingType": {
    "type": "SLIDER",
    "min": 0,
    "max": 1000,
    "step": 50,
    "decimalPoints": 0
  }
}

Object Style

Most metadata have a property names "style". This property can be used by clients to represent the object in a certain way. The properties currently supported by style is as follows:

Currently, there is no official list or support for icon-libraries, so this is currently up to the client to provide. The following list shows all objects that support style:

• Data element

• Data element category option

• Data set

• Indicator

• Option

• Program

• Program Indicator

• Program Section

• Program Stage

• Program Stage Section

• Relationship (Tracker)

• Tracked Entity Attribute

• Tracked Entity Type

When creating or updating any of these objects, you can include the following payload to change the style:

{
  "style": {
    "color": "#ffffff",
    "icon": "my-beautiful-icon"
  }
}

Category

Merge categories

The category merge endpoint allows you to merge a number of categories (sources) into a target category.

Note

Categories can only be merged when:

1. they have identical category options
   
2. source and target categories do not share category combos
   
3. source categories do not share category combos with each other
   

These constraints ensure only duplicate Categories can be merged, and it helps to keep system integrity.

Authorisation

The main authority required to perform a category merge is F_CATEGORY_MERGE.

Request

Merge categories with a POST request:

POST /api/categories/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

The JSON properties are described in the following table.

The merge operation will merge the source categories into the target category. One or many source categories can be specified. Only one target should be specified.

The merge operation will transfer all source category metadata associations to the target category. The following metadata get updated:

Validation

The following constraints and error codes apply.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "Category",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "Category merge complete"
        }
    }
}

Failure

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source Category must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target Category does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "Category",
            "sourcesDeleted": [],
            "message": "Category merge has errors"
        }
    }
}

Category Option

Merge category options

The category option merge endpoint allows you to merge a number of category options (sources) into a target category option.

Authorisation

The main authority required to perform a category option merge is F_CATEGORY_OPTION_MERGE.
Other authorities required relate to the general sharing and access of category options, F_CATEGORY_OPTION_PUBLIC_ADD and F_CATEGORY_OPTION_DELETE.

Request

Merge category options with a POST request:

POST /api/categoryOptions/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

The JSON properties are described in the following table.

The merge operation will merge the source category options into the target category option. One or many source category options can be specified. Only one target should be specified.

The merge operation will transfer all source category option metadata associations to the target category option. The following metadata get updated:

Validation

The following constraints and error codes apply.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "CategoryOption",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "CategoryOption merge complete"
        }
    }
}

Failure

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source CategoryOption must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target CategoryOption does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "CategoryOption",
            "sourcesDeleted": [],
            "message": "CategoryOption merge has errors"
        }
    }
}

Category Option Combo

Import Validation

CategoryOptionCombos are unique in that they are auto-generated by the system, most of the time (imports are allowed with specific expectations, mentioned below). They are generated based on their category model:
- CategoryOption - Category (has category options) - CategoryCombo (has categories)

There will be a CategoryOptionCombo created for each combination of Category CategoryOption.

Generated CategoryOptionCombo Example

• There is 1 CategoryCombo [CC1]
• CC1 has 2 Categories CC1=[C1, C2]
• Each Category has 2 CategoryOptions C1=[CO1, CO2], C2=[CO3, CO4]
• The Generated CategoryOptionCombos from this category model would produce 4 CategoryOptionCombos:
• COC1=[CO1, CO3]
• COC2=[CO1, CO4]
• COC3=[CO2, CO3]
• COC4=[CO2, CO4]

This is important to understand when trying to import CategoryOptionCombos. Validation is performed when importing CategoryOptionCombos to ensure that the provided set of CategoryOptionCombos matches the expected generated set of CategoryOptionCombos. This is to ensure no invalid state/relationships can enter the system, which prevent all sorts of issues (orphaned data, hidden relationships in the DB not exposed in the API etc.).

Note

This validation is performed using the UIDs of the CategoryOptionCombos. No other idScheme is supported.

Merge category option combos

The category option combo merge endpoint allows you to merge a number of category options (sources) into a target category option. This can be used to clean up the system, removing duplicates for instance.

Note

Only duplicate category option combos can be merged. There's more info about this in the validation section below.

Authorisation

The main authority required to perform a category option combo merge is F_CATEGORY_OPTION_COMBO_MERGE.

Request

Merge category option combos with a POST request:

POST /api/categoryOptionCombos/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "dataMergeStrategy": "DISCARD"
}

The JSON properties are described in the following table.

The merge operation will merge the source category option combos into the target category option combo. One or many source category option combos can be specified. Only one target should be specified.

The merge operation will transfer all source category option combo metadata associations to the target category option combo.

Note

All source category option combos will always be deleted during a merge. The is because after all source references have been handled, empty category option combos are left. These are not seen as valid by the system.

The following metadata get updated:

Note

The following properties haven been purposely excluded from the merge as these may use references for external systems. If you encounter issues with these fields, they may need to be updated.

Indicator: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo

ProgramIndicator: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo

Validation

The following constraints and error codes apply. One of the main validation points is regarding duplicate CategoryOptionCombos. A duplicate CategoryOptionCombo is one which satisfies the criteria: - has the same CategoryCombo - has the same CategoryOptions - has a different UID

Database constraints

There are unique constraints in place that can prevent a successful merge. These constraints are set by DHIS2 in order to maintain a logical domain model.
Below are a list of the known database unique key constraints at the time of writing. For example, you can only have 1 min max data element with the same org unit, data element and category option combo.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "CategoryOptionCombo",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "CategoryOptionCombo merge complete"
        }
    }
}

Failure

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source CategoryOptionCombo must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target CategoryOptionCombo does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "CategoryOptionCombo",
            "sourcesDeleted": [],
            "message": "CategoryOptionCombo merge has errors"
        }
    }
}

A database constraint sample error response:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "ERROR: duplicate key value violates unique constraint \"minmaxdataelement_unique_key\"\n  Detail: Key (sourceid, dataelementid, categoryoptioncomboid)=(193236, 1148617, 167661) already exists."
}

Category Combo

Merge category combos

The category combo merge endpoint allows you to merge a number of category combos (sources) into a target category combo.

Note

Category combos can only be merged when:

1. source and target category combos have identical categories
   
2. all category option combos belonging to the involved category combos are valid (correct number of options, valid option membership)
   
3. no pre-existing duplicate category option combos exist within the involved category combos
   

These constraints ensure only equivalent category combos can be merged and help maintain system integrity.

Warning

A category combo merge will result in duplicate category option combos. These should be merged immediately after the category combo merge to maintain system integrity. Duplicates can be found using the data integrity check category_option_combos_have_duplicates.

Authorisation

The main authority required to perform a category combo merge is F_CATEGORY_COMBO_MERGE.

Request

Merge category combos with a POST request:

POST /api/categoryCombos/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

The JSON properties are described in the following table.

The merge operation will merge the source category combos into the target category combo. One or many source category combos can be specified. Only one target should be specified.

The merge operation will transfer all source category combo metadata associations to the target category combo. The following metadata get updated:

Validation

The following constraints and error codes apply.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "CategoryCombo",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "CategoryCombo merge complete. There will be duplicate CategoryOptionCombos as a result of the merge. These should be merged immediately to help keep system integrity. Duplicates can be found using the data integrity check `category_option_combos_have_duplicates`"
        }
    }
}

Failure

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source CategoryCombo must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target CategoryCombo does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "CategoryCombo",
            "sourcesDeleted": [],
            "message": "CategoryCombo merge has errors"
        }
    }
}

Data Elements

Merge data elements

Caution

Merging DataElements should be carried out with the utmost care. Particular attention should be given to the merging of data values that have data element references involved in the merge. Knowing the potential side effects of a merge should be fully understood before performing the merge. The merging of DataElements has far-reaching effects. The information below will try to help show what's involved in a DataElement merge. A DataElement merge touches all the major parts of the system (metadata, data, tracker, analytics and audit).

System performance may be impacted if the source DataElements are linked to large amounts of Data/Audit records particularly.

The data element merge endpoint allows you to merge a number of data elements (sources) into a target data element.

Authorisation

The main authority required to perform a data element merge is F_DATA_ELEMENT_MERGE.
Other authorities required relate to the general sharing and access of data elements, F_DATAELEMENT_PUBLIC_ADD and F_DATAELEMENT_DELETE.

Request

Merge data elements with a POST request:

POST /api/dataElements/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true,
  "dataMergeStrategy": "DISCARD"
}

The JSON properties are described in the following table.

The merge operation will merge the source data elements into the target data element. One or many source data elements can be specified. Only one target should be specified.

The merge operation will transfer all source data element metadata associations to the target data element. The following metadata get updated:

Validation

The following constraints and error codes apply.

Database constraints

There are unique constraints in place that can prevent a successful merge. These constraints are set by DHIS2 in order to maintain a logical domain model.
Below are a list of the known database unique key constraints at the time of writing. For example, you can only have 1 data set element with the same dataset and data element.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "DataElement",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "DataElement merge complete"
        }
    }
}

Failure

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source DataElement must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target DataElement does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

Another sample validation error response:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "All source ValueTypes must match target ValueType: `TEXT`. Other ValueTypes found: `NUMBER`",
                    "errorCode": "E1550",
                    "args": []
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

A database constraint sample error response:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "ERROR: duplicate key value violates unique constraint \"minmaxdataelement_unique_key\"\n  Detail: Key (sourceid, dataelementid, categoryoptioncomboid)=(193236, 1148617, 167661) already exists."
}

Indicators

This section describes indicators and indicator expressions.

Aggregate indicators

To retrieve indicators you can make a GET request to the indicators resource like this:

/api/indicators

Indicators represent expressions which can be calculated and presented as a result. The indicator expressions are split into a numerator and denominator. The numerators and denominators are mathematical expressions which can contain references to data elements, other indicators, constants and organisation unit groups. The variables will be substituted with data values when used e.g. in reports. Variables which are allowed in expressions are described in the following table.

Within a Data element operand or an Aggregate data element, the following substitutions may be made:

The syntax looks like this:

#{<dataelement-id>.<catoptcombo-id>} + C{<constant-id>} + OUG{<orgunitgroup-id>}

A corresponding example looks like this:

#{P3jJH5Tu5VC.S34ULMcHMca} + C{Gfd3ppDfq8E} + OUG{CXw2yu5fodb}

Note that for data element variables the category option combo identifier can be omitted. The variable will then represent the total for the data element, e.g. across all category option combos. Example:

#{P3jJH5Tu5VC} + 2

Data element operands can include any of category option combination and attribute option combination, and use wildcards to indicate any value:

#{P3jJH5Tu5VC.S34ULMcHMca} + #{P3jJH5Tu5VC.*.j8vBiBqGf6O} + #{P3jJH5Tu5VC.S34ULMcHMca.*}

An example using a data element group:

#{deGroup:oDkJh5Ddh7d} + #{deGroup:GBHN1a1Jddh.j8vBiBqGf6O}

An example using a category option, data element group, and a category option group:

#{P3jJH5Tu5VC.co:FbLZS3ueWbQ} + #{deGroup:GBHN1a1Jddh.coGroup:OK2Nr4wdfrZ.j8vBiBqGf6O}

An example using multiple category option groups:

#{P3jJH5Tu5VC.coGroup:OK2Nr4wdfrZ&j3C417uW6J7&ddAo6zmIHOk}

An example using a program data element and a program attribute:

( D{eBAyeGv0exc.vV9UWAZohSf} * A{IpHINAT79UW.cejWyOfXge6} ) / D{eBAyeGv0exc.GieVkTxp4HH}

An example combining program indicators and aggregate indicators:

I{EMOt6Fwhs1n} * 1000 / #{WUg3MYWQ7pt}

An example using a reporting rate:

R{BfMAe6Itzgt.REPORTING_RATE} * #{P3jJH5Tu5VC.S34ULMcHMca}

Another reporting rate example using actual data set reports and expected reports:

R{BfMAe6Itzgt.ACTUAL_REPORTS} / R{BfMAe6Itzgt.EXPECTED_REPORTS}

An example using an existing indicator:

N{Rigf2d2Zbjp} * #{P3jJH5Tu5VC.S34ULMcHMca}

Expressions can be any kind of valid mathematical expression, as an example:

( 2 * #{P3jJH5Tu5VC.S34ULMcHMca} ) / ( #{FQ2o8UBlcrS.S34ULMcHMca} - 200 ) * 25

Program indicators

To retrieve program indicators you can make a GET request to the program indicators resource like this:

/api/programIndicators

Program indicators can contain information collected in a program. Indicators have an expression which can contain references to data elements, attributes, constants and program variables. Variables which are allowed in expressions are described in the following table.

The syntax looks like this:

#{<programstage-id>.<dataelement-id>} + #{<attribute-id>} + V{<varible-id>} + C{<constant-id>}

A corresponding example looks like this:

#{A03MvHHogjR.a3kGcGDCuk6} + A{OvY4VVhSDeJ} + V{incident_date} + C{bCqvfPR02Im}

Expressions

Expressions are mathematical formulas which can contain references to data elements, constants and organisation unit groups. To validate and get the textual description of an expression, you can make a GET request to the expressions resource:

/api/expressions/description?expression=<expression-string>

The response follows the standard JSON web message format. The status property indicates the outcome of the validation and will be "OK" if successful and "ERROR" if failed. The message property will be "Valid" if successful and provide a textual description of the reason why the validation failed if not. The description provides a textual description of the expression.

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Valid",
  "description": "Acute Flaccid Paralysis"
}

Merge indicators

The indicator merge endpoint allows you to merge a number of indicators (sources) into a target indicator.

Authorisation

The authority F_INDICATOR_MERGE is required to perform indicator merges.

Request

Merge indicators with a POST request:

POST /api/indicators/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true
}

The JSON properties are described in the following table.

The merge operation will merge the source indicators into the target indicator. One or many source indicators can be specified. Only one target should be specified.

The merge operation will transfer all source indicator metadata associations to the target indicator. The following metadata get updated:

Validation

The following constraints and error codes apply.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "Indicator",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "Indicator merge complete"
        }
    }
}

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source Indicator must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target Indicator does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "Indicator",
            "sourcesDeleted": [],
            "message": "Indicator merge has errors"
        }
    }
}

Indicator Types

Merge indicator types

The indicator type merge endpoint allows you to merge a number of indicator types into a target indicator type.

Authorisation

The authority F_INDICATOR_TYPE_MERGE is required to perform indicator type merges.

Request

Merge indicator types with a POST request:

POST /api/indicatorTypes/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true
}

The JSON properties are described in the following table.

The merge operation will merge the source indicator types into the target indicator type. One or many source indicator types can be specified. Only one target should be specified.

The merge operation will transfer all of the indicator metadata associations to the source indicator types over to the target indicator type.

Validation

The following constraints and error codes apply.

Response

Success

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "IndicatorType",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "IndicatorType merge complete"
        }
    }
}

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source IndicatorType must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target IndicatorType does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "IndicatorType",
            "sourcesDeleted": [],
            "message": "IndicatorType merge has errors"
        }
    }
}

Organisation units

The organisationUnits resource follows the standard conventions as other metadata resources in DHIS2. This resource supports some additional query parameters.

Get list of organisation units

To get a list of organisation units you can use the following resource.

/api/33/organisationUnits

Get organisation unit with sub-hierarchy

To get an organisation unit including organisation units in its sub-hierarchy you can use the following resource.

/api/33/organisationUnits/{id}

Get organisation units by category option

Purpose-built endpoint to retrieve associations between category options and organisation units. This endpoint is the preferred way to retrieve program organisation unit associations.

/api/33/categoryOptions/orgUnits?categoryOptions={categoryOptionIdA},{categoryOptionIdB}

responses will have the following format:

{
  "<categoryOptionIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdC>": []
}

Category options that are accessible by all organisation units are returned with an empty array ([]) of organisation units.

Get organisation units by programs

Purpose-built endpoint to retrieve associations between programs and organisation units. This endpoint is the preferred way to retrieve program organisation unit associations.

/api/33/programs/orgUnits?programs={programIdA},{programIdB}

responses will have the following format:

{
  "<programIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdC>": []
}

Programs which are accessible by all organisation units are returned with an empty array ([]) of organisation units.

Split organisation unit

The organisation unit split endpoint allows you to split organisation units into a number of target organisation units.

Request

Split organisation units with a POST request:

POST /api/organisationUnits/split

The payload in JSON format looks like the following:

{
  "source": "rspjJHg4WY1",
  "targets": [
    "HT0w9YLMLyn",
    "rEpnzuNpRKM"
  ],
  "primaryTarget": "HT0w9YLMLyn",
  "deleteSource": true
}

The JSON properties are described in the following table.

The split operation will split the source org unit into the target org units. It is recommended to first create new target org units before performing the split, and at a minimum ensure that no aggregate data exists for the target org units. Any number of target org units can be specified.

The split operation will transfer all of the metadata associations of the source org unit over to the target org units. This includes data sets, programs, org unit groups, category options, users, visualizations, maps and event reports.

The operation will transfer all data records of the source org unit over to the org unit specified as the primary target, or if not specified, the first specified target org unit. This includes aggregate data values, data approval records, events, tracked entities and more.

Validation

The following constraints and error codes apply.

Merge organisation units

The organisation unit merge endpoint allows you to merge a number of organisation units into a target organisation unit.

Authorisation

The main authority required to perform an organisation unit merge is F_ORGANISATION_UNIT_MERGE.

Request

Merge organisation units with a POST request:

POST /api/organisationUnits/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "dataValueMergeStrategy": "LAST_UPDATED",
  "dataApprovalMergeStrategy": "LAST_UPDATED",
  "deleteSources": true
}

The JSON properties are described in the following table.

The merge operation will merge the source org units into the target org unit. It is recommended to first create a new target org unit before performing the merge, and at a minimum ensure that no aggregate data exists for the target org unit. Any number of source org units can be specified.

The merge operation will transfer all of the metadata associations of the source org units over to the target org unit. This includes data sets, programs, org unit groups, category options, users, visualizations, maps and event reports. The operation will also transfer all event and tracker data, such as events, enrollments, ownership history, program ownership and tracked entities, over to the target org unit.

The specified data value merge strategy defines how data values are handled. For strategy LAST_UPDATED, data values for all source org units are transferred over to the target org unit, and in situation where data values exist for the same parameters, the last updated or created data value will be used. This is done to avoid duplication of data. For strategy DISCARD, data values are not transferred over to the target org unit, and simply deleted. The specified data approval merge strategy defines how data approval records are handled, and follows the same logic as data values.

Validation

The following constraints and error codes apply.

Data sets

The dataSets resource follows the standard conventions as other metadata resources in DHIS2. This resource supports some additional query parameters.

/api/33/dataSets

To retrieve the version of a data set you can issue a GET request:

GET /api/33/dataSets/<uid>/version

To bump (increase by one) the version of a data set you can issue a POST request:

POST /api/33/dataSets/<uid>/version

Data set notification template

The dataset notification templates resource follows the standard conventions as other metadata resources in DHIS2.

GET /api/33/dataSetNotficationTemplates

To retrieve data set notification template you can issue a GET request:

GET /api/33/dataSetNotficationTemplates/<uid>

To add data set notification template you can issue a POST request:

POST /api/33/dataSetNotficationTemplates

To delete data set notification template you can issue a DELETE request:

DELETE /api/33/dataSetNotficationTemplates/<uid>

JSON payload sample is given below:

{
  "name": "dataSetNotificationTemplate1",
  "dataSetNotificationTrigger": "DATA_SET_COMPLETION",
  "relativeScheduledDays": 0,
  "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
  "dataSets": [{
    "id": "eZDhcZi6FLP"
  }],
  "deliveryChannels": ["SMS","EMAIL"],
  "subjectTemplate": "V{data_set_name}",
  "messageTemplate": "V{data_set_name}V{registration_period}",
  "sendStrategy": "SINGLE_NOTIFICATION"
}

notificationRecipient can be one of: - USER_GROUP for internal messages - ORGANISATION_UNIT_CONTACT for external messages

Filled organisation unit levels

The filledOrganisationUnitLevels resource provides an ordered list of organisation unit levels, where generated levels are injected into the list to fill positions for which it does not exist a persisted level.

GET /api/33/filledOrganisationUnitLevels

To set the organisation unit levels you can issue a POST request with a JSON payload and content type application/json looking like this:

{
  "organisationUnitLevels": [{
    "name": "National",
    "level": 1,
    "offlineLevels": 3
  }, {
    "name": "District",
    "level": 2
  }, {
    "name": "Chiefdom",
    "level": 3
  }, {
    "name": "Facility",
    "level": 4
  }]
}

Predictors

A predictor allows you to generate data values based on an expression. This can be used for example to generate targets, thresholds, or estimated values.

To retrieve predictors you can make a GET request to the predictors resource like this:

/api/predictors

Creating a predictor

You can create a predictor with a POST request to the predictors resource:

POST /api/predictors

A sample payload looks like this:

{
  "id": "AG10KUJCrRk",
  "name": "Malaria Outbreak Threshold Predictor",
  "shortName": "Malaria Outbreak Predictor",
  "description": "Computes the threshold for potential malaria outbreaks based on the mean plus 1.5x the std dev",
  "output": {
    "id": "nXJJZNVAy0Y"
  },
  "generator": {
    "expression": "AVG(#{r6nrJANOqMw})+1.5*STDDEV(#{r6nrJANOqMw})",
    "description": "Maximum normal malaria case count",
    "missingValueStrategy": "NEVER_SKIP",
    "slidingWindow": false
  },
  "periodType": "Monthly",
  "sequentialSampleCount": 4,
  "sequentialSkipCount": 1,
  "annualSampleCount": 3,
  "organisationUnitLevels": [4]
}

The output element refers to the identifier of the data element for which to saved predicted data values. The generator element refers to the expression to use when calculating the predicted values.

Predictor expressions

A predictor always has a generator expression that describes how the predicted value is calculated. A predictor may also have a skip test expression returning a boolean value. When the skip test expression is present, it is evaluated in each of the sampled periods to tell whether values from that period should be skipped.

The following variables may be used in either a generator expression or a skip test expression:

Generating predicted values

To run all predictors (generating predicted values) you can make a POST request to the run resource:

POST /api/predictors/run

To run a single predictor you can make a POST request to the run resource for a predictor:

POST /api/predictors/AG10KUJCrRk/run

Programs

To retrieve programs you can make a GET request to the programs resource like this:

/api/programs

Program category mappings

Starting in version 2.42, a program may optionally define one of more category mappings. These mappings can be used to add disaggregations to program indicators for the program. A program indicator for this program can choose which mappings to use for the categories in its category combination and/or attribute combination.

This allows program indicator data to be viewed by category and category option such as in the Data Visualizer. It also allows an Aggregate data exchange to generate values from the program indicator that contain a category option combination and/or an attribute option combination.

These category mappings can be generated by the Maintenance (Preview) App or they can be added using the Web API. This section describes the format of the category mappings if you are using the Web API.

A new program has no category mappings. In the Web API this looks like:

"categoryMappings": []

To add category mappings to the program, you can edit this part of the program definition and then import the result back into DHIS2. Here is an example of how the edited field could look:

"categoryMappings": [
  {
    "id": "goor7Li4See",
    "categoryId": "cX5k9anHEHd",
    "mappingName": "standard Gender mapping",
    "optionMappings": [
      {
        "optionId": "apsOixVZlf1",
        "filter": "#{Zj7UnCAulEk.oZg33kd9taw} == 'Female'"
      },
      {
        "optionId": "jRbMi0aBjYn",
        "filter": "#{Zj7UnCAulEk.oZg33kd9taw} == 'Male'"
      }
    ]
  },
  {
    "id": "ESesheeva1i",
    "categoryId": "VPqYge5RB93",
    "mappingName": "standard Outcome mapping",
    "optionMappings": [
      {
        "optionId": "e3oqm527jBS",
        "filter": "#{Zj7UnCAulEk.sAg4Niej9bo} == 'Managed at PHU'"
      },
      {
        "optionId": "rSdQZYDmHJm",
        "filter": "#{Zj7UnCAulEk.sAg4Niej9bo} == 'Referred'"
      }
    ]
  },
  {
    "id": "laiHaid9eit",
    "categoryId": "fkAkrdC7eJF",
    "mappingName": "Referrals Age at event",
    "optionMappings": [
      {
        "optionId": "K4gwuiVvW3z",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{event_date})<5"
      },
      {
        "optionId": "oaFqxkefkPs",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{event_date})>=5"
      }
    ]
  },
  {
    "id": "SeNg0bohFah",
    "categoryId": "fkAkrdC7eJF",
    "mappingName": "Referrals Age at analyitcs period start",
    "optionMappings": [
      {
        "optionId": "K4gwuiVvW3z",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{analytics_period_start})<5"
      },
      {
        "optionId": "oaFqxkefkPs",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{analytics_period_start})>=5"
      }
    ]
  }
]