Sending large bulks of data values

Sending large bulks of data values @@ -624,7 +624,7 @@ <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

+ 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"/> @@ -721,9 +721,7 @@ 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

+ 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 @@ -783,9 +781,8 @@ 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

+ 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. @@ -892,10 +889,10 @@ </users> </message> To test this we save the XML content into a file called message.xml. We use cURL to dispatch the message the the DHIS 2 demo instance where we indicate that the content-type is XML and authenticate as the admin user: -

curl -d @message.xml "http://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/xml" -u admin:district -X POST -v

+ curl -d @message.xml "http://apps.dhis2.org/demo/api/messageConversations" -H "Content-Type:application/xml" -u admin:district -X POST -v If all is well we receive a 201 Created HTTP status code. Also note that we receive a Location HTTP header which value informs us of the URL of the newly created message conversation resource - this can be used by a consumer to perform further action. We will now pretend to be the mobile user and read the message which was just sent by dispatching a GET request to the messageConversations resource. We supply an Accept header with application/xml as the value to indicate that we are interested in the XML resource representation and we authenticate as the mobile user: - curl "http://apps.dhis2.org/demo/api/messageConversations" -H "Accept:application/xml" -u mobile:district -X GET -v + curl "http://apps.dhis2.org/demo/api/messageConversations" -H "Accept:application/xml" -u mobile:district -X GET -v In response we get the following XML: <messageConversations xmlns="http://dhis2.org/schema/dxf/2.0" link="http://apps.dhis2.org/demo/api/messageConversations"> @@ -905,18 +902,89 @@ link="http://apps.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2"/> </messageConversations> From the response we are able to read the identifier of the newly sent message which is ZjHHSjyyeJ2. Note that the link to the specific resource is embedded and can be followed in order to read the full message. From the description at we learned that we can reply directly to an existing message conversation once we know the URL by including the message text as the request payload (body). We are now able to construct a URL for sending our reply: -

curl -d "Yes the Mortality data set has been reported" "http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2" -H "Content-Type:text/plain" -u mobile:district -X POST -v

+ curl -d "Yes the Mortality data set has been reported" "http://apps.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2" -H "Content-Type:text/plain" -u mobile:district -X POST -v If all went according to plan you will receive a 200 OK status code.

+ Interpretations + For certain analysis-related resources in DHIS, like charts, maps and report tables, one + can write and share a data interpretation. An interpretation is simply a link to the the + relevant resource together with a text expressing some insight about the data. Interpretations + access control follows the access given for the interpreted object. +

+ Reading interpretations + To read interpretations we will interact with the api/interpretations resource. The output in JSON response format could look + like below (use e.g. api/interpretations.json): + { + "interpretations": [{ + "created": "2013-10-07T11:37:19.273+0000", + "lastUpdated": "2013-10-07T12:08:58.028+0000", + "type": "map", + "href": "http://apps.dhis2.org/demo/api/interpretations/d3BukolfFZI", + "id": "d3BukolfFZI" + }, { + "created": "2013-05-30T10:24:06.181+0000", + "lastUpdated": "2013-05-30T10:25:08.066+0000", + "type": "reportTable", + "href": "http://apps.dhis2.org/demo/api/interpretations/XSHiFlHAhhh", + "id": "XSHiFlHAhhh" + }, { + "created": "2013-05-29T14:47:13.081+0000", + "lastUpdated": "2013-05-29T14:47:13.081+0000", + "type": "chart", + "href": "http://apps.dhis2.org/demo/api/interpretations/kr4AnZmYL43", + "id": "kr4AnZmYL43" + }] +} + An interpretation contains properties for identifier, date of creation and date of last + modification. The type property refers to the kind of object is being interpretated, and is + useful to show an appriate visual indication in a client. Valid options are "chart", "map", + "reportTable" and "dataSetReport". By following the link given in the "href" property one + can get more information about a specific interpretation. In the case of the map + interpretation, the response will look like this: + { + "created": "2013-10-07T11:37:19.273+0000", + "lastUpdated": "2013-10-07T12:08:58.028+0000", + "map": { + "name": "ANC: ANC 2 Coverage", + "created": "2012-11-13T12:01:21.918+0000", + "lastUpdated": "2012-11-13T12:01:21.918+0000", + "href": "http://apps.dhis2.org/demo/api/maps/bhmHJ4ZCdCd", + "id": "bhmHJ4ZCdCd" + }, + "text": "We can see that the ANC 2 coverage of Kasonko and Lei districts are under 40 %. What could be the cause for this?", + "comments": [{ + "created": "2013-10-07T12:08:58.026+0000", + "lastUpdated": "2013-10-07T12:08:58.026+0000", + "text": "Due to the rural environment, getting women to the facilities is a challenge. Outreach campaigns might be helpful.", + "href": "http://apps.dhis2.org/demo/api/null/iB4Etq8yTE6", + "id": "iB4Etq8yTE6" + }], + "type": "map", + "href": "http://apps.dhis2.org/demo/api/interpretations/d3BukolfFZI", + "id": "d3BukolfFZI" +} + The map interpretation contains identifier and type information in the "id" and "type" + properties. The interpretation text is available in the "text" property and references to + any comments in the "comments" list. It also contains information about the interpreted + object, in this case the "map" property. Note that you can follow the link to the actual map + through the "href" property. For all analytical objects you can append /data to the URL to retrieve the data associated with the + resource, as apposed to the meta-data. As an example, by following the map link and + appending /data one can retrieve a PNG (image) representation of the thematic map through + the following URL: + http://apps.dhis2.org/demo/api/maps/bhmHJ4ZCdCd/data +

Writing interpretations - For certain analysis-related resources in DHIS, like charts and report tables, one can share a data interpretation. An interpretation is simply a link to the the relevant resource together with a text expressing some insight about the data. Currently an interpretation can be viewed by all users in the system. We will start by writing an interpretation for the chart with identifier EbRN2VIbPdV. To write chart interpretations we will interact with the resource. The interpretation will be the request body. Based on this we can put together the following request using cURL: -

curl -d "This chart shows a significant ANC 1-3 dropout" "http://apps.dhis2.org/demo/api/interpretations/chart/EbRN2VIbPdV" -H "Content-Type:text/plain" -u admin:district -v

+ curl -d "This chart shows a significant ANC 1-3 dropout" "http://apps.dhis2.org/demo/api/interpretations/chart/EbRN2VIbPdV" -H "Content-Type:text/plain" -u admin:district -v Second we will write a comment on the interpretation we just wrote. By looking at the interpretation response you will see that a Location header is returned. This header tells us the URL of the newly created interpretation and from that we can read its identifier. This identifier is randomly generated so you will have to replace the one in the command below with your own. To write a comment we can interact with the like this: -

curl -d "An intervention is needed" "http://apps.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comment" -H "Content-Type:text/plain" -u admin:district -v

+ curl -d "An intervention is needed" "http://apps.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comment" -H "Content-Type:text/plain" -u admin:district -v You can also write interpretations for report tables in a similar way by interacting with the . For report tables you can also provide an optional ou query parameter to supply an organisation unit identifier in the case where the report table has an organisation unit report parameter: -

curl -d "This table reveals poor data quality" "http://apps.dhis2.org/demo/api/interpretations/reportTable/xIWpSo5jjT1?ou=O6uvpzGd5pu" -H "Content-Type:text/plain" -u admin:district -v

+ curl -d "This table reveals poor data quality" "http://apps.dhis2.org/demo/api/interpretations/reportTable/xIWpSo5jjT1?ou=O6uvpzGd5pu" -H "Content-Type:text/plain" -u admin:district -v +