Settings and configuration¶

System settings¶

You can manipulate system settings by interacting with the systemSettings resource. A system setting is a simple key-value pair, where both the key and the value are plain text strings. To save or update a system setting you can make a POST request to the following URL:

/api/33/systemSettings/my-key?value=my-val

Alternatively, you can submit the setting value as the request body, where content type is set to "text/plain". As an example, you can use curl like this:

curl "play.dhis2.org/demo/api/33/systemSettings/my-key" -d "My long value"
  -H "Content-Type: text/plain" -u admin:district

To set system settings in bulk you can send a JSON object with a property and value for each system setting key-value pair using a POST request:

{
  "keyApplicationNotification": "Welcome",
  "keyApplicationIntro": "DHIS2",
  "keyApplicationFooter": "Read more at dhis2.org"
}

Translations for translatable Setting keys can be set by specifying locale as a query parameter and translated value which can be specified either as a query param or withing the body payload. See an example URL:

/api/33/systemSettings/<my-key>?locale=<my-locale>&value=<my-translated-value>

You should replace my-key with your real key and my-val with your real value. To retrieve the value for a given key (in JSON or plain text) you can make a GET request to the following URL:

/api/33/systemSettings/my-key

Alternatively, you can specify the key as a query parameter:

/api/33/systemSettings?key=my-key

You can retrieve specific system settings as JSON by repeating the key query parameter:

curl "play.dhis2.org/demo/api/33/systemSettings?key=keyApplicationNotification&key=keyApplicationIntro"
  -u admin:district

You can retrieve all system settings with a GET request:

/api/33/systemSettings

To retrieve a specific translation for a given translatable key you can specify a locale as query param:

/api/33/systemSettings/<my-key>?locale=<my-locale>

If present, the translation for the given locale is returned. Otherwise, a default value is returned. If no locale is specified for the translatable key, the user default UI locale is used to fetch the correct translation. If the given translation is not present, again, the default value is returned.

The priority for translatable keys is the following:

specified locale > user's default UI locale > defaut value

To delete a system setting, you can make a DELETE request to the URL similar to the one used above for retrieval. If a translatable key is used, all present translations will be deleted as well.

To delete only a specific translation of translatable key, the same URL as for adding a translation should be used and the empty value should be provided:

/api/33/systemSettings/<my-key>?locale=<my-locale>&value=

The available system settings are listed below.

User settings¶

You can manipulate user settings by interacting with the userSettings resource. A user setting is a simple key-value pair, where both the key and the value are plain text strings. The user setting will be linked to the user who is authenticated for the Web API request. To return a list of all user settings, you can send a GET request to the following URL:

/api/33/userSettings

User settings not set by the user, will fall back to the equivalent system setting. To only return the values set explicitly by the user, you can append ?useFallback=false to the above URL, like this:

/api/33/userSettings?useFallback=false

To save or update a setting for the currently authenticated user you can make a POST request to the following URL:

/api/33/userSettings/my-key?value=my-val

You can specify the user for which to save the setting explicitly with this syntax:

/api/33/userSettings/my-key?user=username&value=my-val

Alternatively, you can submit the setting value as the request body, where content type is set to "text/plain". As an example, you can use curl like this:

curl "https://play.dhis2.org/demo/api/33/userSettings/my-key" -d "My long value"
  -H "Content-Type: text/plain" -u admin:district

As an example, to set the UI locale of the current user to French you can use the following command.

curl "https://play.dhis2.org/demo/api/33/userSettings/keyUiLocale?value=fr"
  -X POST -u admin:district

You should replace my-key with your real key and my-val with your real value. To retrieve the value for a given key in plain text you can make a GET request to the following URL:

/api/33/userSettings/my-key

To delete a user setting, you can make a DELETE request to the URL similar to the one used above for retrieval.

The available system settings are listed below.

Configuration¶

To access configuration you can interact with the configuration resource. You can get XML and JSON responses through the Accept header or by using the .json or .xml extensions. You can GET all properties of the configuration from:

/api/33/configuration

You can send GET and POST requests to the following specific resources:

GET /api/33/configuration/systemId

GET POST DELETE /api/configuration/feedbackRecipients

GET POST DELETE /api/configuration/offlineOrganisationUnitLevel

GET POST /api/configuration/infrastructuralDataElements

GET POST /api/configuration/infrastructuralIndicators

GET POST /api/configuration/infrastructuralPeriodType

GET POST DELETE /api/configuration/selfRegistrationRole

GET POST DELETE /api/configuration/selfRegistrationOrgUnit

GET POST /api/facilityOrgUnitGroupSet

GET POST /api/facilityOrgUnitLevel

For the CORS whitelist configuration you can make a POST request with an array of URLs to whitelist as payload using "application/json" as content-type, for instance:

["www.google.com", "www.dhis2.org", "www.who.int"]

GET POST /api/33/configuration/corsWhitelist

For POST requests, the configuration value should be sent as the request payload as text. The following table shows appropriate configuration values for each property.

As an example, to set the feedback recipients user group you can invoke the following curl command:

curl "localhost/api/33/configuration/feedbackRecipients" -d "wl5cDMuUhmF"
  -H "Content-Type:text/plain"-u admin:district

Tokens¶

The tokens resource provides access tokens to various services.

Google Service Account¶

You can retrieve a Google service account OAuth 2.0 access token with a GET request to the following resource.

GET /api/tokens/google

The token will be valid for a certain amount of time, after which another token must be requested from this resource. The response contains a cache control header which matches the token expiration. The response will contain the following properties in JSON format.

This assumes that a Google service account has been set up and configured for DHIS2. Please consult the installation guide for more info.

Static content¶

The staticContent resource allows you to upload and retrieve custom logos used in DHIS2. The resource lets the user upload a file with an associated key, which can later be retrieved using the key. Only PNG files are supported and can only be uploaded to the logo_banner and logo_front keys.

/api/33/staticContent

To upload a file, send the file with a POST request to:

POST /api/33/staticContent/<key>

Example request to upload logo.png to the logo_front key:

curl -F "file=@logo.png;type=image/png" "https://play.dhis2.org/demo/api/33/staticContent/logo_front"
  -X POST -H "Content-Type: multipart/form-data" -u admin:district

Uploading multiple files with the same key will overwrite the existing file. This way, retrieving a file for any given key will only return the latest file uploaded.

To retrieve a logo, you can GET the following:

GET /api/33/staticContent/<key>

Example of requests to retrieve the file stored for logo_front:

• Adding "Accept: text/html" to the HTTP header.*__ In this case, the endpoint will return a default image if nothing is defined. Will return an image stream when a custom or default image is found.

curl "https://play.dhis2.org/demo/api/33/staticContent/logo_front"
  -H "Accept: text/html" -L -u admin:district

• Adding "Accept: application/json" to the HTTP header.*__ With this parameter set, the endpoint will never return a default image if the custom logo is not found. Instead, an error message will be returned. When the custom image is found this endpoint will return a JSON response containing the path/URL to the respective image.

curl "https://play.dhis2.org/demo/api/33/staticContent/logo_front"
  -H "Accept: application/json" -L -u admin:district

Success and error messages will look like this:

{
  "images": {
    "png": "http://localhost:8080/dhis/api/staticContent/logo_front"
  }
}

{
  "httpStatus": "Not Found",
  "httpStatusCode": 404,
  "status": "ERROR",
  "message": "No custom file found."
}

To use custom logos, you need to enable the corresponding system settings by setting it to true. If the corresponding setting is false, the default logo will be served.

UI customization¶

To customize the UI of the DHIS2 application you can insert custom JavaScript and CSS styles through the files resource.

POST GET DELETE /api/33/files/script
POST GET DELETE /api/33/files/style

The JavaScript and CSS content inserted through this resource will be loaded by the DHIS2 web application. This can be particularly useful in certain situations:

• Overriding the CSS styles of the DHIS2 application, such as the login page or main page.

• Defining JavaScript functions which are common to several custom data entry forms and HTML-based reports.

• Including CSS styles which are used in custom data entry forms and HTML-based reports.

Javascript¶

To insert Javascript from a file called script.js you can interact with the files/script resource with a POST request:

curl --data-binary @script.js "localhost/api/33/files/script"
  -H "Content-Type:application/javascript" -u admin:district

Note that we use the --data-binary option to preserve formatting of the file content. You can fetch the JavaScript content with a GET request:

/api/33/files/script

To remove the JavaScript content you can use a DELETE request.

CSS¶

To insert CSS from a file called style.css you can interact with the files/style resource with a POST-request:

curl --data-binary @style.css "localhost/api/33/files/style"
  -H "Content-Type:text/css" -u admin:district

You can fetch the CSS content with a GET-request:

/api/33/files/style

To remove the JavaScript content you can use a DELETE request.