DHIS2 DataValueSets GET and POST methods

Data values

This section is about sending and reading data values.

/api/dataValueSets

Sending data values

A common use-case for system integration is the need to send a set of data values from a third-party system into DHIS. In this example we will use the DHIS2 demo on http://play.dhis2.org/demo as basis and we recommend that you follow the provided links with a web browser while reading (log in with admin/district as username/password). We assume that we have collected case-based data using a simple software client running on mobile phones for the Mortality <5 years data set in the community of Ngelehun CHC (in Badjia chiefdom, Bo district) for the month of January 2014. We have now aggregated our data into a statistical report and want to send that data to the national DHIS2 instance.

The resource which is most appropriate for our purpose of sending data values is the dataValueSets resource. A data value set represents a set of data values which have a logical relationship, usually from being captured off the same data entry form. We follow the link to the HTML representation which will take us to http://play.dhis2.org/demo/api/24/dataValueSets. The format looks like this:


  
  
  


JSON is supported in this format:

{
  "dataSet": "dataSetID",
  "completeDate": "date",
  "period": "period",
  "orgUnit": "orgUnitID",
  "attributeOptionCombo", "aocID",
  "dataValues": [
    { "dataElement": "dataElementID", "categoryOptionCombo": "cocID", "value": "1", "comment": "comment1" },
    { "dataElement": "dataElementID", "categoryOptionCombo": "cocID", "value": "2", "comment": "comment2" },
    { "dataElement": "dataElementID", "categoryOptionCombo": "cocID", "value": "3", "comment": "comment3" }
  ]
}

CSV is supported in this format:

"dataelement","period","orgunit","catoptcombo","attroptcombo","value","storedby","lastupd","comment"
"dataElementID","period","orgUnitID","cocID","aocID","1","username","2015-04-01","comment1"
"dataElementID","period","orgUnitID","cocID","aocID","2","username","2015-04-01","comment2"
"dataElementID","period","orgUnitID","cocID","aocID","3","username","2015-04-01","comment3"

Note: Please refer to the date and period section above for time formats.

From the example we can see that we need to identify the period, the data set, the org unit (facility) and the data elements for which to report.

In JSON format: { "dataSet": "iReVg2xgFPL", "completeDate": "2018-06-06", "period": "201712", "orgUnit": "bVo3BRA2D2a", "dataValues": [ { "dataElement": "ta8v9gj6aQC", "value": "10" }, { "dataElement": "yQfHIwxvCmb", "value": "20" }, { "dataElement": "CRueZPFX52M", "value": "30" } ] } Live Example: API: http://103.247.238.86:8081/dhis28/api/dataValueSets JSON Payload: { "dataSet": "iReVg2xgFPL", //Monthly eLMIS Dataset-final "completeDate": "2018-05-13", "period": "201801", "orgUnit": "WPqHGtwerEu", // Jhalokati Civil Surgeons Office, Jhalokati "dataValues": [ { "dataElement": "ta8v9gj6aQC", "value": "100" }, { "dataElement": "yQfHIwxvCmb", "value": "200" }, { "dataElement": "CRueZPFX52M", "value": "300" } ] } Result: { "responseType": "ImportSummary", "status": "SUCCESS", "importOptions": { "idSchemes": {}, "dryRun": false, "async": false, "importStrategy": "CREATE_AND_UPDATE", "mergeMode": "REPLACE", "reportMode": "FULL", "skipExistingCheck": false, "sharing": false, "skipNotifications": false, "datasetAllowsPeriods": false, "strictPeriods": false, "strictCategoryOptionCombos": false, "strictAttributeOptionCombos": false, "strictOrganisationUnits": false, "requireCategoryOptionCombo": false, "requireAttributeOptionCombo": false }, "description": "Import process completed successfully", "importCount": { "imported": 3, "updated": 0, "ignored": 0, "deleted": 0 }, "dataSetComplete": "2018-05-13" } Result in Data Entry App:

To perform functional testing we will use the cURL tool which provides an easy way of transferring data using HTTP. First we save the data value set XML content in a file called datavalueset.xml . From the directory where this file resides we invoke the following from the command line:

curl -d @datavalueset.xml "https://play.dhis2.org/demo/api/26/dataValueSets" 
  -H "Content-Type:application/xml" -u admin:district -v

For sending JSON content you must set the content-type header accordingly:

curl -d @datavalueset.json "https://play.dhis2.org/demo/api/26/dataValueSets" 
  -H "Content-Type:application/json" -u admin:district -v


The command will dispatch a request to the demo Web API, set application/xml as the content-type and authenticate using admin/district as username/password. If all goes well this will return a 200 OK HTTP status code. You can verify that the data has been received by opening the data entry module in DHIS2 and select the org unit, data set and period used in this example.

The API follows normal semantics for error handling and HTTP status codes. If you supply an invalid username or password, 401 Unauthorized is returned. If you supply a content-type other than application/xml, 415 Unsupported Media Type is returned. If the XML content is invalid according to the DXF namespace, 400 Bad Request is returned. If you provide an invalid identifier in the XML content, 409 Conflict is returned together with a descriptive message.

Sending bulks of data values

The previous example showed us how to send a set of related data values sharing the same period and organisation unit. This example will show us how to send large bulks of data values which don't necessarily are logically related.

Again we will interact with the with http://play.dhis2.org/demo/api/24/dataValueSets resource. This time we will not specify the dataSet and completeDate attributes. Also, we will specify the period and orgUnit attributes on the individual data value elements instead of on the outer data value set element. This will enable us to send data values for various periods and org units:


  
  
  
  


In JSON format:

{
  "dataValues": [
    { "dataElement": "f7n9E0hX8qk", "period": "201401", "orgUnit": "DiszpKrYNg8", "value": "12" },
    { "dataElement": "f7n9E0hX8qk", "period": "201401", "orgUnit": "FNnj3jKGS7i", "value": "14" },
    { "dataElement": "f7n9E0hX8qk", "period": "201402", "orgUnit": "DiszpKrYNg8", "value": "16" },
    { "dataElement": "f7n9E0hX8qk", "period": "201402", "orgUnit": "Jkhdsf8sdf4", "value": "18" }
  ]
}

In CSV format:

"dataelement","period","orgunit","categoryoptioncombo","attributeoptioncombo","value"
"f7n9E0hX8qk","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","1"
"Ix2HsbDMLea","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","2"
"eY5ehpbEsB7","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","3"

We test by using cURL to send the data values in XML format:

curl -d @datavalueset.xml "https://play.dhis2.org/demo/api/26/dataValueSets" 
  -H "Content-Type:application/xml" -u admin:district -v

Note that when using CSV format you must use the binary data option to preserve the line-breaks in the CSV file:

curl --data-binary @datavalueset.csv "https://play.dhis2.org/demo/24/api/dataValueSets" 
  -H "Content-Type:application/csv" -u admin:district -v

The data value set resource provides an XML response which is useful when you want to verify the impact your request had. The first time we send the data value set request above the server will respond with the following import summary:


  
  false

This message tells us that 3 data values were imported, 1 data value was updated while zero data values were ignored. The single update comes as a result of us sending that data value in the previous example. A data value will be ignored if it references a non-existing data element, period, org unit or data set. In our case this single ignored value was caused by the last data value having an invalid reference to org unit. The data set complete element will display the date of which the data value set was completed, or false if no data element attribute was supplied.

Data Value Set API, GET and POST Method


To get data values from your datasets:

/api/dataValueSets
/api/dataValueSets.json?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8

Example:
API: 

http://103.247.238.86:8081/dhis28/api/dataValueSets.json?dataSet=iReVg2xgFPL&period=201801&orgUnit=WPqHGtwerEu

Result: 
{
    "dataSet": "iReVg2xgFPL",
    "completeDate": "2018-05-12T18:00:00.000+0000",
    "period": "201801",
    "orgUnit": "WPqHGtwerEu",
    "dataValues": [
        {
            "dataElement": "ta8v9gj6aQC",
            "period": "201801",
            "orgUnit": "WPqHGtwerEu",
            "categoryOptionCombo": "dCWAvZ8hcrs",
            "attributeOptionCombo": "dCWAvZ8hcrs",
            "value": "100",
            "storedBy": "julhas",
            "created": "2018-05-09T06:21:34.000+0000",
            "lastUpdated": "2018-05-09T06:21:34.000+0000",
            "followUp": false
        },
        {
            "dataElement": "yQfHIwxvCmb",
            "period": "201801",
            "orgUnit": "WPqHGtwerEu",
            "categoryOptionCombo": "dCWAvZ8hcrs",
            "attributeOptionCombo": "dCWAvZ8hcrs",
            "value": "200",
            "storedBy": "julhas",
            "created": "2018-05-09T06:21:34.000+0000",
            "lastUpdated": "2018-05-09T06:21:34.000+0000",
            "followUp": false
        }
......
}

Data Value Set Import

Data Value Set JSON Format
       {
          "dataSet": "pBOMPrpg1QX",
          "completeDate": "2014-02-03",
          "period": "201401",
          "orgUnit": "DiszpKrYNg8",
          "dataValues": [ {
          "dataElement": "f7n9E0hX8qk", "value": "1"
          }, {
          "dataElement": "Ix2HsbDMLea", "value": "2"
          }, {
          "dataElement": "eY5ehpbEsB7", "value": "3"
          } ]
       }         

          POST /api/dataValueSets?idScheme=code&dataElementIdScheme=id
          POST /api/dataValueSets?importStrategy=create

        Import with curl:

          ● curl -d @dvs.json "http://localhost/api/dataValueSets" -H "Content-Type:application/json" -u admin:district -v