1.57 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/26/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/26/systemSettings/my-key" -d "My long value"
  -H "Content-Type: text/plain" -u admin:district -v

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"
}

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/26/systemSettings/my-key

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

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

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

curl "play.dhis2.org/demo/api/26/systemSettings?key=keyApplicationNotification&key=keyApplicationIntro"
  -H "Content-Type: application/json" -u admin:district -v

You can retrieve all system settings with a GET request:

/api/26/systemSettings

To delete a system 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.

System settings
Key Description
keyMessageEmailNotification Send email notification for messages
keyMessageSmsNotification Send sms notification for messages
keyUiLocale Locale for the user interface
keyDbLocale Locale for the database
keyAnalysisDisplayProperty The property to display in analysis. Default: “name”
keyCurrentDomainType Not yet in use
keyAutoSaveCaseEntryForm Autosave case entry forms
keyAutoSaveDataEntryForm Autosave data entry forms
keyTrackerDashboardLayout Used by tracker capture
keyAutoSavetTrackedEntityForm Autosave tracked entity forms
applicationTitle The application title. Default: “DHIS2”
keyApplicationIntro The application introduction
keyApplicationNotification Application notification
keyApplicationFooter Application left footer
keyApplicationRightFooter Application right footer
keyFlag Application flag
keyFlagImage Flag used in dashboard menu
startModule The startpage of the application. Default: “dhis-web-dashboard-integration”
factorDeviation Data analysis standard deviation factor. Default: “2d”
keyEmailHostName Email server hostname
keyEmailPort Email server port
keyEmailTls Use TLS. Default: “true”
keyEmailSender Email sender
keyEmailUsername Email server username
keyEmailPassword Email server password
keyInstanceBaseUrl The base url of the application instance
keySmsConfig SMS configuration
keyCacheStrategy Cache strategy. Default: “CACHE_6AM_TOMORROW”
keyCacheability PUBLIC or PRIVATE. Determines if proxy servers are allowed to cache data or not.
phoneNumberAreaCode Phonenumber area code
multiOrganisationUnitForms Enable multi-organisation unit forms. Default: “false”
keyAccountRecovery Enable user account recovery. Default: “false”
googleAnalyticsUA Google Analytic UA key for tracking site-usage
credentialsExpires Require user account password change. Default: “0” (Never)
keySelfRegistrationNoRecaptcha Do not require recaptcha for self registration. Default: “false”
recaptchaSecret Google API recaptcha secret. Default: dhis2 play instance API secret, but this will only works on you local instance and not in production.
recaptchaSite Google API recaptcha site. Default: dhis2 play instance API site, but this will only works on you local instance and not in production.
keyOpenIdProvider OpenID provider
keyCanGrantOwnUserAuthorityGroups Allow users to grant own user roles. Default: “false”
keyRespectMetaDataStartEndDatesInAnalyticsTableExport When “true”, analytics will skip data not within category option’s start and end dates. Default: “false”
keyCacheAnalyticsDataYearThreshold Analytics data older than this value (in years) will always be cached. “0” disabled this setting. Default: 0
analyticsFinancialYearStart Set financial year start. Default: October
keyIgnoreAnalyticsApprovalYearThreshold “0” check approval for all data. “-1” disable approval checking. “1” or higher checks approval for all data that is newer than “1” year.
keyAnalyticsMaxLimit Maximum number of analytics recors. Default: “50000”
keyAnalyticsMaintenanceMode Put analytics in maintenance mode. Default: “false”
keyDatabaseServerCpus Number of database server CPUs. Default: “0” (Automatic)
helpPageLink Link to help page. Default: " https://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html
keyAcceptanceRequiredForApproval Acceptance required before approval. Default: “false”
keySystemNotificationsEmail Where to email system notifications
keyAnalysisRelativePeriod Default relative period for analysis. Default: “LAST_12_MONTHS”
keyRequireAddToView Require authority to add to view object lists. Default: “false”
keyAllowObjectAssignment Allow assigning object to related objects during add or update. Default: “false”
keyUseCustomLogoFront Enables the usage of a custom logo on the front page. Default: “false”
keyUseCustomLogoBanner Enables the usage of a custom banner on the website. Default: “false”
keyDataImportStrictPeriods Require periods to match period type of data set. Default: “false”
keyDataImportStrictCategoryOptionCombos Require category option combos to match category combo of data element. Default: “false”
keyDataImportStrictOrganisationUnits Require organisation units to match assignment of data set. Default: “false”
keyDataImportStrictAttributeOptionsCombos Require attribute option combis to match category combo of data set. Default: “false”
keyDataImportRequireCategoryOptionCombo Require category option combo to be specified. Default: “false”
keyDataImportRequireAttributeOptionCombo Require attribute option combo to be specified. Default: “false”
keyCustomJs Custom JavaScript to be used on the website
keyCustomCss Custom CSS to be used on the website
keyCalendar The calendar type. Default: “iso8601”.
keyDateFormat The format in which dates should be displayed. Default: “yyyy-MM-dd”.
appStoreUrl The url used to point to the app store. Default: “https://www.dhis2.org/appstore”
keyStyle The style used on the DHIS2 webpages. Default: “light_blue/light_blue.css”.
keyRemoteInstanceUrl Url used to connect to remote instance
keyRemoteInstanceUsername Username used to connect to remote DHIS2 instance
keyRemoteInstancePassword Password used to connect to remote DHIS2 instance
keyMapzenSearchApiKey Key for the Mapzen geo search API
keyFileResourceRetentionStrategy Determines how long file resources associated with deleted or updated values are kept. NONE, THREE_MONTHS, ONE_YEAR, or FOREVER.