Data values

+ Data values + This section is about sending and reading data values. +

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 DHIS 2 demo on as basis and we recommend that you follow the provided @@ -437,6 +440,264 @@ In a real-world scenario, looking up identifiers, constructing and dispatching XML messages would be the task of the client software application. This software would probably interact with the more machine-friendly XML and JSON resource representations and not the human-friendly HTML representations like we did in this example. Developing creative and robust consumers of the Web API services begins here.

+ Sending large 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 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: + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0"> + <dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="DiszpKrYNg8" value="12"/> + <dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="FNnj3jKGS7i" value="14"/> + <dataValue dataElement="f7n9E0hX8qk" period="201202" orgUnit="DiszpKrYNg8" value="16"/> + <dataValue dataElement="f7n9E0hX8qk" period="201202" orgUnit="Jkhdsf8sdf4" value="18"/> +</dataValueSet> + We test by using cURL to send the data values: + curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -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: + <importSummary> + <dataValueCount imported="2" updated="1" ignored="1"/> + <dataSetComplete>false</dataSetComplete> +</importSummary> + 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. + The import process can be customized using a set of import parameters: + + Import parameters + + + + + Parameter + + + Values (default first) + + + Description + + + + + + dataElementIdScheme + id | name | code + Which property on the data element object to reference from the XML attribute + + + orgUnitIdScheme + id | name | code + Which property on the org unit object to reference from the XML attribute + + + dryRun + false | true + Whether to save changes on the server or just return the import summary + + + importStrategy + new_and_updates | new | updates + Save objects of all, new or update import status on the server + + + +

+ All parameters are optional and can be supplied as query parameters in the request URL like this: + http://apps.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name&dryRun=true&importStrategy=new + They can also be supplied as XML attributes on the data value set element like below. XML attributes will override query string parameters. + <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataElementIdScheme="code" + orgUnitIdScheme="name" dryRun="true" importStrategy="new"> + .. +</dataValueSet> + Regarding the id schemes, by default the identifiers used in the XML messages refer to the + DHIS stable object identifiers. In certain interoperability situations we might experience + that the external system decides the identifiers of the objects. In that case we can use the + code property of the organisation unit and data element + objects to set fixed identifiers dictated by the other system. When importing data values we + hence need to reference the code property instead of the identfier property, and can do so + using the dataElementIScheme and orgUnitIdScheme paramaters. +

+ Sending individual data values + This example will show how to send individual data values to be saved in a request. This + can be achieved by sending a POST request to the dataValues resource: + http://apps.dhis2.org/demo/api/dataValues + The following query parameters are supported for this resource: + + Data values query parameters + + + + + + + Query parameter + Required + Description + + + + + de + Yes + Data element identifier + + + pe + Yes + Period identifier + + + ou + Yes + Organisation unit identifier + + + co + No + Category option combo identifier, default will be used if omitted + + + cc + No (must combine with cp) + Attribute combo identifier + + + cp + No (must combine with cc) + Attribute option identifiers, separated with ; for multiple values + + + value + No + Data value + + + comment + No + Data comment + + + followUp + No + Follow up on data value, will toggle the current boolean value + + + +

+ If any of the identifiers given are invalid, if the data value or comment are invalid or + if the data is locked, the response will contain the 409 + Conflict status code and descriptive text message. If the operation lead to a + saved or updated value, 200 OK will be returned. An example + of a request looks like this: + curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12" -X POST -u admin:district -v + This resource also allows a special syntax for associating the value to an attribute + option combination. This can be done by sending the identifier of the attribute combination, + together with the identifier(s) of the attribute option(s) which the value represents within + the combination. An example looks like this: + curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&ou=DiszpKrYNg8&pe=201308&cc=dzjKKQq0cSO&cp=wbrDrL2aYEc;btOyqprQ9e8&value=26" -X POST -u admin:district -v +

+ Reading data values + This section explains how to retrieve data values from the Web API by interacting with the dataValueSets resource. Data values can currently be retrieved in XML format. Since we want to read data we will use the GET HTTP verb. We will also specify that we are interested in the XML resource representation by including an Accept HTTP header with our request. The following query parameters are required: + + Data value set query parameters + + + + + Parameter + + + Description + + + + + + dataSet + Data set identifier + + + period + Period identifier in ISO format + + + orgUnit + Organisation unit identifier + + + +

+ It is assumed that we have posted data values to DHIS according to the previous section called "Sending data values". We can now put together our request and send it using cURL: + curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/xml" -u admin:district -v + The response will look something like this: + HTTP/1.1 200 OK +Content-Type: application/xml + +<?xml version='1.0' encoding='UTF-8'?> +<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX" + completeDate="2012-01-02" period="201201" orgUnit="DiszpKrYNg8"> +<dataValue dataElement="eY5ehpbEsB7" period="201201" orgUnit="DiszpKrYNg8" + categoryOptionCombo="bRowv6yZOF2" value="10003"/> +<dataValue dataElement="Ix2HsbDMLea" period="201201" orgUnit="DiszpKrYNg8" + categoryOptionCombo="bRowv6yZOF2" value="10002"/> +<dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="DiszpKrYNg8" + categoryOptionCombo="bRowv6yZOF2" value="10001"/> +</dataValueSet> + The header tells us that the request was processed successfully and that we are receiving a response in XML format. The XML message looks familiar - it is the data values we sent in the previous section. +

+ Reading large bulks of data values + This section explains how to retrieve large bulks of data values which not necessarily + belong in a single data value set. We will, like in the previous section, interact with the + dataValueSets resource. The query parameters to use are these: + + Data value set query parameters + + + + + + Parameter + Description + + + + + dataSet + Data set identifier, can be specified multiple times + + + startDate + Start date for the time span of the values to export + + + endDate + End date for the time span of the values to export + + + orgUnit + Organisation unit identifier, can be specified multiple times + + + children + Whether to include the children in the hierarchy of the organisation + units + + + +

+ The dataSet and orgUnit parameters can be repeated in order to include multiple data sets + and organisation units. An example request looks like this: + curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31& +orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true" -H "Accept:application/xml" -u admin:district -v + You can get the response in xml and csv format. You can indicate which response format you prefer + through the Accept HTTP header like in the example above. + For xml you use application/xml; for csv you use application/csv. +

+ Events + This section is about sending and reading events. +

Sending event data values DHIS 2 supports three kinds of events: single events with no registration (also referred to as anonymous events), single event with registration and multiple events with registration. @@ -448,7 +709,7 @@ using the programs resource, an orgUnit which can be looked up using the organisationUnits resource, and a list of valid data element identifiers which - can be looked up using the dataElements resource. For + can be looked up using the dataElements resource. For events with registration, a person identifier is required, read about how to get this in the section about the person resource. For sending events to programs with multiple stages, you will need to also include @@ -467,7 +728,8 @@ <dataValue dataElement="msodh3rEMJa" value="2013-05-18" /> </dataValues> </event> - To perform some testing we can save the XML payload as a file called events.xml and send it as a POST request to the events resource in + To perform some testing we can save the XML payload as a file called events.xml and send it as a POST request to the events resource in the API using curl with the following command: curl -d @events.xml "http://apps.dhis2.org/demo/api/events" -H "Content-Type:application/xml" -u admin:district -v The same payload in JSON format looks like this: @@ -487,7 +749,8 @@ { "dataElement": "msodh3rEMJa", "value": "2013-05-18" } ] } - To send this you can save it to a file called events.json and use curl like this: + To send this you can save it to a file called events.json and use curl like this: curl -d @events.xml "localhost:8080/api/events" -H "Content-Type:application/json" -u admin:district -v We also support sending multiple events at the same time. A payload in XML format might look like this: @@ -648,300 +911,6 @@

- Sending data values using SDMX-HD - Posting a dataValueSet report formatted using the WHO SDMX-HD standard is very similar to - the dxf2 example above. The same api/dataValueSets resource is used, but the client has to - specify the Content-Type as application/sdmx+xml. - The example below shows an SDMX-HD dataValueSet: - - - -

- OpenMRS-Export - false - 2012-03-21 - -

- - - - - - - - - - - - - -]]> - One thing to note is that the SDMX-HD metadata for dataelements, orgunits and datasets are - identified using codes rather than identifiers. - Assuming these coded datasets are present in the DHIS2 server then this can be posted, for - example using the curl command below. - curl -d @sdmxdatavalueset.xml "http://{server base url}/api/dataValueSets" -H "Content-Type:application/sdmx+xml" -u admin:district -v -

- Sending large 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 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: - <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0"> - <dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="DiszpKrYNg8" value="12"/> - <dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="FNnj3jKGS7i" value="14"/> - <dataValue dataElement="f7n9E0hX8qk" period="201202" orgUnit="DiszpKrYNg8" value="16"/> - <dataValue dataElement="f7n9E0hX8qk" period="201202" orgUnit="Jkhdsf8sdf4" value="18"/> -</dataValueSet> - We test by using cURL to send the data values: - curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -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: - <importSummary> - <dataValueCount imported="2" updated="1" ignored="1"/> - <dataSetComplete>false</dataSetComplete> -</importSummary> - 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. - The import process can be customized using a set of import parameters: - - Import parameters - - - - - Parameter - - - Values (default first) - - - Description - - - - - - dataElementIdScheme - id | name | code - Which property on the data element object to reference from the XML attribute - - - orgUnitIdScheme - id | name | code - Which property on the org unit object to reference from the XML attribute - - - dryRun - false | true - Whether to save changes on the server or just return the import summary - - - importStrategy - new_and_updates | new | updates - Save objects of all, new or update import status on the server - - - -

- All parameters are optional and can be supplied as query parameters in the request URL like this: - http://apps.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name&dryRun=true&importStrategy=new - They can also be supplied as XML attributes on the data value set element like below. XML attributes will override query string parameters. - <dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataElementIdScheme="code" - orgUnitIdScheme="name" dryRun="true" importStrategy="new"> - .. -</dataValueSet> - Regarding the id schemes, by default the identifiers used in the XML messages refer to the - DHIS stable object identifiers. In certain interoperability situations we might experience - that the external system decides the identifiers of the objects. In that case we can use the - code property of the organisation unit and data element - objects to set fixed identifiers dictated by the other system. When importing data values we - hence need to reference the code property instead of the identfier property, and can do so - using the dataElementIScheme and orgUnitIdScheme paramaters. -

- Sending individual data values - This example will show how to send individual data values to be saved in a request. This - can be achieved by sending a POST request to the dataValues resource: - http://apps.dhis2.org/demo/api/dataValues - The following query parameters are supported for this resource: - - Data values query parameters - - - - - - - Query parameter - Required - Description - - - - - de - Yes - Data element identifier - - - pe - Yes - Period identifier - - - ou - Yes - Organisation unit identifier - - - co - No - Category option combo identifier, default will be used if omitted - - - cc - No (must combine with cp) - Attribute combo identifier - - - cp - No (must combine with cc) - Attribute option identifiers, separated with ; for multiple values - - - value - No - Data value - - - comment - No - Data comment - - - followUp - No - Follow up on data value, will toggle the current boolean value - - - -

- If any of the identifiers given are invalid, if the data value or comment are invalid or - if the data is locked, the response will contain the 409 - Conflict status code and descriptive text message. If the operation lead to a - saved or updated value, 200 OK will be returned. An example - of a request looks like this: - curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12" -X POST -u admin:district -v - This resource also allows a special syntax for associating the value to an attribute - option combination. This can be done by sending the identifier of the attribute combination, - together with the identifier(s) of the attribute option(s) which the value represents within - the combination. An example looks like this: - curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&ou=DiszpKrYNg8&pe=201308&cc=dzjKKQq0cSO&cp=wbrDrL2aYEc;btOyqprQ9e8&value=26" -X POST -u admin:district -v -

- Reading data values - This section explains how to retrieve data values from the Web API by interacting with the dataValueSets resource. Data values can currently be retrieved in XML format. Since we want to read data we will use the GET HTTP verb. We will also specify that we are interested in the XML resource representation by including an Accept HTTP header with our request. The following query parameters are required: - - Data value set query parameters - - - - - Parameter - - - Description - - - - - - dataSet - Data set identifier - - - period - Period identifier in ISO format - - - orgUnit - Organisation unit identifier - - - -

- It is assumed that we have posted data values to DHIS according to the previous section called "Sending data values". We can now put together our request and send it using cURL: - curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/xml" -u admin:district -v - The response will look something like this: - HTTP/1.1 200 OK -Content-Type: application/xml - -<?xml version='1.0' encoding='UTF-8'?> -<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX" - completeDate="2012-01-02" period="201201" orgUnit="DiszpKrYNg8"> -<dataValue dataElement="eY5ehpbEsB7" period="201201" orgUnit="DiszpKrYNg8" - categoryOptionCombo="bRowv6yZOF2" value="10003"/> -<dataValue dataElement="Ix2HsbDMLea" period="201201" orgUnit="DiszpKrYNg8" - categoryOptionCombo="bRowv6yZOF2" value="10002"/> -<dataValue dataElement="f7n9E0hX8qk" period="201201" orgUnit="DiszpKrYNg8" - categoryOptionCombo="bRowv6yZOF2" value="10001"/> -</dataValueSet> - The header tells us that the request was processed successfully and that we are receiving a response in XML format. The XML message looks familiar - it is the data values we sent in the previous section. -

- Reading large bulks of data values - This section explains how to retrieve large bulks of data values which not necessarily - belong in a single data value set. We will, like in the previous section, interact with the - dataValueSets resource. The query parameters to use are these: - - Data value set query parameters - - - - - - Parameter - Description - - - - - dataSet - Data set identifier, can be specified multiple times - - - startDate - Start date for the time span of the values to export - - - endDate - End date for the time span of the values to export - - - orgUnit - Organisation unit identifier, can be specified multiple times - - - children - Whether to include the children in the hierarchy of the organisation - units - - - -

- The dataSet and orgUnit parameters can be repeated in order to include multiple data sets - and organisation units. An example request looks like this: - curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt&startDate=2013-01-01&endDate=2013-01-31& -orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true" -H "Accept:application/xml" -u admin:district -v - You can get the response in xml and csv format. You can indicate which response format you prefer - through the Accept HTTP header like in the example above. - For xml you use application/xml; for csv you use application/csv. -

Reading event data values This section explains how to read out the events that have been stored in the DHIS2 instance. For more advanced uses of the event data, please see the section on event analytics. The output format from the /api/events endpoint @@ -1036,6 +1005,7 @@ /api/events?program=ID&orgUnit=ID&person=ID&startDate=2012-01-01&endDate=2012-12-31