dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #22708
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 741: documentation for event api, wip
------------------------------------------------------------
revno: 741
committer: Morten Olav Hansen <mortenoh@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Sun 2013-05-26 17:10:22 +0700
message:
documentation for event api, wip
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 2013-05-24 11:54:48 +0000
+++ src/docbkx/en/dhis2_user_man_web_api.xml 2013-05-26 10:10:22 +0000
@@ -344,6 +344,170 @@
<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 single event no registration data values</title>
+ <para>DHIS 2 supports 3 kinds of events, single events with no registration (previously called
+ anonymous), single event with registration, and multiple events with registration. Currently
+ only single event with no registration is supported in DXF2, support for additional event
+ types will come later.</para>
+ <para>The approach to sending events is very similar to sending aggregate data values, you will
+ need a <emphasis role="italic">programId</emphasis>, <emphasis role="italic"
+ >organisationUnitId</emphasis>, and a list of valid data element IDs. An example payload can
+ be seen below (in XML and
+ JSON):<screen><?xml version='1.0' encoding='utf-8'?>
+<event programId="nGREQllB95g" organisationUnitId="yFZVWkkk1QL" eventDate="2013-05-17"
+ completed="true" storedBy="admin">
+ <coordinate latitude="59.8" longitude="10.9" />
+ <dataValues>
+ <dataValue dataElementId="WFhjqschUjD" value="2013-05-17" />
+ <dataValue dataElementId="QGfmQy0pxFU" value="-100" />
+ </dataValues>
+</event></screen><screen>{
+ "programId": "nGREQllB95g",
+ "organisationUnitId": "yFZVWkkk1QL",
+ "eventDate": "2013-05-17",
+ "completed": true,
+ "storedBy": "admin",
+ "coordinate": {
+ "latitude": "59.8",
+ "longitude": "10.9"
+ },
+ "dataValues": [
+ { "dataElementId": "WFhjqschUjD", "value": "2013-05-17" },
+ { "dataElementId": "QGfmQy0pxFU", "value": "-100" }
+ ]
+}</screen></para>
+ <para>We also support sending multiple events at the same time (be warned that this format might
+ change for our next
+ release):<screen><?xml version='1.0' encoding='utf-8'?>
+<events>
+ <eventList>
+ <event programId="nGREQllB95g" organisationUnitId="yFZVWkkk1QL" eventDate="2013-05-17"
+ completed="true" storedBy="admin">
+ <coordinate latitude="59.8" longitude="10.9" />
+ <dataValues>
+ <dataValue dataElementId="WFhjqschUjD" value="2013-05-17" />
+ <dataValue dataElementId="QGfmQy0pxFU" value="-100" />
+ </dataValues>
+ </event>
+
+ <event programId="nGREQllB95g" organisationUnitId="yFZVWkkk1QL" eventDate="2013-05-17"
+ completed="true" storedBy="admin">
+ <coordinate latitude="59.8" longitude="10.9" />
+ <dataValues>
+ <dataValue dataElementId="WFhjqschUjD" value="2013-05-17" />
+ <dataValue dataElementId="QGfmQy0pxFU" value="-100" />
+ </dataValues>
+ </event>
+ </eventList>
+</events></screen><screen>{
+ "eventList": [
+ {
+ "programId": "nGREQllB95g",
+ "organisationUnitId": "yFZVWkkk1QL",
+ "eventDate": "2013-05-17",
+ "completed": true,
+ "storedBy": "admin",
+ "coordinate": {
+ "latitude": "59.8",
+ "longitude": "10.9"
+ },
+ "dataValues": [
+ { "dataElementId": "WFhjqschUjD", "value": "2013-05-17" },
+ { "dataElementId": "QGfmQy0pxFU", "value": "-100" }
+ ]
+ },
+ {
+ "programId": "nGREQllB95g",
+ "organisationUnitId": "yFZVWkkk1QL",
+ "eventDate": "2013-05-17",
+ "completed": true,
+ "storedBy": "admin",
+ "coordinate": {
+ "latitude": "59.8",
+ "longitude": "10.9"
+ },
+ "dataValues": [
+ { "dataElementId": "WFhjqschUjD", "value": "2013-05-17" },
+ { "dataElementId": "QGfmQy0pxFU", "value": "-100" }
+ ]
+ }
+ ]
+}</screen></para>
+ <para>Most of the elements here should be easy to understand already, but a table can be seen
+ below that will explain what they all mean.</para>
+ <para>
+ <table>
+ <title>XML/JSON element/key description</title>
+ <tgroup cols="5">
+ <thead>
+ <row>
+ <entry>
+ <emphasis role="italic">Key</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Type</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Required</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Options (default first)</emphasis>
+ </entry>
+ <entry>
+ <emphasis role="italic">Description</emphasis>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>programId</entry>
+ <entry>string</entry>
+ <entry>true</entry>
+ <entry/>
+ <entry>UID pointing to the single event no registration program</entry>
+ </row>
+ <row>
+ <entry>organisationUnitId</entry>
+ <entry>string</entry>
+ <entry>true</entry>
+ <entry/>
+ <entry>UID pointing to the organisation unit.</entry>
+ </row>
+ <row>
+ <entry>eventDate</entry>
+ <entry>date</entry>
+ <entry>true</entry>
+ <entry/>
+ <entry>The date this event occured.</entry>
+ </row>
+ <row>
+ <entry>completed</entry>
+ <entry>boolean</entry>
+ <entry>false</entry>
+ <entry>Defaults to true.</entry>
+ <entry>Is this event complete or not.</entry>
+ </row>
+ <row>
+ <entry>storedBy</entry>
+ <entry>string</entry>
+ <entry>false</entry>
+ <entry>Defaults to current user.</entry>
+ <entry>Who stored this event (can be username, system-name etc)</entry>
+ </row>
+ <row>
+ <entry>coordinate</entry>
+ <entry>object</entry>
+ <entry>false</entry>
+ <entry>GPS coordinate where this event occured.</entry>
+ <entry>For XML this is an element called coordinate with two attributes (latitude and longitude),
+ for JSON this is an object with two keys (latitude and longitude)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </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
