1.49 System resource

The system resource provides you with convenient information and functions. The system resource can be found at /api/system .

1.49.1 Generate identifiers

To generate valid, random DHIS2 identifiers you can do a GET request to this resource:

/api/26/system/id?limit=3

The limit query parameter is optional and indicates how many identifiers you want to be returned with the response. The default is to return one identifier. The response will contain a JSON object with a array named codes, similar to this:

{
  "codes": [
    "Y0moqFplrX4",
    "WI0VHXuWQuV",
    "BRJNBBpu4ki"
  ]
}

The DHIS2 UID format has these requirements:

  • 11 characters long.

  • Alphanumeric characters only, ie. alphabetic or numeric characters (A-Za-z0-9).

  • Start with an alphabetic character (A-Za-z).

1.49.2 View system information

To get information about the current system you can do a GET request to this URL:

/api/26/system/info

JSON and JSONP response formats are supported. The system info response currently includes the below properties. Note that if the user who is requesting this resource does not have full authority in the system then only the first seven properties will be included, as this information is security sensitive.

{
    contextPath: "http://yourdomain.com",
    userAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/29.0.1547.62 Safari/537.36",
    version: "2.13-SNAPSHOT",
    revision: "11852",
    buildTime: "2013-09-01T21:36:21.000+0000",
    serverDate: "2013-09-02T12:35:54.311+0000",
    environmentVariable: "DHIS2_HOME",
    javaVersion: "1.7.0_06",
    javaVendor: "Oracle Corporation",
    javaIoTmpDir: "/tmp",
    javaOpts: "-Xms600m -Xmx1500m -XX:PermSize=400m -XX:MaxPermSize=500m",
    osName: "Linux",
    osArchitecture: "amd64",
    osVersion: "3.2.0-52-generic",
    externalDirectory: "/home/dhis/config/dhis2",
    databaseInfo: {
        type: "PostgreSQL",
        name: "dhis2",
        user: "dhis",
        spatialSupport: false
    },
    memoryInfo: "Mem Total in JVM: 848 Free in JVM: 581 Max Limit: 1333",
    cpuCores: 8
}

To get information about the system context ( contextPath and userAgent ) only you can do a GET request to the below URL. JSON and JSONP response formats are supported:

/api/26/system/context

1.49.3 Check if username and password combination is correct

To check if some user credentials (a username and password combination) is correct you can make a GET request to the following resource using basic authentication :

/api/26/system/ping

You can detect the outcome of the authentication by inspecting the HTTP status code of the response header. The meaning of the possible status codes are listed below. Note that this applies to Web API requests in general.

HTTP Status codes
HTTP Status code Description Outcome
200 OK Authentication was successful
302 Found No credentials was supplied with the request - no authentication took place
401 Unauthorized The username and password combination was incorrect - authentication failed

1.49.4 View asynchronous task status

Several tasks which typically take a significant time to complete can be performed asynchronously. After initiating an async task you can poll the status through the system/tasks resource by suppling the task category of interest.

When polling for the task status you need to authenticate as the same user which initiated the task. The following task categories are supported.

Task categories
Identifier Description
ANALYTICSTABLE_UPDATE Generation of the analytics tables.
RESOURCETABLE_UPDATE Generation of the resource tables.
MONITORING Processing of data surveillance/monitoring validation rules.
DATAVALUE_IMPORT Import of data values.
EVENT_IMPORT Import of events.
METADATA_IMPORT Import of metadata.
DATAINTEGRITY Processing of data integrity checks.

You can poll tasks through a GET request to the system tasks resource:

/api/26/system/tasks/{task-category-id}

A request to poll for the status of a data value import task looks like this:

/api/26/system/tasks/DATAVALUE_IMPORT

The response will provide information about the status, such as the notification level, category, time and status. The completed property indicates whether the process is considered to be complete.

[
    {
        "uid": "hpiaeMy7wFX",
        "level": "INFO",
        "category": "DATAVALUE_IMPORT",
        "time": "2015-09-02T07:43:14.595+0000",
        "message": "Import done",
        "completed": true
    }
]

1.49.5 Get appearance information

You can retrieve the available flag icons in JSON format with a GET request:

/api/26/system/flags

You can retrieve the available UI styles in JSON format with a GET request:

/api/26/system/styles