dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #27522
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 946: Web api, put data values and events in outer sections
------------------------------------------------------------
revno: 946
committer: Lars Helge Øverland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Mon 2014-01-13 20:01:57 +0100
message:
Web api, put data values and events in outer sections
modified:
src/docbkx/en/dhis2_user_man_web_api.xml
--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription
=== modified file 'src/docbkx/en/dhis2_user_man_web_api.xml'
--- src/docbkx/en/dhis2_user_man_web_api.xml 2014-01-13 09:45:39 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2014-01-13 19:01:57 +0000
@@ -389,6 +389,9 @@
</section>
</section>
<section>
+ <title>Data values</title>
+ <para>This section is about sending and reading data values.</para>
+ <section>
<title>Sending data values</title>
<para>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 <ulink url="http://apps.dhis2.org/demo"/> as basis and we recommend that you follow the provided
@@ -437,6 +440,264 @@
<para>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.</para>
</section>
<section>
+ <title>Sending large bulks of data values</title>
+ <para>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.</para>
+ <para>Again we will interact with the with <ulink url="http://apps.dhis2.org/demo/api/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:</para>
+ <screen><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></screen>
+ <para>We test by using cURL to send the data values:</para>
+ <screen>curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v</screen>
+ <para>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<emphasis role="italic"> import summary</emphasis>:</para>
+ <screen><importSummary>
+ <dataValueCount imported="2" updated="1" ignored="1"/>
+ <dataSetComplete>false</dataSetComplete>
+</importSummary></screen>
+ <para>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.</para>
+ <para>The import process can be customized using a set of import parameters:</para>
+ <table>
+ <title>Import parameters</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ <emphasis role="italic">Parameter</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Values (default first)</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Description</emphasis>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>dataElementIdScheme</entry>
+ <entry>id | name | code</entry>
+ <entry>Which property on the data element object to reference from the XML attribute</entry>
+ </row>
+ <row>
+ <entry>orgUnitIdScheme</entry>
+ <entry>id | name | code</entry>
+ <entry>Which property on the org unit object to reference from the XML attribute</entry>
+ </row>
+ <row>
+ <entry>dryRun</entry>
+ <entry>false | true</entry>
+ <entry>Whether to save changes on the server or just return the import summary</entry>
+ </row>
+ <row>
+ <entry>importStrategy</entry>
+ <entry>new_and_updates | new | updates</entry>
+ <entry>Save objects of all, new or update import status on the server</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>All parameters are optional and can be supplied as query parameters in the request URL like this:</para>
+ <screen>http://apps.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name&dryRun=true&importStrategy=new</screen>
+ <para>They can also be supplied as XML attributes on the data value set element like below. XML attributes will override query string parameters.</para>
+ <screen><dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataElementIdScheme="code"
+ orgUnitIdScheme="name" dryRun="true" importStrategy="new">
+ ..
+</dataValueSet></screen>
+ <para>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
+ <emphasis role="italic">code</emphasis> 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.</para>
+ </section>
+ <section>
+ <title>Sending individual data values</title>
+ <para>This example will show how to send individual data values to be saved in a request. This
+ can be achieved by sending a <emphasis role="italic">POST</emphasis> request to the <emphasis
+ role="italic">dataValues</emphasis> resource:</para>
+ <screen>http://apps.dhis2.org/demo/api/dataValues</screen>
+ <para>The following query parameters are supported for this resource:</para>
+ <table frame="all">
+ <title>Data values query parameters</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="1.23*"/>
+ <colspec colname="c3" colnum="3" colwidth="4.08*"/>
+ <thead>
+ <row>
+ <entry>Query parameter</entry>
+ <entry>Required</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>de</entry>
+ <entry>Yes</entry>
+ <entry>Data element identifier</entry>
+ </row>
+ <row>
+ <entry>pe</entry>
+ <entry>Yes</entry>
+ <entry>Period identifier</entry>
+ </row>
+ <row>
+ <entry>ou</entry>
+ <entry>Yes</entry>
+ <entry>Organisation unit identifier</entry>
+ </row>
+ <row>
+ <entry>co</entry>
+ <entry>No</entry>
+ <entry>Category option combo identifier, default will be used if omitted</entry>
+ </row>
+ <row>
+ <entry>cc</entry>
+ <entry>No (must combine with cp)</entry>
+ <entry>Attribute combo identifier</entry>
+ </row>
+ <row>
+ <entry>cp</entry>
+ <entry>No (must combine with cc)</entry>
+ <entry>Attribute option identifiers, separated with ; for multiple values</entry>
+ </row>
+ <row>
+ <entry>value</entry>
+ <entry>No</entry>
+ <entry>Data value</entry>
+ </row>
+ <row>
+ <entry>comment</entry>
+ <entry>No</entry>
+ <entry>Data comment</entry>
+ </row>
+ <row>
+ <entry>followUp</entry>
+ <entry>No</entry>
+ <entry>Follow up on data value, will toggle the current boolean value</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>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 <emphasis role="italic">409
+ Conflict</emphasis> status code and descriptive text message. If the operation lead to a
+ saved or updated value, <emphasis role="italic">200 OK</emphasis> will be returned. An example
+ of a request looks like this:</para>
+ <screen>curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12"; -X POST -u admin:district -v</screen>
+ <para>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:</para>
+ <screen>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</screen>
+ </section>
+ <section>
+ <title>Reading data values</title>
+ <para>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 <emphasis role="italic">GET</emphasis> HTTP verb. We will also specify that we are interested in the XML resource representation by including an <emphasis role="italic">Accept</emphasis> HTTP header with our request. The following query parameters are required:</para>
+ <table>
+ <title>Data value set query parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <emphasis role="italic">Parameter</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Description</emphasis>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>dataSet</entry>
+ <entry>Data set identifier</entry>
+ </row>
+ <row>
+ <entry>period</entry>
+ <entry>Period identifier in ISO format</entry>
+ </row>
+ <row>
+ <entry>orgUnit</entry>
+ <entry>Organisation unit identifier</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>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:</para>
+ <screen>curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/xml" -u admin:district -v</screen>
+ <para>The response will look something like this:</para>
+ <screen>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></screen>
+ <para>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.</para>
+ </section>
+ <section>
+ <title>Reading large bulks of data values</title>
+ <para>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:</para>
+ <table frame="all">
+ <title>Data value set query parameters</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="195pt"/>
+ <colspec colname="c2" colnum="2" colwidth="605.25pt"/>
+ <thead>
+ <row>
+ <entry><emphasis role="italic">Parameter</emphasis></entry>
+ <entry><emphasis role="italic">Description</emphasis></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>dataSet</entry>
+ <entry>Data set identifier, can be specified multiple times</entry>
+ </row>
+ <row>
+ <entry>startDate</entry>
+ <entry>Start date for the time span of the values to export</entry>
+ </row>
+ <row>
+ <entry>endDate</entry>
+ <entry>End date for the time span of the values to export</entry>
+ </row>
+ <row>
+ <entry>orgUnit</entry>
+ <entry>Organisation unit identifier, can be specified multiple times</entry>
+ </row>
+ <row>
+ <entry>children</entry>
+ <entry>Whether to include the children in the hierarchy of the organisation
+ units</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>The dataSet and orgUnit parameters can be repeated in order to include multiple data sets
+ and organisation units. An example request looks like this:</para>
+ <screen>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</screen>
+ <para>You can get the response in <emphasis role="italic">xml</emphasis> and <emphasis role="italic">csv</emphasis> format. You can indicate which response format you prefer
+ through the <emphasis role="italic">Accept</emphasis> HTTP header like in the example above.
+ For xml you use <emphasis role="italic">application/xml</emphasis>; for csv you use <emphasis role="italic">application/csv</emphasis>.</para>
+ </section>
+ </section>
+ <section>
+ <title>Events</title>
+ <para>This section is about sending and reading events.</para>
+ <section>
<title>Sending event data values</title>
<para>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 <emphasis role="italic">programs</emphasis> resource, an <emphasis role="italic"
>orgUnit</emphasis> which can be looked up using the <emphasis role="italic"
>organisationUnits</emphasis> resource, and a list of valid data element identifiers which
- can be looked up using the <emphasis role="italic">dataElements</emphasis> resource. For
+ can be looked up using the <emphasis role="italic">dataElements</emphasis> resource. For
events with registration, a <emphasis role="italic">person</emphasis> identifier is required,
read about how to get this in the section about the <emphasis role="italic">person</emphasis>
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></screen>
- <para>To perform some testing we can save the XML payload as a file called<emphasis role="italic"> events.xml</emphasis> and send it as a POST request to the events resource in
+ <para>To perform some testing we can save the XML payload as a file called<emphasis
+ role="italic"> events.xml</emphasis> and send it as a POST request to the events resource in
the API using curl with the following command:</para>
<screen>curl -d @events.xml "http://apps.dhis2.org/demo/api/events"; -H "Content-Type:application/xml" -u admin:district -v</screen>
<para>The same payload in JSON format looks like this:</para>
@@ -487,7 +749,8 @@
{ "dataElement": "msodh3rEMJa", "value": "2013-05-18" }
]
}</screen>
- <para>To send this you can save it to a file called <emphasis role="italic">events.json</emphasis> and use curl like this:</para>
+ <para>To send this you can save it to a file called <emphasis role="italic"
+ >events.json</emphasis> and use curl like this:</para>
<screen>curl -d @events.xml "localhost:8080/api/events" -H "Content-Type:application/json" -u admin:district -v</screen>
<para>We also support sending multiple events at the same time. A payload in XML format might
look like this: </para>
@@ -648,300 +911,6 @@
</para>
</section>
<section>
- <title>Sending data values using SDMX-HD</title>
- <para>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 <emphasis role="italic">application/sdmx+xml</emphasis>.</para>
- <para>The example below shows an SDMX-HD dataValueSet:</para>
- <screen><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<CrossSectionalData xmlns="http://www.SDMX.org/resources/SDMXML/schemas/v2_0/message";
- xmlns:common="http://www.SDMX.org/resources/SDMXML/schemas/v2_0/common";
- xmlns:ns="urn:sdmx:org.sdmx.infomodel.keyfamily.KeyFamily=DHIS2:KF_DHIS2_SIMPLE:1.0:cross"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://www.SDMX.org/resources/SDMXML/schemas/v2_0/message SDMXMessage.xsd
- urn:sdmx:org.sdmx.infomodel.keyfamily.KeyFamily=DHIS2:KF_DHIS2_SIMPLE:1.0:cross file:./KF_HOSP_cross.xsd">
-
- <Header>
- <ID>OpenMRS-Export</ID>
- <Test>false</Test>
- <Prepared>2012-03-21</Prepared>
- <Sender id="DDU"/>
- </Header>
-
- <ns:DataSet FREQ="M" TIME_PERIOD="2012-01" FACILITY="DDU" datasetID="KF_HOSP">
- <ns:Group>
- <ns:Section>
- <ns:OBS_VALUE DATAELEMENT="DE001" value="34" />
- <ns:OBS_VALUE DATAELEMENT="DE002" value="36" />
- <ns:OBS_VALUE DATAELEMENT="DE003" value="34" />
- <ns:OBS_VALUE DATAELEMENT="DE004" value="12" />
- <ns:OBS_VALUE DATAELEMENT="DE005" value="5" />
- </ns:Section>
- </ns:Group>
-
-</ns:DataSet>
-</CrossSectionalData>]]></screen>
- <para>One thing to note is that the SDMX-HD metadata for dataelements, orgunits and datasets are
- identified using <emphasis>codes</emphasis> rather than <emphasis>identifiers</emphasis>.
- Assuming these coded datasets are present in the DHIS2 server then this can be posted, for
- example using the curl command below.</para>
- <screen>curl -d @sdmxdatavalueset.xml "http://{server base url}/api/dataValueSets" -H "Content-Type:application/sdmx+xml" -u admin:district -v</screen>
- </section>
- <section>
- <title>Sending large bulks of data values</title>
- <para>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.</para>
- <para>Again we will interact with the with <ulink url="http://apps.dhis2.org/demo/api/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:</para>
- <screen><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></screen>
- <para>We test by using cURL to send the data values:</para>
- <screen>curl -d @datavalueset.xml "http://apps.dhis2.org/demo/api/dataValueSets" -H "Content-Type:application/xml" -u admin:district -v</screen>
- <para>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<emphasis role="italic"> import summary</emphasis>:</para>
- <screen><importSummary>
- <dataValueCount imported="2" updated="1" ignored="1"/>
- <dataSetComplete>false</dataSetComplete>
-</importSummary></screen>
- <para>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.</para>
- <para>The import process can be customized using a set of import parameters:</para>
- <table>
- <title>Import parameters</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- <emphasis role="italic">Parameter</emphasis>
- </entry>
- <entry>
- <emphasis role="italic">Values (default first)</emphasis>
- </entry>
- <entry>
- <emphasis role="italic">Description</emphasis>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>dataElementIdScheme</entry>
- <entry>id | name | code</entry>
- <entry>Which property on the data element object to reference from the XML attribute</entry>
- </row>
- <row>
- <entry>orgUnitIdScheme</entry>
- <entry>id | name | code</entry>
- <entry>Which property on the org unit object to reference from the XML attribute</entry>
- </row>
- <row>
- <entry>dryRun</entry>
- <entry>false | true</entry>
- <entry>Whether to save changes on the server or just return the import summary</entry>
- </row>
- <row>
- <entry>importStrategy</entry>
- <entry>new_and_updates | new | updates</entry>
- <entry>Save objects of all, new or update import status on the server</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>All parameters are optional and can be supplied as query parameters in the request URL like this:</para>
- <screen>http://apps.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name&dryRun=true&importStrategy=new</screen>
- <para>They can also be supplied as XML attributes on the data value set element like below. XML attributes will override query string parameters.</para>
- <screen><dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataElementIdScheme="code"
- orgUnitIdScheme="name" dryRun="true" importStrategy="new">
- ..
-</dataValueSet></screen>
- <para>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
- <emphasis role="italic">code</emphasis> 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.</para>
- </section>
- <section>
- <title>Sending individual data values</title>
- <para>This example will show how to send individual data values to be saved in a request. This
- can be achieved by sending a <emphasis role="italic">POST</emphasis> request to the <emphasis
- role="italic">dataValues</emphasis> resource:</para>
- <screen>http://apps.dhis2.org/demo/api/dataValues</screen>
- <para>The following query parameters are supported for this resource:</para>
- <table frame="all">
- <title>Data values query parameters</title>
- <tgroup cols="3">
- <colspec colname="c1" colnum="1" colwidth="1*"/>
- <colspec colname="c2" colnum="2" colwidth="1.23*"/>
- <colspec colname="c3" colnum="3" colwidth="4.08*"/>
- <thead>
- <row>
- <entry>Query parameter</entry>
- <entry>Required</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>de</entry>
- <entry>Yes</entry>
- <entry>Data element identifier</entry>
- </row>
- <row>
- <entry>pe</entry>
- <entry>Yes</entry>
- <entry>Period identifier</entry>
- </row>
- <row>
- <entry>ou</entry>
- <entry>Yes</entry>
- <entry>Organisation unit identifier</entry>
- </row>
- <row>
- <entry>co</entry>
- <entry>No</entry>
- <entry>Category option combo identifier, default will be used if omitted</entry>
- </row>
- <row>
- <entry>cc</entry>
- <entry>No (must combine with cp)</entry>
- <entry>Attribute combo identifier</entry>
- </row>
- <row>
- <entry>cp</entry>
- <entry>No (must combine with cc)</entry>
- <entry>Attribute option identifiers, separated with ; for multiple values</entry>
- </row>
- <row>
- <entry>value</entry>
- <entry>No</entry>
- <entry>Data value</entry>
- </row>
- <row>
- <entry>comment</entry>
- <entry>No</entry>
- <entry>Data comment</entry>
- </row>
- <row>
- <entry>followUp</entry>
- <entry>No</entry>
- <entry>Follow up on data value, will toggle the current boolean value</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>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 <emphasis role="italic">409
- Conflict</emphasis> status code and descriptive text message. If the operation lead to a
- saved or updated value, <emphasis role="italic">200 OK</emphasis> will be returned. An example
- of a request looks like this:</para>
- <screen>curl "http://apps.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12"; -X POST -u admin:district -v</screen>
- <para>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:</para>
- <screen>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</screen>
- </section>
- <section>
- <title>Reading data values</title>
- <para>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 <emphasis role="italic">GET</emphasis> HTTP verb. We will also specify that we are interested in the XML resource representation by including an <emphasis role="italic">Accept</emphasis> HTTP header with our request. The following query parameters are required:</para>
- <table>
- <title>Data value set query parameters</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <emphasis role="italic">Parameter</emphasis>
- </entry>
- <entry>
- <emphasis role="italic">Description</emphasis>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>dataSet</entry>
- <entry>Data set identifier</entry>
- </row>
- <row>
- <entry>period</entry>
- <entry>Period identifier in ISO format</entry>
- </row>
- <row>
- <entry>orgUnit</entry>
- <entry>Organisation unit identifier</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>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:</para>
- <screen>curl "http://apps.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201201&orgUnit=DiszpKrYNg8" -H "Accept:application/xml" -u admin:district -v</screen>
- <para>The response will look something like this:</para>
- <screen>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></screen>
- <para>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.</para>
- </section>
- <section>
- <title>Reading large bulks of data values</title>
- <para>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:</para>
- <table frame="all">
- <title>Data value set query parameters</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="195pt"/>
- <colspec colname="c2" colnum="2" colwidth="605.25pt"/>
- <thead>
- <row>
- <entry><emphasis role="italic">Parameter</emphasis></entry>
- <entry><emphasis role="italic">Description</emphasis></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>dataSet</entry>
- <entry>Data set identifier, can be specified multiple times</entry>
- </row>
- <row>
- <entry>startDate</entry>
- <entry>Start date for the time span of the values to export</entry>
- </row>
- <row>
- <entry>endDate</entry>
- <entry>End date for the time span of the values to export</entry>
- </row>
- <row>
- <entry>orgUnit</entry>
- <entry>Organisation unit identifier, can be specified multiple times</entry>
- </row>
- <row>
- <entry>children</entry>
- <entry>Whether to include the children in the hierarchy of the organisation
- units</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The dataSet and orgUnit parameters can be repeated in order to include multiple data sets
- and organisation units. An example request looks like this:</para>
- <screen>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</screen>
- <para>You can get the response in <emphasis role="italic">xml</emphasis> and <emphasis role="italic">csv</emphasis> format. You can indicate which response format you prefer
- through the <emphasis role="italic">Accept</emphasis> HTTP header like in the example above.
- For xml you use <emphasis role="italic">application/xml</emphasis>; for csv you use <emphasis role="italic">application/csv</emphasis>.</para>
- </section>
- <section>
<title>Reading event data values</title>
<para>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 <emphasis role="italic">/api/events</emphasis> endpoint
@@ -1036,6 +1005,7 @@
<screen>/api/events?program=ID&orgUnit=ID&person=ID&startDate=2012-01-01&endDate=2012-12-31</screen></para>
</section>
</section>
+ </section>
<section>
<title>Reading dataset complete registrations</title>
<para>This section explains how to retrieve dataset completeness registrations. We will be using
