Sending single event no registration data values

- Sending single event no registration data values - 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. - The approach to sending events is very similar to sending aggregate data values, you will - need a programId, organisationUnitId, and a list of valid data element IDs. An example payload can - be seen below (in XML and - JSON):<?xml version='1.0' encoding='utf-8'?> -<event programId="nGREQllB95g" organisationUnitId="yFZVWkkk1QL" eventDate="2013-05-17" - completed="true" storedBy="admin"> + Sending single event with no registration 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. + Registration implies that the data is linked to a person which is identified using some sort + of identifier. Currently only single event with no registration is supported in DXF 2 + currently. + To send events to DHIS 2 you must interact with the events resource. The approach to sending events is similar to sending aggregate + data values. You will need a programId which can be looked + up using the programs resource, an organisationUnitId which can be looked up using the organisationUnits resource, and a list of valid data element identfiers which + can be looked up using the dataElements resource. + An example payload in XML format where we send events from the "Inpatient morbidity and + mortality" program for the "Ngelehun CHC" facility in the demo database can be seen + below: + <?xml version='1.0' encoding='utf-8'?> +<event programId="eBAyeGv0exc" organisationUnitId="DiszpKrYNg8" 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" /> + <dataValue dataElementId="qrur9Dvnyt5" value="22" /> + <dataValue dataElementId="oZg33kd9taw" value="Male" /> + <dataValue dataElementId="msodh3rEMJa" value="2013-05-18" /> </dataValues> -</event>{ - "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" } - ] -} - We also support sending multiple events at the same time (be warned that this format might - change for our next - release):<?xml version='1.0' encoding='utf-8'?> +</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 + the API using curl with the following command: + curl -d @events.xml "localhost:8080/api/events" -H "Content-Type:application/xml" -u admin:district -v + The same payload in JSON format looks like this: + { + "programId": "eBAyeGv0exc", + "organisationUnitId": "DiszpKrYNg8", + "eventDate": "2013-05-17", + "completed": true, + "storedBy": "admin", + "coordinate": { + "latitude": "59.8", + "longitude": "10.9" + }, + "dataValues": [ + { "dataElementId": "qrur9Dvnyt5", "value": "22" }, + { "dataElementId": "oZg33kd9taw", "value": "Male" }, + { "dataElementId": "msodh3rEMJa", "value": "2013-05-18" } + ] +} + 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: (Caution: this format might change slightly in version 2.13) + <?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>{ - "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" } - ] - } - ] -} - 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. + <eventList> + <event programId="eBAyeGv0exc" organisationUnitId="DiszpKrYNg8" eventDate="2013-05-17" completed="true" storedBy="admin"> + <coordinate latitude="59.8" longitude="10.9" /> + <dataValues> + <dataValue dataElementId="qrur9Dvnyt5" value="22" /> + <dataValue dataElementId="oZg33kd9taw" value="Male" /> + </dataValues> + </event> + <event programId="eBAyeGv0exc" organisationUnitId="DiszpKrYNg8" eventDate="2013-05-17" completed="true" storedBy="admin"> + <coordinate latitude="59.8" longitude="10.9" /> + <dataValues> + <dataValue dataElementId="qrur9Dvnyt5" value="26" /> + <dataValue dataElementId="oZg33kd9taw" value="Female" /> + </dataValues> + </event> + </eventList> +</events> + You will receive an import summary with the response which can be inspected in order to + get information about the outcome of the request, like how many values were imported + successfully. The payload in JSON format looks like this: + { + "eventList": [ + { + "programId": "eBAyeGv0exc", + "organisationUnitId": "DiszpKrYNg8", + "eventDate": "2013-05-17", + "completed": true, + "storedBy": "admin", + "coordinate": { + "latitude": "59.8", + "longitude": "10.9" + }, + "dataValues": [ + { "dataElementId": "qrur9Dvnyt5", "value": "22" }, + { "dataElementId": "oZg33kd9taw", "value": "Male" } + ] }, + { + "programId": "eBAyeGv0exc", + "organisationUnitId": "DiszpKrYNg8", + "eventDate": "2013-05-17", + "completed": true, + "storedBy": "admin", + "coordinate": { + "latitude": "59.8", + "longitude": "10.9" + }, + "dataValues": [ + { "dataElementId": "qrur9Dvnyt5", "value": "26" }, + { "dataElementId": "oZg33kd9taw", "value": "Female" } + ] } + ] +} + The table below describes the meaning of each element. Most elements should be reasonably + self-explanatory. XML/JSON element/key description @@ -464,57 +480,57 @@ stringtrue - UID pointing to the single event no registration program + UID of the single event with no registration program organisationUnitId string true - UID pointing to the organisation unit. + UID of the organisation unit where the event took place eventDate date true - The date this event occured. + The date of when the event occured completed boolean false - Defaults to true. - Is this event complete or not. + true | false + Whether the event is complete or not storedBy string false - Defaults to current user. + Defaults to current user Who stored this event (can be username, system-name etc) coordinate double false - GPS coordinate where this event occured. - 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) - - - dataValue / dataElementId - string - true - - UID of data element. - - - dataValue / value - string - true - - Value of captured data element. + + Refers to wher the event took place geographically (latitude and + longitude) + + + dataElementId + string + true + + UID of data element + + + value + string + true + + Data value or measure for this event