Settings and configuration¶

Configurações do sistema¶

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

Como alternativa, você pode especificar a chave como um parâmetro de consulta:

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

If a key is not found or marked confidential then a 404 response will be returned like so:

{
    "httpStatus": "Not Found",
    "httpStatusCode": 404,
    "status": "ERROR",
    "message": "Setting does not exist or is marked as confidential",
    "errorCode": "E1005"
}

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

Você pode recuperar todas as configurações do sistema com uma solicitação GET:

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

A prioridade para chaves traduzíveis é a seguinte:

localidade especificada> localidade da IU padrão do usuário> valor padrão

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 =

As configurações de sistema disponíveis estão listadas abaixo.

Configurações do Usuário¶

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.

As configurações de sistema disponíveis estão listadas abaixo.

Configuração¶

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 / configuração

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 allowlist configuration you can make a POST request with an array of URLs to allowlist as payload using "application/json" as content-type, for instance:

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

GET POST /api/33/configuration/corsAllowlist

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.

Conta de serviço do Google¶

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.

Isso pressupõe que uma conta de serviço do Google foi definida e configurada para DHIS2. Consulte o guia de instalação para obter mais informações.

Conteúdo estático¶

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>

Exemplo de solicitação para fazer upload de logo.png para a chave logo_front:

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>

Exemplo de solicitações para recuperar o arquivo armazenado para 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

As mensagens de sucesso e de erro serão assim:

{
  "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.

Personalização da IU¶

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.

Login App customization¶

The Settings App allows users to define a variety of elements (text, logo, flag) that can be used to customize the login page of DHIS2. Additionally, it is possible to choose between two preconfigured layouts (the default and a sidebar layout).

If needed, the login app's styling and layout can be further customized by uploading an HTML template (also definable in the settings app). This HTML template replaces certain elements (based on ID); the reserved IDs are listed in the table below. In this way, it is possible to combine custom styling (using css) and custom layout (using HTML) to change the look of the login app. The custom template does not support custom scripts, and script tags will be removed from any uploaded template.

To create a custom template, it is recommended to start with one of the existing templates (these are available for download from within the login app at the extension dhis-web-login/#download).

The appearance of the login dialog can also be modified by defining css variables within the HTML template. The following css variables are available for customization:

--form-container-margin-block-start
--form-container-margin-block-end
--form-container-margin-inline-start, auto
--form-container-margin-inline-end
--form-container-default-width
--form-container-padding
--form-container-background-color
--form-container-box-border-radius
--form-container-box-shadow
--form-container-font-color
--form-title-font-size
--form-title-font-weight
--form-container-title-color

You can reset the login page theme using the API by making a POST request to /api/41/systemSettings/loginPageLayout including the loginPageLayout DEFAULT or SIDEBAR value in the request body, where content type is set to "text/plain". As an example, you can use curl like this:

curl "play.im.dhis2.org/stable-2-41-0/api/41/systemSettings/loginPageLayout" -d "DEFAULT" -H "Content-Type: text/plain" -u admin:district