Nastavení a konfigurace¶

Nastavení systému¶

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

Alternativně můžete zadat klíč jako parametr dotazu:

/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

Všechna nastavení systému můžete načíst pomocí požadavku 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.

Priorita překladatelných klíčů je následující:

zadané národní prostředí > národní prostředí uživatelského rozhraní výchozího uživatele > výchozí hodnota

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.

Chcete-li odstranit pouze konkrétní překlad přeložitelného klíče, měla by se použít stejná adresa URL jako pro přidání překladu a měla by být uvedena prázdná hodnota:

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

Dostupná nastavení systému jsou uvedena níže.

Tabulka: Nastavení systému

Uživatelské nastavení¶

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

Uživatelská nastavení, která uživatel nenastaví, se vrátí k ekvivalentnímu systémovému nastavení. Chcete-li vrátit pouze hodnoty explicitně nastavené uživatelem, můžete k výše uvedené adrese URL připojit ?useFallback=false, například takto:

/api/33/userSettings?useFallback=false

Chcete-li uložit nebo aktualizovat nastavení pro aktuálně ověřeného uživatele, můžete zadat požadavek POST na následující adresu 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.

Dostupná nastavení systému jsou uvedena níže.

Tabulka: Uživatelská nastavení

Konfigurace¶

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 /api/configuration/dataOutputPeriodTypes

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.

Tabulka: Hodnoty konfigurace

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

Tokeny¶

Prostředek tokeny poskytuje přístupové tokeny k různým službám.

Účet služby 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.

Tabulka: Odezva tokenu

To předpokládá, že účet služby Google byl nastaven a nakonfigurován pro DHIS2. Další informace najdete v instalační příručce.

Statický obsah¶

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

Tabulka: Klíče statického obsahu

Chcete-li nahrát soubor, odešlete soubor s požadavkem POST na adresu:

POST /api/33/staticContent/<key>

Příklad požadavku na nahrání logo.png do klíče 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

Nahrání více souborů se stejným klíčem přepíše stávající soubor. Tímto způsobem se při načtení souboru pro daný klíč vrátí pouze poslední nahraný soubor.

To retrieve a logo, you can GET the following:

GET /api/33/staticContent/<key>

Příklad požadavků na načtení souboru uloženého pro 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

Úspěšné a chybové zprávy budou vypadat takto:

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

Přizpůsobení uživatelského rozhraní¶

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 přihlašovací stránka nebo hlavní stránka.

• Defining JavaScript functions which are common to several custom formuláře pro zadávání dat a zprávy založené na HTML.

• 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