1.24 Events

This section is about sending and reading events.

/api/26/events

1.24.1 Sending events

DHIS2 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 tracked entity instance which is identified using some sort of identifier.

To send events to DHIS2 you must interact with the events resource. The approach to sending events is similar to sending aggregate data values. You will need a program which can be looked up 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 events with registration, a tracked entity instance identifier is required, read about how to get this in the section about the trackedEntityInstances resource. For sending events to programs with multiple stages, you will need to also include the programStage identifier, the identifiers for programStages can be found in the programStages resource.

A simple single event with no registration 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 program="eBAyeGv0exc" orgUnit="DiszpKrYNg8"
  eventDate="2013-05-17" status="COMPLETED" storedBy="admin">
  <coordinate latitude="59.8" longitude="10.9" />
  <dataValues>
    <dataValue dataElement="qrur9Dvnyt5" value="22" />
    <dataValue dataElement="oZg33kd9taw" value="Male" />
    <dataValue dataElement="msodh3rEMJa" value="2013-05-18" />
  </dataValues>
</event>

To perform some testing we can save the XML payload as a file called event.xml and send it as a POST request to the events resource in the API using curl with the following command:

curl -d @event.xml "https://play.dhis2.org/demo/api/26/events"
  -H "Content-Type:application/xml" -u admin:district -v

The same payload in JSON format looks like this:

{
  "program": "eBAyeGv0exc",
  "orgUnit": "DiszpKrYNg8",
  "eventDate": "2013-05-17",
  "status": "COMPLETED",
  "storedBy": "admin",
  "coordinate": {
    "latitude": 59.8,
    "longitude": 10.9
  },
  "dataValues": [
    { "dataElement": "qrur9Dvnyt5", "value": "22" },
    { "dataElement": "oZg33kd9taw", "value": "Male" },
    { "dataElement": "msodh3rEMJa", "value": "2013-05-18" }
  ]
}

To send this you can save it to a file called event.json and use curl like this:

curl -d @event.json "localhost/api/26/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:

<?xml version="1.0" encoding="utf-8"?>
<events>
    <event program="eBAyeGv0exc" orgUnit="DiszpKrYNg8"
      eventDate="2013-05-17" status="COMPLETED" storedBy="admin">
      <coordinate latitude="59.8" longitude="10.9" />
      <dataValues>
        <dataValue dataElement="qrur9Dvnyt5" value="22" />
        <dataValue dataElement="oZg33kd9taw" value="Male" />
      </dataValues>
    </event>
    <event program="eBAyeGv0exc" orgUnit="DiszpKrYNg8"
      eventDate="2013-05-17" status="COMPLETED" storedBy="admin">
      <coordinate latitude="59.8" longitude="10.9" />
      <dataValues>
        <dataValue dataElement="qrur9Dvnyt5" value="26" />
        <dataValue dataElement="oZg33kd9taw" value="Female" />
      </dataValues>
    </event>
</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:

{
  "events": [
  {
    "program": "eBAyeGv0exc",
    "orgUnit": "DiszpKrYNg8",
    "eventDate": "2013-05-17",
    "status": "COMPLETED",
    "storedBy": "admin",
    "coordinate": {
      "latitude": "59.8",
      "longitude": "10.9"
    },
    "dataValues": [
      { "dataElement": "qrur9Dvnyt5", "value": "22" },
      { "dataElement": "oZg33kd9taw", "value": "Male" }
    ] },
  {
    "program": "eBAyeGv0exc",
    "orgUnit": "DiszpKrYNg8",
    "eventDate": "2013-05-17",
    "status": "COMPLETED",
    "storedBy": "admin",
    "coordinate": {
      "latitude": "59.8",
      "longitude": "10.9"
    },
    "dataValues": [
      { "dataElement": "qrur9Dvnyt5", "value": "26" },
      { "dataElement": "oZg33kd9taw", "value": "Female" }
    ] }
  ]
}

As part of the import summary you will also get the identifier reference to the event you just sent, together with a href element which points to the server location of this event. The table below describes the meaning of each element.

Events resource format
Parameter Type Required Options (default first) Description
program string true Identifier of the single event with no registration program
orgUnit string true Identifier of the organisation unit where the event took place
eventDate date true The date of when the event occured
status enum false ACTIVE | COMPLETED | VISITED | SCHEDULE | OVERDUE | SKIPPED Whether the event is complete or not
storedBy string false Defaults to current user Who stored this event (can be username, system-name etc)
coordinate double false Refers to wher the event took place geographically (latitude and longitude)
dataElement string true Identifier of data element
value string true Data value or measure for this event

OrgUnit matching : By default the orgUnit parameter will match on the ID, you can also select the orgUnit id matching scheme by using the parameter orgUnitIdScheme=SCHEME, where the options are: ID , UID , UUID , CODE , and NAME . There is also the ATTRIBUTE: scheme, which matches on a unique metadata attribute value.

Update : To update an existing event, the format of the payload is the same, but the URL you are posting to must add the identifier to the end of the URL string and the request must be PUT.

curl -X PUT -d @updated_event.xml "localhost/api/26/events/ID"
  -H "Content-Type: application/xml" -u admin:district

curl -X PUT -d @updated_event.json "localhost/api/26/events/ID"
  -H "Content-Type: application/json" -u admin:district

Delete : To delete an existing event, all you need is to send a DELETE request with a identifier reference to the server you are using.

curl -X DELETE "localhost/api/26/events/ID" -u admin:district

Get : To get an existing event you can issue a GET request including the identifier like this:

curl "localhost/api/26/events/ID" -H "Content-Type: application/xml" -u admin:district

1.24.1.1 Import parameters

The import process can be customized using a set of import parameters:

Import parameters
Parameter Values (default first) Description
dataElementIdScheme id | name | code | attribute:ID Property of the data element object to use to map the data values.
orgUnitIdScheme id | name | code | attribute:ID Property of the org unit object to use to map the data values.
idScheme id | name | code| attribute:ID Property of all objects including data elements, org units and category option combos, to use to map the data values.
dryRun false | true Whether to save changes on the server or just return the import summary.
importStrategy CREATE | UPDATE | CREATE_AND_UPDATE | DELETE Save objects of all, new or update import status on the server.
skipNotifications true | false Indicates whether to send notifications for completed events.
importReportMode FULL, ERRORS, DEBUG Sets the ImportReport mode, controls how much is reported back after the import is done. ERRORS only includes ObjectReports for object which has errors. FULL returns an ObjectReport for all objects imported, and DEBUG returns the same plus a name for the object (if available).

1.24.2 CSV Import / Export

In addition to XML and JSON for event import/export, in DHIS2.17 we introduced support for the CSV format. Support for this format builds on what was described in the last section, so here we will only write about what the CSV specific parts are.

To use the CSV format you must either use the /api/events.csv endpoint, or add content-type: text/csv for import, and accept: text/csv for export when using the /api/events endpoint.

The order of column in the CSV which are used for both export and import is as follows:

CSV column
Index Key Type Description
1 event identifier Identifier of event
2 status enum Status of event, can be ACTIVE | COMPLETED | VISITED | SCHEDULED | OVERDUE | SKIPPED
3 program identifier Identifier of program
4 programStage identifier Identifier of program stage
5 enrollment identifier Identifier of enrollment (program stage instance)
6 orgUnit identifier Identifier of organisation unit
7 eventDate date Event date
8 dueDate date Due Date
9 latitude double Latitude where event happened
10 longitude double Longitude where event happened
11 dataElement identifier Identifier of data element
12 value string Value / measure of event
13 storedBy string Event was stored by (defaults to current user)
14 providedElsewhere boolean Was this value collected somewhere else

Example of 2 events with 2 different data value each:

EJNxP3WreNP,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,1,,
EJNxP3WreNP,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,2,,
qPEdI1xn7k0,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,3,,
qPEdI1xn7k0,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,4,,

1.24.3 Querying and reading events

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 will match the format that is used to send events to it (which the analytics event api does not support). Both XML and JSON are supported, either through adding .json/.xml or by setting the appropriate Accept header. The query is paged by default and the default page size is 50 events, field filtering works as it does for metadata, add the fields parameter and include your wanted properties, i.e. ?fields=program,status .

Events resource query parameters
Key Type Required Description
program identifier true (if not programStage is provided) Identifier of program
programStage identifier false Identifier of program stage
programStatus enum false Status of event in program, ca be ACTIVE | COMPLETED | CANCELLED
followUp boolean false Whether event is considered for follow up in program, can be true | false or omitted.
trackedEntityInstance identifier false Identifier of tracked entity instance
orgUnit identifier true Identifier of organisation unit
ouMode enum false Org unit selection mode, can be SELECTED | CHILDREN | DESCENDANTS
startDate date false Only events newer than this date
endDate date false Only events older than this date
status enum false Status of event, can be ACTIVE | COMPLETED | VISITED | SCHEDULED | OVERDUE | SKIPPED
lastUpdatedStartDate date false Filter for events which were updated after this date.
lastUpdatedEndDate date false Filter for events which were updated up until this date.
skipMeta boolean false Exclude the meta data part of response (improves performance)
page integer false Page number
pageSize integer falase Number of items in each page
totalPages boolean false Indicates whether to include the total number of pages in the paging response.
skipPaging boolean false Indicates whether to skip paging in the query and return all events.
dataElementIdScheme string false Data element ID scheme to use for export, valid options are UID and CODE
categoryOptionComboIdScheme string false Category Option Combo ID scheme to use for export, valid options are UID and CODE
orgUnitIdScheme string false Organisation Unit ID scheme to use for export, valid options are UID and CODE
programIdScheme string false Program ID scheme to use for export, valid options are UID and CODE
programStageIdScheme string false Program Stage ID scheme to use for export, valid options are UID and CODE
idScheme string false Allows to set id scheme for data element, category option combo, orgUnit, program and program stage at once.
order string false The order of which to retreive the events from the API. Usage: order=<property>:asc/desc - Ascending order is default.

Properties: event | program | programStage | enrollment | enrollmentStatus | orgUnit | orgUnitName | trackedEntityInstance | eventDate | followup | status | dueDate | storedBy | created | lastUpdated | completedBy | completedDate

order=orgUnitName:DESC
order=lastUpdated:ASC
event comma delimited strings false Filter the result down to a limited set of IDs by using event=id1;id2 .
includeDeleted boolean false When true, soft deleted events will be included in your query result.

1.24.3.1 Examples

Query for all events with children of a certain organisation unit:

/api/26/events.json?orgUnit=YuQRtpLP10I&ouMode=CHILDREN

Query for all events with all descendants of a certain organisation unit, implying all organisation units in the sub-hierarchy:

/api/26/events.json?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS

Query for all events with a certain program and organisation unit:

/api/26/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

Query for all events with a certain program and organisation unit, sorting by due date ascending:

/api/26/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=dueDate

Query for the 10 events with the newest event date in a certain program and organisation unit - by paging and ordering by due date descending:

/api/26/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  &order=eventDate:desc&pageSize=10&page=1

Query for all events with a certain program and organisation unit for a specific tracked entity instance:

/api/26/events.json?orgUnit=DiszpKrYNg8
  &program=eBAyeGv0exc&trackedEntityInstance=gfVxE3ALA9m

Query for all events with a certain program and organisation unit older or equal to 2014-02-03:

/api/26/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&endDate=2014-02-03

Query for all events with a certain program stage, organisation unit and tracked entity instance in the year 2014:

/api/26/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  &trackedEntityInstance=gfVxE3ALA9m&startDate=2014-01-01&endDate=2014-12-31