New Tracker API Endpoints

This page gives an overview of the Tracker data API endpoints available in 2.36+. Its objective is to inform decisions on which API “system” to use (the old, legacy endpoints, or the new endpoints).

Documentation

Version 2.36 of DHIS2 introduced a set of new tracker endpoints dedicated to importing and querying tracker objects (Including tracked entities, enrollments, events, and relationships). These new endpoints set a discontinuity with earlier implementations. Re-engineering the endpoints allowed developers to improve, redesign, and formalize the API's behavior to improve the Tracker services.

The newly introduced endpoints consist of:

POST /api/tracker

GET /api/tracker/enrollments

GET /api/tracker/events

GET /api/tracker/trackedEntities

GET /api/tracker/relationships

The old endpoints are marked as deprecated but still work as before (as of August 2021)

Summary

  • Performance and ease of use have been improved
  • Backend program rules are supported (not supported in old APIs, e.g. /api/events)
  • Additional features for data imports such as async imports and import statistics
  • Some unknowns on how stable the new API already is

High-level overview

Tracker data import

  • Multiple endpoints (/api/trackedEntityInstance, /api/enrollments, /api/events) were merged into a single API endpoint (/api/tracker) allowing a single payload for Tracker data import
  • Different structures are allowed for the payload: flat (i.e. all trackedEntities, enrollments, events in its own JSON array) or nested (one large trackedEntities JSON array containing also enrollments and events). Examples of the JSON structure can be found in [1].
  • Most property names have changed (e.g. created has become createdAt)
  • Data can be imported synchronously (great for smaller imports; immediate response) or asynchronously (useful for large imports; no need to wait for completion but rather poll status of import elsewhere).
  • More information and statistics are provided in the import response (error and warnings, time per each step, counts of created/updated/deleted/ignored, message of import errors, error codes)

Tracker data export

  • Parameters changed to respect same naming convention of the changes to data import properties (see above)
  • CSV export is not yet supported
  • Field filtering is not yet supported

Events

Events of an “Events” program (single-stage, anonymous, no tracked entity) are all connected to the same enrollment. Previously there was only an implicit enrollment on the database level.

Relationships

Relationships still describe links between Tracker objects like tracked entity, enrollment, and event – based on/defined through the relation ship type.

Tracker notes

Free-text / qualitative data can be registered for enrollments or events, as many as required. These are similar to Aggregate Data Value comments. The notes cannot be deleted (only by deleting the enrollment or event itself where the note belongs to).

Program rules and actions

Some program rules actions are supported (as some others are only useful in the front-end). Supported are (as of August 2021):

  • Assign
  • Show warning
  • Show error
  • Warning on completion
  • Error on completion
  • Set mandatory field
  • Send message
  • Schedule message.

NOT supported (in the API import) are:

  • Display text or key/value pair
  • Hide field or section
  • Create event

Note: it’s possible to skip program rules by using the parameter skipProgramRules=true

Notifications

Notifications (or: “Side Effects” [1]) are supported: Tracker notification and Program Rule notifications.

Note: it’s possible to skip side effects by using the parameter skipSideEffects=true

Assigning users to events (still supported)

Assigning users to events is also possible in the new Tracker API.

Access control in Tracker (still supported)

Besides the standard features of metadata (sharing, user roles), Tracker has an additional access level protection called “Access Level”. An owning organisation unit means an enrollment of a tracked entity into a program is owned by one organisation unit. Then a particular users three org unit scopes (data capture / data view / search) determines if the user can see data for a tracked entity/enrollment:

  • Open: accessing and modifying data outside the user’s Data Capture org units is possible if the owner organisation unit falls under the users Search org units.
  • Audited: same as open, but adds an audit log entry. In other words, users can change data if they can search for it. This acdcess is logged in the audit log.
  • Protected: can only be accessed by users if the owner organisation unit falls under the user’s Data Capture orgunits. If the user has the owner org units within his/her Search org units the user can “Break the glass” (temporary access to the data; justification required; audit log created). In other words, users can change data if they are able to search it but must justify it and this access is logged.
  • Closed: only users where the owner organisation unit falls under the Data Capture orgunits can access data. In other words, only users who can enter data can view data.

Quality comparison
Quality Legacy Tracker API New Tracker API
Documentation Yes (probably outdated at some point) Yes (still under development)
Performance Lacking; different endpoints increase overhead YES; Increased performance for large imports (e.g. async)
Complexity High High
Features Features more complete Some features still in development while others are new
Long-term view Will be deprecated, UiO at some point will halt further development and bug fixes Future-ready; UiO will continue development
API stability and consistency Stable Stable / some parts subject to change
Security Stable; subject to DHIS2 security model Stable; subject to DHIS2 security model
Validation Yes Yes
Experience with bug and errors Stable, a few bugs Unknown; subject to UiO bug fixes
File types JSON, XML, CSV JSON, (CSV)
Applicable DHIS2 versions 2.35 - unknown 2.36+
Cost considerations Lower initial costs; higher long-term costs Higher initial costs; lower long-term costs

References

  1. DHIS2 docs: New Tracker https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/new-tracker.html
  2. 2.36.0 Release notes including Jira issues related to new Tracker API https://github.com/dhis2/dhis2-releases/blob/master/releases/2.36/ReleaseNote-2.36.0.md