For the complete DHIS2 documentation index, see llms.txt.

Tracker¶

Note

Tracker has been re-implemented in DHIS2 2.36. This document describes the new tracker endpoints

POST /api/tracker

GET /api/tracker/trackedEntities

GET /api/tracker/enrollments

GET /api/tracker/events

GET /api/tracker/relationships

The deprecated tracker endpoints

GET/POST/PUT/DELETE /api/trackedEntityInstance

GET/POST/PUT/DELETE /api/enrollments

GET/POST/PUT/DELETE /api/events

GET/POST/PUT/DELETE /api/relationships

have been removed in version 42!

Migrating to new tracker endpoints should help you get started with your migration. Reach out on the community of practice if you need further assistance.

Tracker objects¶

Tracker consists of a few different types of objects that are nested together to represent the data. In this section, we will show and describe each of the objects used in the Tracker API.

Tracked entities¶

Tracked Entities are the root object for the Tracker model.

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
trackedEntity	The identifier of the tracked entity. Generated if not supplied	Não	sim	String:Uid	ABCDEF12345
trackedEntityType	The type of tracked entity.	sim	sim	String:Uid	ABCDEF12345
createdAt	Timestamp when the user created the tracked entity. Set on the server.	Não	Não	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
createdAtClient	Timestamp when the user created the tracked entity on the client.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAt	Timestamp when the object or any enrollment, event, attribute or originating relationship, was last updated. Set on the server.	Não	Não	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAtClient	Timestamp when the object was last updated on the client.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
orgUnit	The organisation unit where the user created the tracked entity.	sim	sim	String:Uid	ABCDEF12345
inactive	Indicates whether the tracked entity is inactive or not.	Não	sim	Boolean	Default: false, true
deleted	Indicates whether the tracked entity has been deleted. It can only change when deleting.	Não	Não	Boolean	false until deleted
potentialDuplicate	Indicates whether the tracked entity is a potential duplicate.	Não	Não	Boolean	Default: false
geometry	A geographical representation of the tracked entity. Based on the "featureType" of the TrackedEntityType.	Não	sim	GeoJson	{ "type": "POINT", "coordinates": [123.0, 123.0] }
storedBy	Client reference for who stored/created the tracked entity. Set on the server.	Não	sim	String:Any	John Doe
createdBy	Only for reading data. User that created the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
updatedBy	Only for reading data. User that last updated the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
atributos	A list of tracked entity attribute values owned by the tracked entity.	Não	sim	List of TrackedEntityAttributeValue	See Attribute
enrollments	A list of enrollments owned by the tracked entity.	Não	sim	List of Enrollment	See Enrollment
relationships	A list of relationships connected to the tracked entity.	Não	sim	List of Relationship	See Relationship
programOwners	A list of organisation units with access through specific programs to this tracked entity. See "Program Ownership".	Não	sim	List of ProgramOwner	See section "Program Ownership"

Note

Tracked Entities "owns" all Tracked Entity Attribute Values (Or "attributes" as described in the previous table). However, Tracked Entity Attributes are either connected to a Tracked Entity through its Tracked Entity Type or a Program. We often refer to this separation as Tracked Entity Type Attributes and Tracked Entity Program Attributes. The importance of this separation is related to access control and limiting what information the user can see.

The "attributes" referred to in the Tracked Entity are Tracked Entity Type Attributes.

Enrollments¶

Tracked Entities can enroll into TRACKER PROGRAM for which they are eligible. Tracked entities are eligible as long as the program is configured with the same Tracked Entity Type as the tracked entity. We represent the enrollment with the Enrollment object, which we describe in this section.

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
enrollment	The identifier of the enrollment. Generated if not supplied.	Não	sim	String:Uid	ABCDEF12345
“Registro de Casos de Malária”	The tracker program the enrollment is enrolled into.	sim	Não	String:Uid	ABCDEF12345
trackedEntity	A reference to the tracked entity enrolled.	sim	sim	String:Uid	ABCDEF12345
status	Status of the enrollment. ACTIVE if not supplied.	Não	Não	Enum	ACTIVE, COMPLETED, CANCELLED
orgUnit	The organisation unit where the user enrolled the tracked entity.	sim	Não	String:Uid	ABCDEF12345
createdAt	Timestamp when the user created the object. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
createdAtClient	Timestamp when the user created the object on client.	Não	Não	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAt	Timestamp when the object was last updated. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAtClient	Timestamp when the object was last updated on client.	Não	Não	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
enrolledAt	Timestamp when the user enrolled the tracked entity.	sim	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
occurredAt	Timestamp when enrollment occurred.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
completedAt	Timestamp when the user completed the enrollment. Set on the server if not set by the client.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
completedBy	Only for reading data. User that completed the enrollment. Set on the server.	Não	Não	String:any	John Doe
followUp	Indicates whether the enrollment requires follow-up. False if not supplied.	Não	Não	Boolean	Default: False, True
deleted	Indicates whether the enrollment has been deleted. It can only change when deleting.	Não	sim	Boolean	False until deleted
geometry	A geographical representation of the enrollment. Based on the "featureType" of the program.	Não	Não	GeoJson	{ "type": "POINT", "coordinates": [123.0, 123.0] }
storedBy	Client reference for who stored/created the enrollment. Set on the server.	Não	sim	String:Any	John Doe
createdBy	Only for reading data. User that created the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
updatedBy	Only for reading data. User that last updated the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
atributos	A list of tracked entity attribute values connected to the enrollment.	Não	Não	List of TrackedEntityAttributeValue	See Attribute
events	A list of events owned by the enrollment.	Não	Não	List of Event	See Event
relationships	A list of relationships connected to the enrollment.	Não	Não	List of Relationship	See Relationship
notes	Notes connected to the enrollment. It can only be created.	Não	sim	List of Note	See Note
attributeOptionCombo	Attribute option combo for the enrollment. If not supplied, the default value defined by the program’s category combo is used.	Não	Não	String:Uid	ABCDEF12345

Note

Tracked Entities "owns" all Tracked Entity Attribute Values (Or "attributes" as described in the previous table). However, Tracked Entity Attributes are either connected to a Tracked Entity through its Tracked Entity Type or a Program. We often refer to this separation as Tracked Entity Type Attributes and Tracked Entity Program Attributes. The importance of this separation is related to access control and limiting what information the user can see.

The "attributes" referred to in the Enrollment are Tracked Entity Program Attributes.

Events¶

Events are either part of an EVENT PROGRAM or TRACKER PROGRAM. For TRACKER PROGRAM, events belong to an Enrollment, which again belongs to a Tracked Entity. On the other hand, EVENT PROGRAM is Events not connected to a specific Enrollment or Tracked Entity. The difference is related to whether we track a specific Tracked Entity or not. We sometimes refer to EVENT PROGRAM events as "anonymous events" or "single events" since they only represent themselves and not another Tracked Entity.

In the API, the significant difference is that events are either not linked to any enrollment (EVENT PROGRAM) or are linked to different enrollments (TRACKER PROGRAM). The table below will point out any exceptional cases between these two.

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
event	The identifier of the event. Generated if not supplied.	Não	sim	String:Uid	ABCDEF12345
programStage	The program stage the event represents.	sim	Não	String:Uid	ABCDEF12345
enrollment	A reference to the enrollment which owns the event. Not applicable for `EVENT PROGRAM`.	sim	sim	String:Uid	ABCDEF12345
“Registro de Casos de Malária”	Only for reading data. The type of program the enrollment which owns the event has.	Não	sim	String:Uid	ABCDEF12345
trackedEntity	Only for reading data. The tracked entity which owns the event. Not applicable for `EVENT PROGRAM`.	Não	Não	String:Uid	ABCDEF12345
status	Status of the event. Default is `ACTIVE`. For `EVENT PROGRAM` only `ACTIVE` and `COMPLETED` statuses are allowed.	Não	Não	Enum	ACTIVE, COMPLETED, VISITED, SCHEDULE, OVERDUE, SKIPPED
orgUnit	The organisation unit where the user registered the event.	sim	Não	String:Uid	ABCDEF12345
createdAt	Only for reading data. Timestamp when the user created the event. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
createdAtClient	Timestamp when the user created the event on client.	Não	Não	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAt	Only for reading data. Timestamp when the event was last updated. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAtClient	Timestamp when the event was last updated on client.	Não	Não	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
scheduledAt	Timestamp when the event was scheduled for. Not applicable for `EVENT PROGRAM`.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
occurredAt	Timestamp when something occurred.	sim	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
completedAt	Timestamp when the user completed the event. Set on the server if not set by the client.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
completedBy	Only for reading data. User that completed the event. Set on the server.	Não	Não	String:any	John Doe
followUp	Only for reading data. Indicates whether the event has been flagged for follow-up.	Não	Não	Boolean	False, True
deleted	Only for reading data. Indicates whether the event has been deleted. It can only change when deleting.	Não	sim	Boolean	False until deleted
geometry	A geographical representation of the event. Based on the "featureType" of the program stage.	Não	Não	GeoJson	{ "type": "POINT", "coordinates": [123.0, 123.0] }
storedBy	Client reference for who stored/created the event. Set on the server.	Não	sim	String:Any	John Doe
createdBy	Only for reading data. User that created the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
updatedBy	Only for reading data. User that last updated the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
attributeOptionCombo	Attribute option combo for the event. If not supplied, the default value defined by the program’s category combo is used.	Não	Não	String:Uid	ABCDEF12345
attributeCategoryOptions	Attribute category option for the event. If not supplied, the default value defined by the program’s category combo is used	Não	Não	String:Uid	ABCDEF12345
assignedUser	A reference to a user who has been assigned to the event.	Não	Não	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
dataValues	A list of data values connected to the event.	Não	Não	List of TrackedEntityAttributeValue	See Attribute
relationships	A list of relationships connected to the event.	Não	Não	List of Relationship	See Relationship
notes	Notes connected to the event. It can only be created.	Não	sim	List of Note	See Note

Relacionamentos¶

Relationships are objects that link together two other tracker objects. The constraints each side of the relationship must conform to are based on the Relationship Type of the Relationship.

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
relationship	The identifier of the relationship. Generated if not supplied.	Não	sim	String:Uid	ABCDEF12345
relationshipType	The type of the relationship. Decides what objects can be linked in a relationship.	sim	sim	String:Uid	ABCDEF12345
relationshipName	Only for reading data. The name of the relationship type of this relationship.	Não	Não	String:Any	Sibling
createdAt	Timestamp when the user created the relationship. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAt	Timestamp when the relationship was last updated. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
createdAtClient	Timestamp when the user created the relationship on the client.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
bidirectional	Only for reading data. Indicated whether the relationship type is bidirectional or not.	Não	Não	Boolean	True or False
from, to	A reference to each side of the relationship. Must conform to the constraints set in the relationship type.	sim	sim	RelationshipItem	{"trackedEntity": {"trackedEntity": "ABCEF12345"}}, {"enrollment": {"enrollment": "ABCDEF12345"}} or {"event": {"event": "ABCDEF12345" }}

Note

Relationship item represents a link to an object. Since a relationship can be between any tracker object like tracked entity, enrollment, and event, the value depends on the relationship type. For example, if a relationship type connects from an event to a tracked entity, the format is strict:
{
  "from": {
    "event": { "event": "ABCDEF12345" }
  },
  "to": {
    "trackedEntity": { "trackedEntity": "FEDCBA12345" }
  }
}

Atributos¶

Attributes are the values describing the tracked entities. Attributes can be associated either through a tracked entity type or a program. This implies that attributes can be part of both a tracked entity and an enrollment. Importantly, an attribute can only have one value, even if a tracked entity has multiple enrollments that define that attribute. This is because the tracked entity ultimately owns the attribute value.

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
attribute	A reference to the tracked entity attribute represented.	sim	sim	String:Uid	ABCDEF12345
código	Only for reading data. The code of the tracked entity attribute.	Não	Não	String:Any	ABC
displayName	Only for reading data. The displayName of the tracked entity attribute.	Não	Não	String:Any	Nome
createdAt	Timestamp when the value was added. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAt	Timestamp when the value was last updated. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
storedBy	Client reference for who stored/created the value. Set on the server.	Não	sim	String:Any	John Doe
valueType	Only for reading data. The type of value the attribute represents.	Não	Não	Enum	TEXT, INTEGER, and more
value	The value of the tracked entity attribute.	Não	Não	String:Any	John Doe

Note

When adding or updating an attribute, only the attribute and value properties are required. To remove an attribute from a tracked entity or enrollment, set the value to null example.

In the context of tracker, we refer to Tracked Entity Attributes and Tracked Entity Attribute Values simply as attributes. However, it's important to note that attributes and attribute values are also concepts within metadata. Therefore, distinguishing between tracker attributes and metadata attributes is essential. In the tracker API, you can reference metadata attributes by specifying the idScheme on import (see request parameters) and event export.

Data values¶

While attributes describe a tracked entity, data values describe an event.

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
dataElement	The data element this value represents.	sim	sim	String:Uid	ABCDEF12345
value	The value of the data value.	Não	Não	String:Any	123
providedElsewhere	Indicates whether the user provided the value elsewhere or not. False if not supplied.	Não	Não	Boolean	False or True
createdAt	Timestamp when the user added the value. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
updatedAt	Timestamp when the value was last updated. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
storedBy	Client reference for who stored/created the value. Set on the server.	Não	sim	String:Any	John Doe
createdBy	Only for reading data. User that created the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }
updatedBy	Only for reading data. User that last updated the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }

Note

When adding or updating a data value, only the dataElement and value properties are required. To remove a data value from an event, set the value to null see example.

Notas¶

In situations where additional information or notes about specific issues need to be recorded, these can be captured using notes.

There are two types of notes: enrollment-level notes and event-level notes. An enrollment can consist of one or more events, and notes can be recorded for each event to document reasons such as why an event was missed, rescheduled, or partially completed. Each event within an enrollment can have its own notes. Additionally, overall observations of these events can be recorded using a parent enrollment note. Enrollment notes are useful for documenting reasons such as why an enrollment was canceled. The use of notes is flexible and can be tailored to the user's needs and specific use cases.

Both enrollment and event notes can have an unlimited number of entries; there is no limit to the number of notes that can be added. However, it is not possible to delete or update these notes once they are created. They function like a logbook. To amend a note, a new note can be created. The only way to delete a note is by deleting the parent object, either the event or the enrollment.

Notes do not have a dedicated endpoint; they are exchanged as part of the parent event and/or enrollment payload. A sample payload is found below.

{
  "trackedEntity": "oi3PMIGYJH8",
  "enrollments": [
    {
      "enrollment": "EbRsJr8LSSO",
      "notes": [
        {
          "note": "vxmCvYcPdaW",
          "value": "Enrollment note 1"
        },
        {
          "value": "Enrollment note 2."
        }
      ],
      "events": [
        {
          "event": "zfzS9WeO0uM",
          "notes": [
            {
              "note": "MAQFb7fAggS",
              "value": "Event Note 1."
            },
            {
              "value": "Event Note 2."
            }
          ]
        }
      ]
    }
  ]
}

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
note	The reference of the note. Generated if empty	Não	sim	String:Uid	ABCDEF12345
value	The content of the note.	sim	sim	String:Any	This is a note
storedAt	Timestamp when the user added the note. Set on the server.	Não	sim	Date:ISO 8601	YYYY-MM-DDThh:mm:ss
storedBy	Client reference for who stored/created the note. Set on the server.	Não	sim	String:Any	John Doe
createdBy	Only for reading data. User that created the object. Set on the server.	Não	sim	Do utilizador	{ "uid": "ABCDEF12345", "username": "username", "firstName": "John", "surname": "Doe" }

Comercial¶

Property	Descrição	Requerido	Immutable	Modelo	Exemplo
uid	The identifier of the user.	Yes*	sim	String:Uid	ABCDEF12345
username	Username used by the user.	Yes*	sim	String:Any	123
firstName	Only for reading data. First name of the user.	Não	sim	String:Any	John
surname	Only for reading data. Last name of the user.	Não	sim	String:Any	Doe

Note

Either uid or username must be provided. If both are provided, only username is considered.

ID schemes¶

Tracker supports different identifier schemes, referred to as ID schemes. The default ID scheme for import and export is UID.

ID schemes are supported in the following endpoints.

See each section for request parameters.

Only metadata fields directly on the entity are exported using the chosen idScheme. Metadata in collections are always exported using UIDs, except for:

TrackedEntity.attributes[].attribute
Event.dataValues[].dataElement

For example, metadata references in TrackedEntity.relationships or enrollments will always use UIDs for import/export.

The import expects metadata identifiers to only use the chosen idScheme. Similarly, metadata is exported only using the chosen idScheme. If metadata lacks identifiers for the chosen idScheme, you'll receive an error like the below.

{
  "httpStatus": "Unprocessable Entity",
  "httpStatusCode": 422,
  "status": "ERROR",
  "message": "Not all metadata has an identifier for the requested idScheme. Either change the requested idScheme or add the missing identifiers to the metadata.",
  "devMessage": "Following metadata listed using their UIDs is missing identifiers for the requested idScheme: ProgramStage[ATTRIBUTE:Y1LUDU8sWBR]=A03MvHHogjR .."
}

To resolve this, either:

Add the missing identifiers.
Change the idScheme parameters to use a scheme with complete information.

Tracker import¶

POST /api/tracker

The endpoint POST /api/tracker is also called the tracker importer. This endpoint allows clients to import i.e. create, update and delete

Entidades rastreadas
Enrollments
Eventos
Relacionamentos
Objects embedded in other tracker objects

Request parameters¶

The tracker importer supports the following parameters:

Request parameter	Descrição	Modelo	Allowed values	Default value
async	Indicates whether the import should happen asynchronously or synchronously.	Boolean	`true`, `false`	`true`
reportMode	Only when performing synchronous import. See importSummary for more info.	Enum	`FULL`, `ERRORS`, `WARNINGS`	`ERRORS`
importMode	Can either be `VALIDATE` which will report errors in the payload without making changes to the database or `COMMIT` (default) which will validate the payload and make changes to the database.	Enum	`VALIDATE`, `COMMIT`	`COMMIT`
idScheme	IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is `UID`.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`UID`
dataElementIdScheme	IdScheme used for data element references. Defaults to the `idScheme` parameter.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`idScheme` parameter
orgUnitIdScheme	IdScheme used for organisation unit references. Defaults to the `idScheme` parameter.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`idScheme` parameter
programIdScheme	IdScheme used for program references. Defaults to the `idScheme` parameter.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`idScheme` parameter
programStageIdScheme	IdScheme used for program stage references. Defaults to the `idScheme` parameter.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`idScheme` parameter
categoryOptionComboIdScheme	IdScheme used for category option combo references. Defaults to the `idScheme` parameter.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`idScheme` parameter
categoryOptionIdScheme	IdScheme used for category option references. Defaults to the `idScheme` parameter.	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	`idScheme` parameter
importStrategy	Indicates the effect the import should have. Can either be `CREATE`, `UPDATE`, `CREATE_AND_UPDATE` and `DELETE`, which respectively only allows importing new data, importing changes to existing data, importing any new or updates to existing data, and finally deleting data.	Enum	`CREATE`, `UPDATE`, `CREATE_AND_UPDATE`, `DELETE`	`CREATE`
atomicMode	Indicates how the import responds to validation errors. If `ALL`, all data imported must be valid for any data to be committed. For `OBJECT`, only the data committed needs to be valid, while other data can be invalid.	Enum	`ALL`, `OBJECT`	`ALL`
flushMode	Indicates the frequency of flushing. This is related to how often data is pushed into the database during the import. Primarily used for debugging reasons, and should not be changed in a production setting	Enum	`AUTO`, `OBJECT`	`AUTO`
validationMode	Indicates the completeness of the validation step. It can be skipped, set to fail fast (Return on the first error), or full (default), which will return any errors found	Enum	`FULL`, `FAIL_FAST`, `SKIP`	`FULL`
skipPatternValidation	If true, it will skip validating the pattern of generated attributes.	Boolean	`true`, `false`	`false`
skipSideEffects	If true, it will skip running any side effects for the import	Boolean	`true`, `false`	`false`
skipRuleEngine	If true, it will skip running any program rules for the import	Boolean	`true`, `false`	`false`

Sync and async¶

The main difference for the user between synchronous and asynchronous imports is the timing of the API response. Synchronous imports provide an immediate import summary once the import is finished. In contrast, asynchronous imports return a reference to the import job right away. The progress of the import job can be tracked using this response.location. An example of an asynchronous import response is found below.

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Tracker job added",
  "response": {
    "id": "cHh2OCTJvRw",
    "location": "https://play.im.dhis2.org/dev/api/tracker/jobs/cHh2OCTJvRw"
  }
}

For large imports, opting for asynchronous import can be advantageous, as it prevents long waiting times for a response.

Payload¶

The importer supports both flat and nested payloads.

Flat payload¶

The flat payload can include collections for each of the core tracker objects: tracked entities, enrollments, events, and relationships. This format integrates well with existing data that already has UIDs assigned. However, for new data, the client must provide new UIDs for any references between objects. For instance, if you import a new tracked entity with a new enrollment, the client must provide a UID for the tracked entity so that the enrollment can be linked to it.

{
  "trackedEntities": [
    {
      "orgUnit": "y77LiPqLMoq",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "nEenWmSyUEp"
    },
    {
      "orgUnit": "y77LiPqLMoq",
      "trackedEntity": "Gjaiu3ea38E",
      "trackedEntityType": "nEenWmSyUEp"
    }
  ],
  "enrollments": [
    {
      "enrolledAt": "2019-08-19T00:00:00.000",
      "enrollment": "MNWZ6hnuhSw",
      "occurredAt": "2019-08-19T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "nEenWmSyUEp",
      "attributeOptionCombo": "HllvX50cXC0",
    }
  ],
  "events": [
    {
      "attributeCategoryOptions": "xYerKDKCefk",
      "attributeOptionCombo": "HllvX50cXC0",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": "true"
        },
        {
          "dataElement": "UXz7xuGCEhU",
          "value": "5.7"
        }
      ],
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "event": "ZwwuwNp6gVd",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    },
    {
      "attributeCategoryOptions": "xYerKDKCefk",
      "attributeOptionCombo": "HllvX50cXC0",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "event": "XwwuwNp6gVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "ZzYYXq4fJie",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ],
  "relationships": [
    {
      "from": {
        "trackedEntity": {
          "trackedEntity": "Kj6vYde4LHh"
        }
      },
      "relationshipType": "dDrh5UyCyvQ",
      "to": {
        "trackedEntity": {
          "trackedEntity": "Gjaiu3ea38E"
        }
      }
    }
  ]
}

Nested payload¶

Nested payloads are the most commonly used structure, where tracker objects are embedded within their parent objects, such as an enrollment within a tracked entity. The advantage of this structure is that the client does not need to provide UIDs for these references, as this is handled automatically.

Note

Although nested payloads can be easier for clients to manage, the payload will always be flattened before the import. For large imports, using a flat structured payload offers more control and reduces overhead during the import process. However, you cannot nest new tracked entities, enrollments or events within a relationship.

{
  "trackedEntities": [
    {
      "enrollments": [
        {
          "attributes": [
            {
              "attribute": "zDhUuAYrxNC",
              "displayName": "Last name",
              "value": "Kelly"
            },
            {
              "attribute": "w75KJ2mc4zz",
              "displayName": "First name",
              "value": "John"
            }
          ],
          "enrolledAt": "2019-08-19T00:00:00.000",
          "events": [
            {
              "attributeCategoryOptions": "xYerKDKCefk",
              "attributeOptionCombo": "HllvX50cXC0",
              "dataValues": [
                {
                  "dataElement": "bx6fsa0t90x",
                  "value": "true"
                },
                {
                  "dataElement": "UXz7xuGCEhU",
                  "value": "5.7"
                }
              ],
              "enrollmentStatus": "ACTIVE",
              "notes": [
                {
                  "value": "need to follow up"
                }
              ],
              "occurredAt": "2019-08-01T00:00:00.000",
              "orgUnit": "y77LiPqLMoq",
              "program": "IpHINAT79UW",
              "programStage": "A03MvHHogjR",
              "scheduledAt": "2019-08-19T13:59:13.688",
              "status": "ACTIVE"
            }
          ],
          "occurredAt": "2019-08-19T00:00:00.000",
          "orgUnit": "y77LiPqLMoq",
          "program": "IpHINAT79UW",
          "status": "ACTIVE",
          "trackedEntityType": "nEenWmSyUEp"
        }
      ],
      "orgUnit": "y77LiPqLMoq",
      "trackedEntityType": "nEenWmSyUEp"
    }
  ]
}

Create¶

Make a POST request to /api/tracker with the importStrategy set to CREATE or CREATE_AND_UPDATE and a payload as described here.

Update¶

Make a POST request to /api/tracker with the importStrategy set to UPDATE or CREATE_AND_UPDATE and a payload as described here.

The payload must include all fields of the object you are updating, even if they have not been modified. The only exception is collections. Items in a collection that should not be changed can be omitted, as demonstrated in update attribute values and update data values.

Note

Deleted tracker objects and relationships cannot be updated.

Update attribute values¶

The following updates one of the attribute values of a tracked entity.

POST /api/tracker?async=false

{
  "trackedEntities": [
    {
      "trackedEntity": "PQfMcpmXeFE",
      "trackedEntityType": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "code": "MMD_PER_NAM",
          "displayName": "First name",
          "createdAt": "2016-08-03T23:49:43.308",
          "updatedAt": "2016-08-03T23:49:43.308",
          "valueType": "TEXT",
          "value": "Johnny"
        }
      ]
    }
  ]
}

Note that it is not necessary to specify the tracked entity's enrollments. However, you must specify the non-collection fields of the tracked entity, even if you are not changing them.

Delete attribute values¶

The following deletes one of the attribute values of a tracked entity:

POST /api/tracker?async=false

{
  "trackedEntities": [
    {
      "trackedEntity": "PQfMcpmXeFE",
      "trackedEntityType": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "value": null
        }
      ]
    }
  ]
}

Update data values¶

The following updates one of the data values of an event:

POST /api/tracker?async=false

{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": "true"
        }
      ],
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ]
}

Delete data values¶

The following deletes one of the data values of an event:

POST /api/tracker?async=false

{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": null
        }
      ],
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ]
}

Delete¶

Make a POST to /api/tracker with importStrategy set to DELETE. The payload should include only the UIDs of the trackedEntities, enrollments, events or relationships you wish to delete.

The following deletes the events created with this payload:

POST /api/tracker?async=false&importStrategy=DELETE

{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
    },
    {
      "event": "XwwuwNp6gVE",
    }
  ]
}

The following deletes the tracked entities and all its child tracker objects which are enrollments, events and relationships:

POST /api/tracker?async=false&importStrategy=DELETE

{
  "trackedEntities": [
    {
      "trackedEntity": "Kj6vYde4LHh",
    },
    {
      "trackedEntity": "Gjaiu3ea38E",
    }
  ]
}

All the children of a tracker object will be deleted if the user making the request has the authorities F_TEI_CASCADE_DELETE and F_ENROLLMENT_CASCADE_DELETE. Relationships linked to an entity are always deleted, without the need of any authority.

CSV import¶

To import events using CSV make a POST request with CSV body file and the Content-Type set to application/csv or text/csv.

Eventos¶

Every row of the CSV payload represents an event and a data value. So, for events with multiple data values, the CSV file will have x rows per event, where x is the number of data values in that event.

CSV payload example¶

Your CSV file can look like:

event,status,program,programStage,enrollment,orgUnit,occurredAt,scheduledAt,geometry,latitude,longitude,followUp,deleted,createdAt,createdAtClient,updatedAt,updatedAtClient,completedBy,completedAt,updatedBy,attributeOptionCombo,attributeCategoryOptions,assignedUser,dataElement,value,providedElsewhere,storedByDataValue,updatedAtDataValue,createdAtDataValue
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,F3ogKBuviRA,"[-11.4880220438585,7.50978830548003]",false,,2016-12-06T17:22:34.438Z,2016-12-06T17:22:34.438Z

See Events CSV in the export section for a more detailed definition of the CSV fields.

Import summary¶

The Tracker API has two primary endpoints for consumers to acquire feedback from their imports. These endpoints are most relevant for async import jobs but are available for sync jobs as well. These endpoints will return either the log related to the import or the import summary itself.

Note

These endpoints rely on information stored in the application memory. This means the information will be unavailable after certain cases, as an application restart or after a large number of import requests have started after this one.

After submitting a tracker import request, we can access the following endpoints in order to monitor the job progress based on logs:

GET /tracker/jobs/{uid}

Request parameter	Descrição	Exemplo
uid	The UID of a tracker import job	eAjkbUGBcZ5

Request example¶

GET /tracker/jobs/PQK63sMwjQp

Response example¶

[
  {
    "uid": "PQK63sMwjQp",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.370",
    "message": "Import complete with status OK, 0 created, 0 updated, 0 deleted, 0 ignored",
    "completed": true,
    "id": "PQK63sMwjQp"
  },
  {
    "uid": "XIfTJ1UUNcd",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.369",
    "message": "PostCommit",
    "completed": false,
    "id": "XIfTJ1UUNcd"
  },
  {
    "uid": "uCG4FNJLLBJ",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.364",
    "message": "Commit Transaction",
    "completed": false,
    "id": "uCG4FNJLLBJ"
  },
  {
    "uid": "xfOUv2Lk2MC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.361",
    "message": "Running Rule Engine Validation",
    "completed": false,
    "id": "xfOUv2Lk2MC"
  },
  {
    "uid": "cSPfA776obb",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.325",
    "message": "Running Rule Engine",
    "completed": false,
    "id": "cSPfA776obb"
  },
  {
    "uid": "t9gOjotekQt",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:15.837",
    "message": "Tracker import started",
    "completed": false,
    "dataType": "PARAMETERS",
    "data": {
      "userId": "xE7jOejl9FI",
      "importMode": "VALIDATE",
      "idSchemes": {
        "dataElementIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "orgUnitIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "programIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "programStageIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "idScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "categoryOptionComboIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "categoryOptionIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        }
      },
      "importStrategy": "CREATE_AND_UPDATE",
      "atomicMode": "ALL",
      "flushMode": "AUTO",
      "validationMode": "FULL",
      "skipPatternValidation": false,
      "skipSideEffects": false,
      "skipRuleEngine": false,
      "filename": null,
      "reportMode": "ERRORS"
    },
    "id": "t9gOjotekQt"
  }
]

Additionally, the following endpoint will return the import summary of the import job. This import summary will only be available after the import has completed:

GET /tracker/jobs/{uid}/report

Request parameter	Descrição	Exemplo
path `/{uid}`	ID of an existing tracker import job.	ABCDEF12345
reportMode	Level of detail for the report.	`FULL`, `ERRORS`, `WARNINGS`

Request example¶

GET /tracker/jobs/mEfEaFSCKCC/report

Response example¶

The response payload is the same as the one returned after a sync import request.

Note

Both endpoints are used primarily for async import; however, GET /tracker/jobs/{uid} would also work for sync requests as it eventually uses the same import process and logging as async requests.

Import summary response¶

Import summaries have the following overall structure, depending on the requested reportMode:

{
  "status": "OK",
  "validationReport": {
    "errorReports": [],
    "warningReports": []
  },
  "stats": {
    "created": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0,
    "total": 3
  },
  "bundleReport": {
    "typeReportMap": {
      "EVENT": {
        "trackerType": "EVENT",
        "stats": {
          "created": 1,
          "updated": 0,
          "deleted": 0,
          "ignored": 0,
          "total": 1
        },
        "objectReports": [
          {
            "trackerType": "EVENT",
            "uid": "gTZBPT3Jq39",
            "errorReports": []
          }
        ]
      },
      "ENROLLMENT": {
        "trackerType": "ENROLLMENT",
        "stats": {
          "created": 1,
          "updated": 0,
          "deleted": 0,
          "ignored": 0,
          "total": 1
        },
        "objectReports": [
          {
            "trackerType": "ENROLLMENT",
            "uid": "ffcvJvWjiNZ",
            "errorReports": []
          }
        ]
      },
      "RELATIONSHIP": {
        "trackerType": "RELATIONSHIP",
        "stats": {
          "created": 0,
          "updated": 0,
          "deleted": 0,
          "ignored": 0,
          "total": 0
        },
        "objectReports": []
      },
      "TRACKED_ENTITY": {
        "trackerType": "TRACKED_ENTITY",
        "stats": {
          "created": 1,
          "updated": 0,
          "deleted": 0,
          "ignored": 0,
          "total": 1
        },
        "objectReports": [
          {
            "trackerType": "TRACKED_ENTITY",
            "uid": "aVcGf9iO8Xp",
            "errorReports": []
          }
        ]
      }
    }
  }
}

Status¶

The property, status, of the import summary indicates the overall status of the import. If no errors or warnings were raised during the import, the status is reported as OK. The presence of any error or warnings in the import will result in a status of type ERROR or WARNING.

status is based on the presence of the most significant validationReport. ERROR has the highest significance, followed by WARNING and finally OK. This implies that ERROR is reported as long as a single error was found during the import, regardless of how many warnings occurred.

Note

If the import is performed using the AtomicMode "OBJECT", where the import will import any data without validation errors, the overall status will still be ERROR if any errors were found.

Validation report¶

The validationReport might include errorReports and warningReports if any errors or warnings were present during the import. When present, they provide a detailed list of any errors or warnings encountered.

For example, a validation error while importing a TRACKED_ENTITY:

{
  "validationReport": {
    "errorReports": [
      {
        "message": "Could not find TrackedEntityType: `Q9GufDoplCL`.",
        "errorCode": "E1005",
        "trackerType": "TRACKED_ENTITY",
        "uid": "Kj6vYde4LHh"
      }
    ],
    "warningReports": [
    ]
  }
}

The report contains a message and a code describing the actual error (See the error codes section for more information about errors). Additionally, the report includes the trackerType and uid, which aims to describe where in the data the error was found. In this case, there was a TRACKED_ENTITY with the uid Kj6vYde4LHh, which had a reference to a tracked entity type that was not found.

Note

When referring to the uid of tracker objects, they are labeled as their object names in the payload. For example, the uid of a tracked entity would in the payload have the name "trackedEntity". The same goes for "enrollment", "event" and "relationship" for enrollments, events, and relationships, respectively.

If no uid is provided in the payload, the import process will generate new uids. This means the error report might refer to a uid that does not exist in your payload.

Errors represent issues with the payload which the importer can not circumvent. Any errors will block that data from being imported. Warnings, on the other hand, are issues where it's safe to circumvent them, but the user should be made aware that it happened. Warnings will not block data from being imported.

Statistics¶

The stats object provides an overview of the import operation. After an import is completed, these will be the actual counts displaying how many objects were created, updated, deleted and ignored.

Resposta de exemplo:

{
  "stats": {
    "created": 2,
    "updated": 2,
    "deleted": 1,
    "ignored": 5,
    "total": 10
  }
}

The created field refers to how many new objects were created. In general, objects without an existing uid in the payload will be treated as new objects.

The updated field refers to the number of objects updated. If an object has a uid set in the payload, it will be treated as an update as long as that same uid exists in the database.

The deleted field refers to the number of objects deleted during the import. Deletion only happens when the import is configured to delete data and only then when the objects in the payload have existing uids set.

The ignored field refers to objects that were not persisted. Objects can be ignored for several reasons, for example trying to create something that already exists. Ignores should always be safe, so if something was ignored, it was not necessary, or it was due to the configuration of the import.

Bundle report¶

When the import is completed, the bundleReport contains all the tracker objects imported.

An example for TRACKED_ENTITY:

{
  "bundleReport": {
    "typeReportMap": {
      "TRACKED_ENTITY": {
        "trackerType": "TRACKED_ENTITY",
        "stats": {
          "created": 1,
          "updated": 0,
          "deleted": 0,
          "ignored": 0,
          "total": 1
        },
        "objectReports": [
          {
            "trackerType": "TRACKED_ENTITY",
            "uid": "aVcGf9iO8Xp",
            "errorReports": []
          }
        ]
      }
    }
  }
}

Each type of tracker object will be reported, and each has its own stats and objectReports. These objectReports will provide details about each imported object, like their type, their uid, and any error or warning reports if applicable.

Message¶

If the import ended abruptly, the message would contain further information in relation to what happened.

Import summary report level¶

A import summary report can be retrieved using a specific reportMode parameter in a GET /tracker/jobs/{uid}/report request. By default the endpoint will return an importSummary with reportMode ERROR.

Valor	Descrição
FULL	Returns everything from `WARNINGS`, plus `timingsStats`
WARNINGS	Returns everything from `ERRORS`, plus `warningReports` in `validationReports`
ERRORS (default)	Returns only `errorReports` in `validationReports`

In addition, all reportModes will return status, stats, bundleReport and message when applicable.

Error codes¶

There are various error codes for different error scenarios. The following table has the list of error codes thrown from the Tracker API, along with the error messages and some additional descriptions. The placeholders in the error messages ({0},{1},{2}..) are usually uids unless otherwise specified.

Error Code	Error Message	Descrição
E1000	User: `{0}`, has no write access to OrganisationUnit: `{1}`.	This typically means that the OrganisationUnit `{1}` is not in the capture scope of the user `{0}` for the write operation to be authorized.
E1001	User: `{0}`, has no data write access to TrackedEntityType: `{1}`.	The error occurs when the user is not authorized to create or modify data of the TrackedEntityType `{1}`
E1002	TrackedEntity: `{0}`, already exists.	This error is thrown when trying to create a new TrackedEntity with an already existing uid. Make sure a new uid is used when adding a new TrackedEntity.
E1003	User: `{0}`, has no write access to TrackedEntity: `{1}`.
E1005	Could not find TrackedEntityType: `{0}`.	Error thrown when trying to fetch a non existing TrackedEntityType with uid `{0}` . This might also mean that the user does not have read access to the TrackedEntityType.
E1006	Attribute: `{0}`, does not exist.	Error thrown when the system was not able to find a matching TrackedEntityAttribute with uid `{0}`. This might also mean that the user does not have access to the TrackedEntityAttribute.
E1007	Error validating attribute value type: `{0}`; Error: `{1}`.	Mismatch between value type of a TrackedEntityAttribute and its provided attribute value. The actual validation error will be displayed in `{1}`.
E1008	Program stage `{0}` has no reference to a program. Check the program stage configuration
E1009	File resource: `{0}`, has already been assigned to a different object.	The File resource uid `{0}` is already assigned to another object in the system.
E1010	Could not find Program: `{0}`, linked to Event.	The system was unable to find a Program with the uid `{0}` specified inside the Event payload. This might also mean that the specific Program is not accessible by the logged in user.
E1011	Could not find OrganisationUnit: `{0}`, linked to Event.	The system was unable to find a OrganisationUnit with uid `{0}` specified inside the Event payload.
E1012	Geometry does not conform to FeatureType: `{0}`.	FeatureType provided is either NONE or an incompatible one for the provided geometry value.
E1013	Could not find ProgramStage: `{0}`, linked to Event.	The system was unable to find a ProgramStage with uid `{0}` specified inside the Event payload. This might also mean that the ProgramStage is not accessible to the logged in user.
E1014	Provided Program: `{0}`, is a Program without registration. An Enrollment cannot be created into Program without registration.	Enrollments can only be created for Programs with registration.
E1015	TrackedEntity: `{0}`, already has an active Enrollment in Program `{1}`.	Cannot enroll into a Program if another active enrollment already exists for the Program. The active enrollment will have to be completed first at least.
E1016	TrackedEntity: `{0}`, already has an active enrollment in Program: `{1}`, and this program only allows enrolling one time.	As per the Program `{1}` configuration, a TrackedEntity can only be enrolled into that Program once. It looks like the TrackedEntity `{0}` already has either an ACTIVE or COMPLETED enrollment in that Program. Hence another enrollment cannot be added.
E1018	Attribute: `{0}`, is mandatory in program `{1}` but not declared in enrollment `{2}`.	Attribute value is missing in payload, for an attribute that is defined as mandatory for a Program. Make sure that attribute values for mandatory attributes are provided in the payload.
E1019	Only Program attributes is allowed for enrollment; Non valid attribute: `{0}`.	Attribute uid `{0}` specified in the enrollment payload is not associated with the Program.
E1020	Enrollment date: `{0}`, cannot be a future date.	Cannot enroll into a future date unless the Program allows for it in its configuration.
E1021	Incident date: `{0}`, cannot be a future date.	Incident date cannot be a future date unless the Program allows for it in its configuration.
E1022	TrackedEntity: `{0}`, must have same TrackedEntityType as Program `{1}`.	The Program is configured to accept TrackedEntityType uid that is different from what is provided in the enrollment payload.
E1023	DisplayIncidentDate is true but property occurredAt is null.	Program is configured with DisplayIncidentDate but it is null in the payload.
E1025	Property enrolledAt is null.	EnrolledAt Date is mandatory for an Enrollment. Make sure it is not null.
E1029	Event OrganisationUnit: `{0}`, and Program: `{1}`, don't match.	The Event payload uses a Program `{1}` which is not configured to be accessible by OrganisationUnit `{0}`.
E1030	Event: `{0}`, already exists.	This error is thrown when trying to add a new Event with an already existing uid. Make sure a new uid is used when adding a new Event.
E1031	Event occurredAt date is missing.	OccurredAt property is either null or has an invalid date format in the payload.
E1032	Event: `{0}`, do not exist.
E1033	Event: `{0}`, Enrollment value is NULL.
E1039	ProgramStage: `{0}`, is not repeatable and an event already exists.	An Event already exists for the ProgramStage for the specific Enrollment. Since the ProgramStage is configured to be non-repeatable, another Event for the same ProgramStage cannot be added.
E1041	Enrollment OrganisationUnit: `{0}`, and Program: `{1}`, don't match.	The Enrollment payload contains a Program `{1}` which is not configured to be accessible by the OrganisationUnit `{0}`.
E1043	Event: `{0}`, completeness date has expired. Not possible to make changes to this event.	A user without 'F_EDIT_EXPIRED' authority cannot update an Event that has passed its expiry days as configured in its Program.
E1046	Event: `{0}`, needs to have at least one (event or schedule) date.	Either of occurredAt or scheduledAt property should be present in the Event payload.
E1047	Event: `{0}`, date belongs to an expired period. It is not possible to create such event.	Event occurredAt or scheduledAt has a value that is earlier than the PeriodType start date.
E1049	Could not find OrganisationUnit: `{0}`, linked to Tracked Entity.	The system could not find an OrganisationUnit with uid `{0}`.
E1050	Event ScheduledAt date is missing.	ScheduledAt property in the Event payload is either missing or an invalid date format.
E1051	Event: `{0}`, completedAt must be null when status is `{1}`.	Event completedAt can only be passed in the payload if status is COMPLETED
E1052	Enrollment: `{0}`, completedAt must be null when status is `{1}`.	Enrollment completedAt can only be passed in the payload if status is COMPLETED
E1054	AttributeOptionCombo `{0}` is not in the event programs category combo `{1}`.
E1055	Default AttributeOptionCombo is not allowed since program has non-default CategoryCombo.	The Program is configured to contain non-default CategoryCombo but the request uses the Default AttributeOptionCombo.
E1056	Event date: `{0}`, is before start date: `{1}`, for AttributeOption: `{2}`.	The CategoryOption has a start date configured , the Event date in the payload cannot be earlier than this start date.
E1057	Event date: `{0}`, is after end date: `{1}`, for AttributeOption; `{2}`.	The CategoryOption has an end date configured, the Event date in the payload cannot be later than this end date.
E1063	TrackedEntity: `{0}`, does not exist.	Error thrown when trying to fetch a non existing TrackedEntity with uid `{0}` . This might also mean that the user does not have read access to the TrackedEntity.
E1064	Non-unique attribute value `{0}` for attribute `{1}`	The attribute value has to be unique within the defined scope. The error indicates that the attribute value already exists for another TrackedEntity.
E1068	Could not find TrackedEntity: `{0}`, linked to Enrollment.	The system could not find the TrackedEntity specified in the Enrollment payload. This might also mean that the user does not have read access to the TrackedEntity.
E1069	Could not find Program: `{0}`, linked to Enrollment.	The system could not find the Program specified in the Enrollment payload. This might also mean that the user does not have read access to the Program.
E1070	Could not find OrganisationUnit: `{0}`, linked to Enrollment.	The system could not find the OrganisationUnit specified in the Enrollment payload.
E1074	FeatureType is missing.
E1075	Attribute: `{0}`, is missing uid.
E1076	`{0}` `{1}` is mandatory and can't be null
E1077	Attribute: `{0}`, text value exceed the maximum allowed length: `{0}`.
E1079	Event: `{0}`, program: `{1}` is different from program defined in enrollment `{2}`.
E1080	Enrollment: `{0}`, already exists.	This error is thrown when trying to create a new Enrollment with an already existing uid. Make sure a new uid is used when adding a new Enrollment.
E1081	Enrollment: `{0}`, do not exist.	Error thrown when trying to fetch a non existing Enrollment with uid `{0}` . This might also mean that the user does not have read access to the Enrollment.
E1082	Event: `{0}`, is already deleted and can't be modified.	If the event is soft deleted, no modifications on it are allowed.
E1083	User: `{0}`, is not authorized to modify completed events.	Only a super user or a user with the authority "F_UNCOMPLETE_EVENT" can modify completed events. Completed Events are those Events with status as COMPLETED.
E1089	Event: `{0}`, references a Program Stage `{1}` that does not belong to Program `{2}`.	The ProgramStage uid and Program uid in the Event payload is incompatible.
E1090	Attribute: `{0}`, is mandatory in tracked entity type `{1}` but not declared in tracked entity `{2}`.	The payload has missing values for mandatory TrackedEntityTypeAttributes.
E1091	User: `{0}`, has no data write access to Program: `{1}`.	The Program sharing configuration is such that, the user does not have write access for this Program.
E1095	User: `{0}`, has no data write access to ProgramStage: `{1}`.	The ProgramStage sharing configuration is such that, the user does not have write access for this ProgramStage.
E1096	User: `{0}`, has no data read access to Program: `{1}`.	The Program sharing configuration is such that, the user does not have read access for this Program.
E1099	User: `{0}`, has no write access to CategoryOption: `{1}`.	The CategoryOption sharing configuration is such that, the user does not have write access for this CategoryOption
E1100	User: `{0}`, is lacking 'F_TEI_CASCADE_DELETE' authority to delete TrackedEntity: `{1}`.	There exists undeleted Enrollments for this TrackedEntity. If the user does not have 'F_TEI_CASCADE_DELETE' authority, then these Enrollments has to be deleted first explicitly to be able to delete the TrackedEntity.
E1102	User: `{0}`, does not have access to the tracked entity: `{1}`, Program: `{2}`, combination.	This error is thrown when the user's OrganisationUnit does not have the ownership of this TrackedEntity for this specific Program. The owning OrganisationUnit of the TrackedEntity-Program combination should fall into the capture scope (in some cases the search scope) of the user.
E1103	User: `{0}`, is lacking 'F_ENROLLMENT_CASCADE_DELETE' authority to delete Enrollment : `{1}`.	There exists undeleted Events for this Enrollment. If the user does not have 'F_ENROLLMENT_CASCADE_DELETE' authority, then these Events has to be deleted first explicitly to be able to delete the Enrollment.
E1104	User: `{0}`, has no data read access to program: `{1}`, TrackedEntityType: `{2}`.	The sharing configuration of the TrackedEntityType associated with the Program is such that, the user does not have data read access to it.
E1112	Attribute value: `{0}`, is set to confidential but system is not properly configured to encrypt data.	Either JCE files is missing or the configuration property `encryption.password` might be missing in `dhis.conf`.
E1113	Enrollment: `{0}`, is already deleted and can't be modified.	If the Enrollment is soft deleted, no modifications on it are allowed.
E1114	TrackedEntity: `{0}`, is already deleted and can't be modified.	If the TrackedEntity is soft deleted, no modifications on it are allowed.
E1115	Could not find CategoryOptionCombo: `{0}`.
E1116	Could not find CategoryOption: `{0}`.	This might also mean the CategoryOption is not accessible to the user.
E1117	CategoryOptionCombo does not exist for given category combo and category options: `{0}`.
E1118	Assigned user `{0}` is not a valid uid.
E1119	A Tracker Note with uid `{0}` already exists.
E1120	ProgramStage `{0}` does not allow user assignment	Event payload has assignedUserId but the ProgramStage is not configured to allow user assignment.
E1121	Missing required tracked entity property: `{0}`.
E1122	Missing required enrollment property: `{0}`.
E1123	Missing required event property: `{0}`.
E1124	Missing required relationship property: `{0}`.
E1125	Value `{0}` is not a valid option code in option set `{1}`
E1126	Not allowed to update Tracked Entity property: {0}.
E1127	Not allowed to update Enrollment property: {0}.
E1128	Not allowed to update Event property: {0}.
E1300	Generated by program rule (`{0}`) - `{1}`
E1301	Generated by program rule (`{0}`) - Mandatory DataElement `{1}` is not present
E1302	DataElement `{0}` is not valid: `{1}`
E1303	Mandatory DataElement `{0}` is not present
E1304	DataElement `{0}` is not a valid data element
E1305	DataElement `{0}` is not part of `{1}` program stage
E1306	Generated by program rule (`{0}`) - Mandatory Attribute `{1}` is not present
E1307	Generated by program rule (`{0}`) - Unable to assign value to data element `{1}`. The provided value must be empty or match the calculated value `{2}`
E1308	Generated by program rule (`{0}`) - DataElement `{1}` is being replaced in event `{2}`
E1309	Generated by program rule (`{0}`) - Unable to assign value to attribute `{1}`. The provided value must be empty or match the calculated value `{2}`
E1310	Generated by program rule (`{0}`) - Attribute `{1}` is being replaced in te `{2}`
E1313	Event {0} of an enrollment does not point to an existing tracked entity. The data in your system might be corrupted	Indicates an anomaly in the existing data whereby enrollments might not reference a tracked entity
E1314	Generated by program rule (`{0}`) - DataElement `{1}` is mandatory and cannot be deleted.
E1315	Status `{0}` does not allow defining data values. Statuses that do allow defining data values are: {1}
E1316	No event can transition from status `{0}` to status `{1}`.
E1317	Generated by program rule (`{0}`) - Attribute `{1}` is mandatory and cannot be deleted.
E4000	Relationship: `{0}` cannot link to itself
E4001	Relationship Item `{0}` for Relationship `{1}` is invalid: an Item can link only one Tracker entity.
E4006	Could not find relationship Type: `{0}`.
E4010	Relationship Type `{0}` constraint requires a {1} but a {2} was found.
E4012	Could not find `{0}`: `{1}`, linked to Relationship.
E4014	Relationship type `{0}` constraint requires a tracked entity having type `{1}` but `{2}` was found.
E4015	Relationship: `{0}`, already exists.
E4016	Relationship: `{0}`, do not exist.
E4017	Relationship: `{0}`, is already deleted and cannot be modified.
E4018	Relationship: `{0}`, linking {1}: `{2}` to {3}: `{4}` already exists.
E4020	User: `{0}`, has no write access to relationship: `{1}`.
E5000	"{0}" `{1}` cannot be persisted because "{2}" `{3}` referenced by it cannot be persisted.	The importer can't persist a tracker object because a reference cannot be persisted.
E9999	N/D	Undefined error message.

Validation¶

While importing data using the tracker importer, a series of validations are performed to ensure the validity of the data. This section will describe some of the different types of validation performed to provide a better understanding if validation fails for your import.

Required properties¶

Each of the tracker objects has a few required properties that need to be present when importing data. For an exhaustive list of required properties, have a look at the tracker objects section.

When validating required properties, we are usually talking about references to other data or metadata. In these cases, there are three main criteria:

The reference is present and not null in the payload.
The reference points to the correct type of data and exists in the database
The user has access to see the reference

If the first condition fails, the import will fail with a message about a missing reference. However, suppose the reference points to something that doesn't exist or which the user cannot access. In that case, both cases will result in a message about the reference not being found.

Formats¶

Some of the properties of tracker objects require a specific format. When importing data, each of these properties is validated against the expected format and will return different errors depending on which property has a wrong format. Some examples of properties that are validated this way:

UIDs (These cover all references to other data or metadata in DHIS2.)
Dates
Geometry (The coordinates must match the format as specified by its type)

User access¶

All data imported will be validated based on the metadata (sharing) and the organisation units (scopes) referenced in the data. You can find more information about sharing and organisation unit scopes in the following sections.

Sharing is validated at the same time as references are looked up in the database. Metadata outside of the user access scope will be treated as if it does not exist. The import will validate any metadata referenced in the data.

Organisation units, on the other hand, serve a dual purpose. It will primarily make sure that data can only be imported when imported for an organisation unit the user has within their capture scope. Secondly, organisation units are also used to restrict what programs are available. That means if you are trying to import data for an organisation unit that does not have access to the Program you are importing, the import will be invalid.

Users with the ALL authority will ignore the limits of sharing and organisation unit scopes when they import data. However, they can not import enrollments in organisation units that do not have access to the enrollment program.

Attributes and data values¶

Attributes and data values are part of a tracked entity and an event, respectively. However, attributes can be linked to a tracked entity either through its type (TrackedEntityType) or its Program (Program). Additionally, attributes can also be unique.

The initial validation done in the import is to make sure the value provided for an attribute or data element conforms to the type of value expected. For example, suppose you import a value for a data element with a numeric type. In that case, the value is expected to be numeric. Any errors related to a mismatch between a type and a value will result in the same error code but with a specific message related to the type of violation.

Mandatory attributes and data values are also checked on creation, on update mandatory attributes and data values are not required in the payload. Currently, removing mandatory attributes and data values is never allowed. Some use-cases require values to be sent separately, while others require all values to be sent as one. Programs can be configured to either validate mandatory attributes ON_COMPLETE or ON_UPDATE_AND_INSERT to accommodate these use-cases.

The import will validate unique attributes at the time of import. That means as long as the provided value is unique for the attribute in the whole system, it will pass. However, if the unique value is found to be used by any other tracked entity other than the one being imported, it will fail.

Configuração¶

The last part of validations in the importer are validations based on the user's configuration of relevant metadata. For more information about each configuration, check out the relevant sections. Some examples of configurable validations:

Feature type (geometry)
User-assignable events
Allow future dates
Enroll once

These configurations will further change how validation is performed during import.

Generated tracked entity attributes¶

Tracked entity attributes that use automatic generation of unique values have three endpoints utilized by apps for generating and reserving these values.

Required values¶

A TextPattern may include variables that change based on different factors. Some of these factors are unknown to the server; thus, the values for these variables must be supplied when generating and reserving values.

This endpoint returns a map of required and optional values that the server will inject into the TextPattern when generating new values. Required variables must be supplied for generation, whereas optional variables should only be provided if necessary.

GET /api/trackedEntityAttributes/Gs1ICEQTPlG/requiredValues

{
  "REQUIRED": [
    "ORG_UNIT_CODE"
  ],
  "OPTIONAL": [
    "RANDOM"
  ]
}

Gerar valor-limite¶

Online web apps and other clients can use this endpoint to generate a unique value for immediate use. The generated value is guaranteed to be unique at the time of generation and is reserved for 3 days. If your TextPattern includes required values, they can be passed as parameters.

To override the expiration time, add ?expiration=<number-of-days> to the request.

GET /api/trackedEntityAttributes/Gs1ICEQTPlG/generate?ORG_UNIT_CODE=OSLO

{
  "ownerObject": "TRACKEDENTITYATTRIBUTE",
  "ownerUid": "Gs1ICEQTPlG",
  "key": "RANDOM(X)-OSL",
  "value": "C-OSL",
  "created": "2018-03-02T12:01:36.680",
  "expiryDate": "2018-03-05T12:01:36.678"
}

Gerar e reservar valor final¶

Offline clients can use this endpoint to reserve a number of unique IDs for later use when registering new tracked entities. The number of IDs to generate can be specified with the numberToReserve parameter (default is 1).

To override the default expiration time of 60 days, add ?expiration=<number-of-days> to the request.

GET /api/trackedEntityAttributes/Gs1ICEQTPlG/generateAndReserve?numberToReserve=3&ORG_UNIT_CODE=OSLO

[
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "B-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  },
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "Q-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  },
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "S-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  }
]

Valores reservados¶

Reserved values are currently not accessible through the api, however, they are returned by the generate and generateAndReserve endpoints. The following table explains the properties of the reserved value object:

Reserved values
Property	Descrição
ownerObject	The metadata type referenced when generating and reserving the value. Currently only TRACKEDENTITYATTRIBUTE is supported.
ownerUid	The uid of the metadata object referenced when generating and reserving the value.
key	A partially generated value where generated segments are not yet added.
value	The fully resolved value reserved. This is the value you send to the server when storing data.
created	The timestamp when the reservation was made
expiryDate	The timestamp when the reservation will no longer be reserved

Expired reservations are removed daily. If a pattern changes, values that were already reserved will be accepted when storing data, even if they don't match the new pattern, as long as the reservation has not expired.

Program rules¶

Users can configure program rules, which adds conditional behavior to tracker forms. In addition to running these rules in the tracker apps, the tracker importer will also run a selection of these rules. Since the importer is also running these rules, we can ensure an additional level of validation.

Not all program rule actions are supported since they are only suitable for a frontend presentation. A complete list of the supported program rule actions is presented below.

Program rule action	Suportado
DISPLAYTEXT
DISPLAYKEYVALUEPAIR
HIDEFIELD
HIDESECTION
ASSIGN	X
SHOWWARNING	X
SHOWERROR	X
WARNINGONCOMPLETION	X
ERRORONCOMPLETION	X
CREATEEVENT
SETMANDATORYFIELD	X
SENDMESSAGE	X
SCHEDULEMESSAGE	X

Program rules are evaluated in the importer in the same way they are evaluated in the tracker apps. To summarize, the following conditions are considered when enforcing the program rules:

The program rule must be linked to the data being imported. For example, a program stage or a data element.
The program rule condition must be evaluated to true.

The results of the program rules depend on the actions defined in those rules:

Program rule actions may end in 2 different results: warnings or errors.
Errors will make the validation fail, while the warnings will be reported as a message in the import summary.
- SHOWWARNING and WARNINGONCOMPLETION actions can generate only warnings.
- SHOWERROR, ERRORONCOMPLETION, and SETMANDATORYFIELD actions can generate only errors.
- ASSIGN action can generate both Warnings and Errors.
- When the action is assigning a value to an empty attribute/data element, a warning is generated.
- When the action is assigning a value to an attribute/data element that already has the same value to be assigned, a warning is generated.
- When the action is assigning a value to an attribute/data element that already has a value and the value to be assigned is different, an error is generated unless the RULE_ENGINE_ASSIGN_OVERWRITE system setting is true.

Additionally, program rules can also result in side-effects, like send and schedule messages. More information about side effects can be found in the following section.

Note

Program rules can be skipped during import using the skipProgramRules parameter.

Side effects¶

After an import has been completed, specific tasks might be triggered as a result of the import. These tasks are what we refer to as "Side effects". These tasks perform operations that do not affect the import itself.

Side effects are tasks running detached from the import but are always triggered by an import. Since side effects are detached from the import, they can fail even when the import is successful. Additionally, side effects are only run when the import is successful, so they cannot fail the other way around.

The following side effects are currently supported:

Side Effects	Suportado	Descrição
Tracker Notification	X	Updates can trigger notifications. Updates which trigger notifications are enrollment, event update, event or enrollment completion.
ProgramRule Notification	X	Program rules can trigger notifications. Note that these notifications are part of program rule effects which are generated through the DHIS2 rule engine.

Note

Certain configurations can control the execution of side effects. skipSideEffects flag can be set during the import to skip side effects entirely. This parameter can be useful if you import something you don't want to trigger notifications for, as an example.

Assign user to events¶

Specific workflows benefit from treating events like tasks, and for this reason, you can assign a user to an event.

Assigning a user to an event will not change the access or permissions for users but will create a link between the Event and the user. When an event has a user assigned, you can query events from the API using the assignedUser field as a parameter.

When you want to assign a user to an event, you simply provide the UID of the user you want to assign in the assignedUser field. See the following example:

{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "programStage": "nlXNK4b7LVr",
      "orgUnit": "O6uvpzGd5pu",
      "enrollment": "MNWZ6hnuhSw",
      "assignedUser" : "M0fCOxtkURr"
    }
  ]
}

In this example, the user with uid M0fCOxtkURr will be assigned to the event with uid ZwwuwNp6gVd. Only one user can be assigned to a single event.

To use this feature, the relevant program stage needs to have user assignment enabled, and the uid provided for the user must refer to a valid, existing user.

Tracker export¶

Tracker export endpoints allow you to retrieve the previously imported objects which are:

Entidades rastreadas
Eventos
Enrollments
Relacionamentos

Note

All tracker export endpoints default to a JSON response content. CSV is only supported by tracked entities and events.

You can export a CSV file by adding the Accept header text/csv or application/csv to the request.

You can download in zip and gzip formats:

CSV for Tracked entities

JSON and CSV for Events

You can export a Gzip file by adding the Accept header application/csv+gzip for CSV or application/json+gzip for JSON.

You can export a Zip file by adding the Accept header application/csv+zip for CSV or application/json+zip for JSON.

Common request parameters¶

The following endpoints support standard pagination parameters.

Tracked entities: GET /api/tracker/trackedEntities
Events: GET /api/tracker/events
Enrollments: GET /api/tracker/enrollments
Relationships: GET /api/tracker/relationships

Request parameters for pagination¶

Request parameter	Modelo	Allowed values	Descrição
page	Inteiro	Any positive integer	Page number to return. Defaults to 1.
pageSize	Inteiro	Any positive integer	Page size. Defaults to 50.
totalPages	Boolean	`true`, `false`	Indicates whether to return the total number of elements and pages. Defaults to `false` as getting the totals is an expensive operation.
paging	Boolean	`true`, `false`	Indicates whether paging should be ignored and all rows should be returned. Defaults to `true`, meaning that by default all requests are paginated, unless `paging=false`.
order	Corda		Comma-separated list of field and sort direction pairs in format `field:sortDirection`. Example: `createdAt:desc` Entities are ordered by newest (internal ID descending) by default. Note: `field` is case sensitive. Valid `sortDirections` are `asc` and `desc`, where `sortDirection` is case insensitive, and `sortDirection` defaults to `asc` for fields or UIDs without explicit `sortDirection`.

Note

Be aware that performance is directly related to the amount of data requested. Greater page sizes will take more time to return.

Organisation unit selection modes¶

The available organisation unit selection modes are SELECTED, CHILDREN, DESCENDANTS, ACCESSIBLE, CAPTURE and ALL. Each mode is explained in detail in this section.

Field filter responses¶

All export endpoints accept a fields parameter which controls which fields will be returned in the JSON response. fields parameter accepts a comma separated list of field names or patterns. A few possible fields filters are shown below. Refer to Metadata field filter for a more complete guide on how to use fields.

Exemplos¶

Query parameter example	Descrição
fields=*	Returns all fields
fields=createdAt,uid	Returns fields `createdAt` and `uid`
fields=enrollments[*,!uid]	Returns all fields of `enrollments` except `uid`
fields=enrollments[uid]	Returns `enrollments` field `uid`
fields=enrollments[uid,enrolledAt]	Returns `enrollments` fields `uid` and `enrolledAt`

Tracked entities¶

GET /api/tracker/trackedEntities

Two endpoints are dedicated to tracked entities:

GET /api/tracker/trackedEntities
retrieves tracked entities matching given criteria
GET /api/tracker/trackedEntities/{id}
retrieves a tracked entity given the provided ID

If not otherwise specified, JSON is the default response for the GET method. The API also supports CSV export for single and collection endpoints. Furthermore, compressed CSV types is an option for the collection endpoint.

CSV¶

In the case of CSV, the fields request parameter has no effect, and the response will always contain the following fields:

trackedEntity (UID)
trackedEntityType (identifier in requested idScheme)
createdAt (Datetime)
createdAtClient (Datetime)
updatedAt (Datetime)
updatedAtClient (Datetime)
orgUnit (identifier in requested idScheme)
inactive (boolean)
deleted (boolean)
potentialDuplicate (boolean)
geometry (WKT) You can omit it in case of a Point type and with latitude and longitude provided)
latitude (Latitude of a Point type of Geometry)
longitude (Longitude of a Point type of Geometry)
attribute (identifier in requested idScheme)
displayName (String)
attrCreatedAt (Attribute creation Datetime)
attrUpdatedAt (Attribute last update Datetime)
valueType (String)
value (String)
storedBy (String)
createdBy (Username of user)
updatedBy (Username of user)

See Tracked Entities and Attributes for more field descriptions.

GZIP¶

The response is file trackedEntities.csv.gz containing the trackedEntities.csv file.

ZIP¶

The response is file trackedEntities.csv.zip containing the trackedEntities.csv file.

Tracked entity collections¶

GET /api/tracker/trackedEntities

The purpose of this endpoint is to retrieve tracked entities matching client-provided criteria.

The endpoint returns a list of tracked entities that match the request parameters.

Request parameter	Modelo	Allowed values	Descrição
filter	Corda	Comma separated values of attribute filters.	Narrows response to tracked entities matching given filters. More on filters here
orgUnits	Corda	Comma-separated list of organisation unit `UID`s.	Only return tracked entities belonging to provided organisation units
orgUnitMode	Corda	`SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`	Get tracked entities owned by given `orgUnits` relative to the `orgUnitMode` and `program` parameters. Defaults to `ACCESSIBLE` if no organisation unit(s) are set via `orgUnits`. Defaults to `SELECTED` if organisation unit(s) are set via `orgUnits`. See org unit modes.
“Registro de Casos de Malária”	Corda	Program `UID`	A tracker program `UID` for which tracked entities in the response must be enrolled into.
programStatus deprecated for removal in version 43 use `enrollmentStatus`	`String`	`ACTIVE`, `COMPLETED`, `CANCELLED`	The status of the tracked entities enrollment in the given program.
programStage	Corda	`UID`	A program stage `UID` for which tracked entities in the response must have events for.
followUp	Boolean	`true`, `false`	Indicates whether the tracked entity is marked for follow up for the specified program.
updatedAfter	DateTime	ISO-8601	Start date and time for last updated
updatedBefore	DateTime	ISO-8601	End date and time for last updated
updatedWithin	Duration	ISO-8601	Returns tracked entities not older than specified Duration
enrollmentStatus	Corda	`ACTIVE`, `COMPLETED`, `CANCELLED`	The status of the tracked entities enrollment in the given program.
enrollmentEnrolledAfter	DateTime	ISO-8601	Start date and time for enrollment in the given program
enrollmentEnrolledBefore	DateTime	ISO-8601	End date and time for enrollment in the given program
enrollmentOccurredAfter	DateTime	ISO-8601	Start date for when the enrollment occurred in the given program
enrollmentOccurredBefore	DateTime	ISO-8601	End date for when the enrollment occurred in the given program
trackedEntityType	Corda	UID of tracked entity type	Only returns tracked entities of given type.
trackedEntities	Corda	Comma-separated list of tracked entity `UID`s.	Filter the result down to a limited set of tracked entities using explicit uids of the tracked entities by using `trackedEntity=id1,id2`. This parameter will, at the very least, create the outer boundary of the results, forming the list of all tracked entities using the uids provided. If other parameters/filters from this table are used, they will further limit the results from the explicit outer boundary.
assignedUserMode	Corda	`CURRENT`, `PROVIDED`, `NONE`, `ANY`, `ALL`	Restricts result to tracked entities with events assigned based on the assigned user selection mode. See table below "Assigned user modes" for explanations. Default is `ALL`.
assignedUsers	Corda	Comma-separated list of user UIDs to filter based on events assigned to the users.	Filter the result down to a limited set of tracked entities with events that are assigned to the given user IDs by using `assignedUser=id1,id2`. This parameter will only be considered if `assignedUserMode` is either `PROVIDED` or `null`. The API will error out, if for example, `assignedUserMode=CURRENT` and `assignedUser=someId`.
order	Corda	Comma-separated list of property name or attribute or UID and sort direction pairs in format `propName:sortDirection`.	Supported values are `createdAt, createdAtClient, enrolledAt, inactive, trackedEntity, updatedAt, updatedAtClient`.
eventStatus	Corda	`ACTIVE`, `COMPLETED`, `VISITED`, `SCHEDULE`, `OVERDUE`, `SKIPPED`	Status of any events in the specified program
eventOccurredAfter	DateTime	ISO-8601	Start date and time for Event for the given Program
eventOccurredBefore	DateTime	ISO-8601	End date and time for Event for the given Program
includeDeleted	Boolean	`true`, `false`	Indicates whether to include soft-deleted elements
potentialDuplicate	Boolean	`true`, `false`	Filter the result based on the fact that a tracked entities is a potential duplicate. `true`: returns tracked entities flagged as potential duplicates. `false`: returns tracked entities NOT flagged as potential duplicates.
idScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is `UID`. Note: only metadata in fields `trackedEntity.trackedEntityType`, `orgUnit` and `attributes` is exported in this idScheme. All other fields will always be exported using UIDs.
orgUnitIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for organisation unit references. Defaults to the `idScheme` parameter.

The available assigned user modes are explained in the following table.

Assigned user modes
Mode	Descrição
CURRENT	Includes events assigned to the current logged in user.
PROVIDED	Includes events assigned to the user provided in the request.
NONE	Includes unassigned events only.
ANY	Includes all assigned events, regardless of who they are assigned to, as long as they are assigned to someone.
TODOS	Includes all events irrespective of whether a user is assigned. This is the default mode.

The query is case insensitive. The following rules apply to the query parameters.

At least one organisation unit must be specified using the orgUnit parameter (one or many), or orgUnitMode=ALL must be specified.
Only one of the program and trackedEntity parameters can be specified (zero or one).
If programStatus is specified, then program must also be specified.
If enrollmentStatus is specified, then program must also be specified.
If followUp is specified, then program must also be specified.
If enrollmentEnrolledAfter or enrollmentEnrolledBefore is specified then program must also be specified.
Os itens do filtro só podem ser especificados uma vez.

Example requests¶

A query for all tracked entities associated with a specific organisation unit and tracker program can look like this:

GET /api/tracker/trackedEntities?program=IpHINAT79UW&orgUnits=DiszpKrYNg8

To query for tracked entities using one attribute with a filter and one attribute without a filter, with one organisation unit using the descendant organisation unit query mode:

GET /api/tracker/trackedEntities?program=IpHINAT79UW&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:EQ:John

A query where multiple operand and filters are specified for a filter item:

GET /api/tracker/trackedEntities?orgUnits=DiszpKrYNg8&program=ur1Edk5Oe2n&filter=lw1SqmMlnfh:GT:150&filter=lw1SqmMlnfh:LT:190

A query filter with a value that needs escaping and will be interpreted as :,/:

GET /api/tracker/trackedEntities?orgUnits=DiszpKrYNg8&program=ur1Edk5Oe2n&filter=lw1SqmMlnfh:EQ:/:/,//

Para especificar as datas de inscrição no programa como parte da consulta:

GET /api/tracker/trackedEntities?orgUnits=DiszpKrYNg8&program=IpHINAT79UW&fields=trackedEntity,enrollments[enrolledAt]&enrollmentEnrolledAfter=2024-01-01

To query on an attribute using multiple values with an IN filter and semicolon-separated values:

GET /api/tracker/trackedEntities?trackedEntityType=nEenWmSyUEp&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:IN:Scott;Jimmy;Santiago

All of the following operators are supported regardless of the value type. Values are compared using text comparison unless stated otherwise. Integer and decimal value types are treated as PostgreSQL integer and numeric data types for the specified operators.

Supported binary operators:

Operator	Descrição
eq	equal to, uses integer/numeric semantics for integer/decimal value types
ieq	equal to, ignoring case (use `eq` instead)*
ge	greater than or equal to (uses integer/number semantics for integer/decimal value types)
gt	greater than, uses integer/number semantics for integer/decimal value types
le	less than or equal to, uses integer/number semantics for integer/decimal value types
lt	less than (uses integer/number semantics for integer/decimal value types)
ne	not equal to (uses integer/number semantics for integer/decimal value types)
neq	not equal to (uses integer/number semantics for integer/decimal value types), use `ne` instead*
nieq	not equal to, ignoring case (use `ne` instead)*
in	one of multiple values separated by semicolon ";", uses integer/number semantics for integer/decimal value types
like	like text match
ilike	like text match, ignoring case (use `like` instead)*
nlike	not like
nilike	not like, ignoring case (use `nlike` instead)*
sw	starts with
ew	ends with

*These operators are currently supported but may be removed in the future. We recommend using the operator mentioned in the description, as it provides the same functionality.

Matches are case-insensitive, for example eq and ieq (i for insensitive) behave in the same way. To ensure future compatibility, always use the non-i form (eq, like, etc.).

For instance, filter=w75KJ2mc4zz:eq:Scott would return values of the given attribute that match any variation of "Scott" regardless of case, such as SCOTT, scott, Scott...

Supported unary operators:

Operator	Descrição
null	has no value
!null	has a value

Tracked entity attribute filtering¶

Filtering by a tracked entity attribute narrows the response to tracked entities matching given filters. A filter is a colon separated property or attribute UID with optional operator and value pairs.

Example: filter=H9IlTX2X6SL:sw:A with operator starts with sw followed by a value.

A filter like filter=H9IlTX2X6SL:!null returns all entries where the given attribute has a value.

Special characters like + need to be percent-encoded, so %2B instead of +. Characters such as : or ,, as part of the filter value, need to be escaped by /. Likewise, / needs to be escaped.

Multiple operators for the same attribute like filter=AuPLng5hLbE:gt:438901703:lt:448901704 are allowed.

Each tracked entity attribute can be configured with: - A minimum number of characters required to perform a search (0 means no minimum) - Blocked operators. Only sw, ew, and like can be blocked. All other operators cannot be blocked.

The following request:

GET /api/tracker/trackedEntities?program=IpHINAT79UW&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:EQ:John

would fail if the minimum character limit was set to 5 (since "John" has only 4 characters), or if the EQ operator was blocked for the specified tracked entity attribute.

Tracked entities response¶

The API supports CSV and JSON response for GET /api/tracker/trackedEntities.

JSON¶

Responses can be filtered on desired fields, see field filter for more information.

A JSON response looks like the following:

{
  "pager": {
    "page": 1,
    "pageSize": 1
  },
  "trackedEntities": [
    {
      "trackedEntity": "F8yKM85NbxW",
      "trackedEntityType": "Zy2SEgA61ys",
      "createdAt": "2019-08-21T13:25:38.022",
      "createdAtClient": "2019-03-19T01:12:16.624",
      "updatedAt": "2019-08-21T13:31:33.410",
      "updatedAtClient": "2019-03-19T01:12:16.624",
      "orgUnit": "DiszpKrYNg8",
      "inactive": false,
      "deleted": false,
      "potentialDuplicate": false,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -11.7896,
          8.2593
        ]
      },
      "attributes": [
        {
          "attribute": "B6TnnFMgmCk",
          "displayName": "Age (years)",
          "createdAt": "2019-08-21T13:25:38.477",
          "updatedAt": "2019-08-21T13:25:38.477",
          "storedBy": "braimbault",
          "valueType": "INTEGER_ZERO_OR_POSITIVE",
          "value": "30"
        },
        {
          "attribute": "TfdH5KvFmMy",
          "displayName": "First Name",
          "createdAt": "2019-08-21T13:25:38.066",
          "updatedAt": "2019-08-21T13:25:38.067",
          "storedBy": "josemp10",
          "valueType": "TEXT",
          "value": "Sarah"
        },
        {
          "attribute": "aW66s2QSosT",
          "displayName": "Last Name",
          "createdAt": "2019-08-21T13:25:38.388",
          "updatedAt": "2019-08-21T13:25:38.388",
          "storedBy": "karoline",
          "valueType": "TEXT",
          "value": "Johnson"
        }
      ]
    }
  ]
}

CSV¶

A CSV response looks like the following:

trackedEntity,trackedEntityType,createdAt,createdAtClient,updatedAt,updatedAtClient,orgUnit,inactive,deleted,potentialDuplicate,geometry,latitude,longitude,storedBy,createdBy,updatedBy,attrCreatedAt,attrUpdatedAt,attribute,displayName,value,valueType
F8yKM85NbxW,Zy2SEgA61ys,2019-08-21T11:25:38.022Z,2019-03-19T00:12:16.624Z,2019-08-21T11:31:33.410Z,2019-03-19T00:12:16.624Z,DiszpKrYNg8,false,false,false,"POINT (-11.7896 8.2593)",8.2593,-11.7896,,,,2019-08-21T11:25:38.477Z,2019-08-21T11:25:38.477Z,B6TnnFMgmCk,"Age (years)",30,INTEGER_ZERO_OR_POSITIVE
F8yKM85NbxW,Zy2SEgA61ys,2019-08-21T11:25:38.022Z,2019-03-19T00:12:16.624Z,2019-08-21T11:31:33.410Z,2019-03-19T00:12:16.624Z,DiszpKrYNg8,false,false,false,"POINT (-11.7896 8.2593)",8.2593,-11.7896,,,,2019-08-21T11:25:38.066Z,2019-08-21T11:25:38.067Z,TfdH5KvFmMy,"First Name",Sarah,TEXT
F8yKM85NbxW,Zy2SEgA61ys,2019-08-21T11:25:38.022Z,2019-03-19T00:12:16.624Z,2019-08-21T11:31:33.410Z,2019-03-19T00:12:16.624Z,DiszpKrYNg8,false,false,false,"POINT (-11.7896 8.2593)",8.2593,-11.7896,,,,2019-08-21T11:25:38.388Z,2019-08-21T11:25:38.388Z,aW66s2QSosT,"Last Name",Johnson,TEXT

Tracked entities collection limits¶

The collection endpoint limits results in three ways:

KeyTrackedEntityMaxLimit in System settings: KeyTrackedEntityMaxLimit defines the maximum tracked entities in an API response, protecting database and server resources. No limit applies when set to 0. Configure it via /api/systemSettings as described in the documentation.
Max number of TEs to return in Program or tracked entity type: it limits results when searching outside the capture scope with a specified program or tracked entity type. The API returns an error if matches exceed this limit. No limit applies when searching within the capture scope or when set to 0. This limit is configurable in the maintenance app.
Pagination: As explained here.

For paginated requests with non-zero KeyTrackedEntityMaxLimit:

If pageSize ≤ KeyTrackedEntityMaxLimit: pageSize is enforced
If pageSize > KeyTrackedEntityMaxLimit: The API returns an error

Tracked entities single object endpoint¶

GET /api/tracker/trackedEntities/{uid}

This endpoint retrieves a tracked entity given by ID.

Sintaxe de solicitação¶

GET /api/tracker/trackedEntities/{uid}?program={programUid}&fields={fields}

Request parameter	Modelo	Allowed values	Descrição
uid	Corda	`uid`	Return the tracked entity with specified `uid`
“Registro de Casos de Malária”	Corda	`uid`	Include program attributes in the response (only the ones user has access to)
fields	Corda	Any valid field filter (default `*,!relationships,!enrollments,!events,!programOwners`)	Include specified sub-objects in the response

Example requests¶

A query for a tracked entity:

GET /api/tracker/trackedEntities/PQfMcpmXeFE

Tracked Entity response¶

The API supports CSV and JSON response for GET /api/tracker/trackedEntities/{uid}

JSON¶

An example JSON response.

{
  "trackedEntity": "PQfMcpmXeFE",
  "trackedEntityType": "nEenWmSyUEp",
  "createdAt": "2014-03-06T05:49:28.256",
  "createdAtClient": "2014-03-06T05:49:28.256",
  "updatedAt": "2016-08-03T23:49:43.309",
  "orgUnit": "DiszpKrYNg8",
  "inactive": false,
  "deleted": false,
  "potentialDuplicate": false,
  "attributes": [
    {
      "attribute": "w75KJ2mc4zz",
      "code": "MMD_PER_NAM",
      "displayName": "First name",
      "createdAt": "2016-08-03T23:49:43.308",
      "updatedAt": "2016-08-03T23:49:43.308",
      "valueType": "TEXT",
      "value": "John"
    },
    {
      "attribute": "zDhUuAYrxNC",
      "displayName": "Last name",
      "createdAt": "2016-08-03T23:49:43.309",
      "updatedAt": "2016-08-03T23:49:43.309",
      "valueType": "TEXT",
      "value": "Kelly"
    }
  ],
  "enrollments": [
    {
      "enrollment": "JMgRZyeLWOo",
      "createdAt": "2017-03-06T05:49:28.340",
      "createdAtClient": "2016-03-06T05:49:28.340",
      "updatedAt": "2017-03-06T05:49:28.357",
      "trackedEntity": "PQfMcpmXeFE",
      "program": "IpHINAT79UW",
      "status": "ACTIVE",
      "orgUnit": "DiszpKrYNg8",
      "enrolledAt": "2024-03-06T00:00:00.000",
      "occurredAt": "2024-03-04T00:00:00.000",
      "attributeOptionCombo": "HllvX50cXC0",
      "followUp": false,
      "deleted": false,
      "events": [
        {
          "event": "Zq2dg6pTNoj",
          "status": "ACTIVE",
          "program": "IpHINAT79UW",
          "programStage": "ZzYYXq4fJie",
          "enrollment": "JMgRZyeLWOo",
          "trackedEntity": "PQfMcpmXeFE",
          "relationships": [],
          "scheduledAt": "2023-03-10T00:00:00.000",
          "followUp": false,
          "deleted": false,
          "createdAt": "2017-03-06T05:49:28.353",
          "createdAtClient": "2016-03-06T05:49:28.353",
          "updatedAt": "2017-03-06T05:49:28.353",
          "attributeOptionCombo": "HllvX50cXC0",
          "attributeCategoryOptions": "xYerKDKCefk",
          "dataValues": [],
          "notes": []
        }
      ],
      "relationships": [],
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "code": "MMD_PER_NAM",
          "displayName": "First name",
          "createdAt": "2016-08-03T23:49:43.308",
          "updatedAt": "2016-08-03T23:49:43.308",
          "valueType": "TEXT",
          "value": "John"
        },
        {
          "attribute": "zDhUuAYrxNC",
          "displayName": "Last name",
          "createdAt": "2016-08-03T23:49:43.309",
          "updatedAt": "2016-08-03T23:49:43.309",
          "valueType": "TEXT",
          "value": "Kelly"
        },
        {
          "attribute": "AuPLng5hLbE",
          "code": "National identifier",
          "displayName": "National identifier",
          "createdAt": "2016-08-03T23:49:43.301",
          "updatedAt": "2016-08-03T23:49:43.301",
          "valueType": "TEXT",
          "value": "245435245"
        },
        {
          "attribute": "ruQQnf6rswq",
          "displayName": "TB number",
          "createdAt": "2016-08-03T23:49:43.308",
          "updatedAt": "2016-08-03T23:49:43.308",
          "valueType": "TEXT",
          "value": "1Z 1F2 A84 59 4464 173 6"
        },
        {
          "attribute": "cejWyOfXge6",
          "displayName": "Gender",
          "createdAt": "2016-08-03T23:49:43.307",
          "updatedAt": "2016-08-03T23:49:43.307",
          "valueType": "TEXT",
          "value": "Male"
        },
        {
          "attribute": "VqEFza8wbwA",
          "code": "MMD_PER_ADR1",
          "displayName": "Address",
          "createdAt": "2016-08-03T23:49:43.307",
          "updatedAt": "2016-08-03T23:49:43.307",
          "valueType": "TEXT",
          "value": "Main street 2"
        }
      ],
      "notes": []
    }
  ],
  "programOwners": [
    {
      "orgUnit": "DiszpKrYNg8",
      "trackedEntity": "PQfMcpmXeFE",
      "program": "ur1Edk5Oe2n"
    },
    {
      "orgUnit": "DiszpKrYNg8",
      "trackedEntity": "PQfMcpmXeFE",
      "program": "IpHINAT79UW"
    }
  ]
}

CSV¶

The response will be the same as the collection endpoint but referring to a single tracked entity, although it might have multiple rows for each attribute.

Tracked entity attribute value change logs¶

GET /api/tracker/trackedEntities/{uid}/changeLogs

This endpoint retrieves change logs for the attributes of a specific tracked entity. It returns a list of all tracked entity attributes that have changed over time for that entity.

Request parameter	Modelo	Allowed values
path `/{uid}`	Corda	Tracked entity `UID`.
“Registro de Casos de Malária”	`String`	Program `UID` (optional).
order	`String`	Field and sort direction pair in the format `field:sortDirection`. Change logs are ordered by newest (creation date in descending order) by default, when no order parameter is provided. Example: `createdAt:desc` `field` is case-sensitive. Valid sortDirection values are `asc` and `desc`. `sortDirection` is case-insensitive and defaults to `asc` for fields without explicit `sortDirection`. Supported fields are `attribute`, `createdAt`, and `username`.
filter	Corda	Colon-separated field name with the `eq` operator and value in the format `field:eq:value`. Example: `attribute:eq:w75KJ2mc4zz` Filtering is supported for `attribute` and `username` fields, one at a time. Only the `eq` (equals) operator is supported.

Tracked entity attribute value change logs¶

An example JSON response.

{
  "pager": {
    "page": 1,
    "pageSize": 10
  },
  "changeLogs": [
    {
      "createdBy": {
        "uid": "AIK2aQOJIbj",
        "username": "tracker",
        "firstName": "Tracker demo",
        "surname": "User"
      },
      "createdAt": "2024-06-20T14:51:16.433",
      "type": "UPDATE",
      "change": {
        "attributeValue": {
          "attribute": "w75KJ2mc4zz",
          "previousValue": "John",
          "currentValue": "Johnny"
        }
      }
    },
    {
      "createdBy": {
        "uid": "AIK2aQOJIbj",
        "username": "tracker",
        "firstName": "Tracker demo",
        "surname": "User"
      },
      "createdAt": "2024-06-20T14:50:32.966",
      "type": "CREATE",
      "change": {
        "attributeValue": {
          "attribute": "w75KJ2mc4zz",
          "currentValue": "John"
        }
      }
    }
  ]
}

The change log type can be CREATE, UPDATE, or DELETE. CREATE and DELETE will always hold a single value: the former shows the current value, and the latter shows the value that was deleted. UPDATE will hold two values: the previous and the current.

Enrollments¶

GET /api/tracker/enrollments

Two endpoints are dedicated to enrollments.

GET /api/tracker/enrollments
- retrieves enrollments matching given criteria
GET /api/tracker/enrollments/{id}
- retrieves an enrollment given the provided ID

Enrollment Collection endpoint `GET /api/tracker/enrollments`¶

Returns a list of enrollments based on filters.

Request parameter	Modelo	Allowed values	Descrição
orgUnits	Corda	Comma-separated list of organisation unit `UID`s.	Only return enrollments belonging to provided organisation units.
orgUnitMode (see orgUnitModes)	Corda	`SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`	The mode of selecting organisation units. Default is `SELECTED`.
“Registro de Casos de Malária”	Corda	`uid`	Identifier of a tracker program the enrollment is enrolled into. This parameter is mandatory.
programStatus deprecated for removal in version 43 use `status`	Corda	`ACTIVE`, `COMPLETED`, `CANCELLED`	The status of the enrollment.
status	Corda	`ACTIVE`, `COMPLETED`, `CANCELLED`	The status of the enrollment.
followUp	boolean	`true`, `false`	Follow up status of the tracked entity for the given program. Can be `true`, `false` or omitted.
updatedAfter	DateTime	ISO-8601	Only enrollments updated after this date
updatedWithin	Duration	ISO-8601	Only enrollments updated since given duration
enrolledAfter	DateTime	ISO-8601	Only enrollments newer than this date
enrolledBefore	DateTime	ISO-8601	Only enrollments older than this date
trackedEntity	Corda	`uid`	Identifier of tracked entity
order	Corda	Comma-separated list of property name or attribute or UID and sort direction pairs in format `propName:sortDirection`.	Supported fields: `completedAt, createdAt, createdAtClient, enrolledAt, updatedAt, updatedAtClient`.
enrollments	Corda	Comma-separated list of enrollment `UID`s.	Filter the result down to a limited set of IDs by using `enrollments=id1,id2`.
attributeOptionCombo	Corda	`uid`	Filters enrollments by the given attribute option combo. Only matching enrollments are returned.
includeDeleted	Boolean		When true, soft deleted events will be included in your query result.

The query is case-insensitive. The only requirement is that the program parameter must be provided.

Example requests¶

A query for all enrollments associated with a specific organisation unit can look like this:

GET /api/tracker/enrollments?orgUnits=DiszpKrYNg8

To constrain the response to enrollments which are part of a specific tracker program you can include a program query parameter:

GET /api/tracker/enrollments?orgUnits=O6uvpzGd5pu&orgUnitMode=DESCENDANTS&program=ur1Edk5Oe2n

Para especificar as datas de inscrição no programa como parte da consulta:

GET /api/tracker/enrollments?orgUnits=DiszpKrYNg8&program=M3xtLkYBlKI&enrolledAfter=2023-11-14&enrolledBefore=2024-02-07

To constrain the response to enrollments of a specific tracked entity you can include a tracked entity query parameter:

GET /api/tracker/enrollments?trackedEntity=ClJ3fn47c4s

To constrain the response to enrollments of a specific tracked entity you can include a tracked entity query parameter, in In this case, we have restricted it to available enrollments viewable for current user:

GET /api/tracker/enrollments?orgUnitMode=ACCESSIBLE&trackedEntity=tphfdyIiVL6

Formato de resposta¶

The JSON response can look like the following.

{
  "pager": {
    "page": 1,
    "pageSize": 1
  },
  "enrollments": [
    {
      "enrollment": "TRE0GT7eh7Q",
      "createdAt": "2019-08-21T13:28:00.056",
      "createdAtClient": "2018-11-13T15:06:49.009",
      "updatedAt": "2019-08-21T13:29:44.942",
      "updatedAtClient": "2019-08-21T13:29:44.942",
      "trackedEntity": "s4NfKOuayqG",
      "program": "M3xtLkYBlKI",
      "status": "COMPLETED",
      "orgUnit": "DiszpKrYNg8",
      "enrolledAt": "2023-11-13T00:00:00.000",
      "occurredAt": "2023-11-13T00:00:00.000",
      "followUp": false,
      "deleted": false,
      "storedBy": "healthworker1",
      "notes": []
    }
  ]
}

Enrollments single object endpoint¶

GET /api/tracker/enrollments/{uid}

The purpose of this endpoint is to retrieve an enrollment given its ID.

Sintaxe de solicitação¶

GET /api/tracker/enrollment/{uid}

Request parameter	Modelo	Allowed values	Descrição
uid	Corda	`uid`	Return the Enrollment with specified `uid`
fields	Corda	Any valid field filter (default `*,!relationships,!events,!attributes`)	Include specified sub-objects in the response

Example requests¶

A query for an enrollment.

GET /api/tracker/enrollments/JMgRZyeLWOo

Formato de resposta¶

{
  "enrollment": "JMgRZyeLWOo",
  "createdAt": "2017-03-06T05:49:28.340",
  "createdAtClient": "2016-03-06T05:49:28.340",
  "updatedAt": "2017-03-06T05:49:28.357",
  "trackedEntity": "PQfMcpmXeFE",
  "program": "IpHINAT79UW",
  "status": "ACTIVE",
  "orgUnit": "DiszpKrYNg8",
  "enrolledAt": "2024-03-06T00:00:00.000",
  "occurredAt": "2024-03-04T00:00:00.000",
  "followUp": false,
  "deleted": false,
  "notes": []
}

Events (`GET /api/tracker/events`)¶

Two endpoints are dedicated to events. To retrieve events matching specific criteria:

GET /api/tracker/events

To retrieve an event with a specific ID:

GET /api/tracker/events/{id}

If not otherwise specified, JSON is the default response for the GET method. The API also supports CSV export for single and collection endpoints. Furthermore, it supports compressed JSON and CSV for the collection endpoint.

Events CSV¶

In the case of CSV, the fields request parameter has no effect, and the response will always contain the following fields:

Property	Modelo
event	UID
status	Corda
“Registro de Casos de Malária”	ID
programStage	ID
enrollment	ID
orgUnit	ID
occurredAt	DateTime
scheduledAt	DateTime
geometry	WKT, can be omitted it in case of a `Point` type and with `latitude` and `longitude` provided
latitude	Latitude of a `Point` type of Geometry
longitude	Longitude of a `Point` type of Geometry
followUp	boolean
deleted	boolean
createdAt	DateTime
createdAtClient	DateTime
updatedAt	DateTime
updatedAtClient	DateTime
completedBy	Nome do utilizador
completedAt	DateTime
updatedBy	Nome do utilizador
attributeOptionCombo	ID
attributeCategoryOptions	ID
assignedUser	Nome do utilizador
dataElement	ID
value	Corda
storedBy	Nome do utilizador
providedElsewhere	boolean
storedByDataValue	Corda
createdAtDataValue	DateTime
updatedAtDataValue	DateTime

See Events and Data Values for more field descriptions.

Events GZIP¶

The response is file events.json.gz or events.csv.gz containing the events.json or events.csv file.

Events ZIP¶

The response is file events.json.zip or events.csv.zip containing the events.json or events.csv file.

Events Collection endpoint `GET /api/tracker/events`¶

Returns a list of events based on the provided filters.

Request parameter	Modelo	Allowed values	Descrição
“Registro de Casos de Malária”	Corda	uid	Identifier of a tracker or event program. This parameter is mandatory.
programStage	Corda	uid	Identifier of program stage
programStatus deprecated for removal in version 43 use `enrollmentStatus`	Corda	`ACTIVE`, `COMPLETED`, `CANCELLED`	The status of the events enrollment.
filter	Corda	Comma separated values of data element filters	Narrows response to events matching given filters. A filter is a colon separated property or data element UID with optional operator and value pairs. Example: `filter=fazCI2ygYkq:eq:PASSIVE` with operator starts with `eq` followed by a value. A filter like `filter=fazCI2ygYkq:!null` returns all events where the given data element has a value. Characters such as `:` or `,`, as part of the filter value, need to be escaped by `/`. Likewise, `/` needs to be escaped. Multiple operators for the same data element like `filter=qrur9Dvnyt5:gt:70:lt:80` are allowed. User needs access to the data element to filter on it.
filterAttributes	Corda	Comma separated values of attribute filters	Narrows response to tracked entities matching given filters. Example: `filterAttributes=H9IlTX2X6SL:eq:John`. More on filters here
followUp	boolean	`true`, `false`	Whether event is considered for follow up in program. Defaults to `true`
trackedEntity	Corda	uid	Identifier of tracked entity
orgUnit	Corda	uid	Identifier of organisation unit
orgUnitMode see orgUnitModes	Corda	`SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`	The mode of selecting organisation units, can be. Default is `SELECTED`, which refers to the selected organisation units only.
status	Corda	`ACTIVE`, `COMPLETED`, `VISITED`, `SCHEDULE`, `OVERDUE`, `SKIPPED`	Status of event
occurredAfter	DateTime	ISO-8601	Filter for events which occurred after this date.
occurredBefore	DateTime	ISO-8601	Filter for events which occurred up until this date.
scheduledAfter	DateTime	ISO-8601	Filter for events which were scheduled after this date.
scheduledBefore	DateTime	ISO-8601	Filter for events which were scheduled before this date.
updatedAfter	DateTime	ISO-8601	Filter for events which were updated after this date. Cannot be used together with `updatedWithin`.
updatedBefore	DateTime	ISO-8601	Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.
updatedWithin	Duration	ISO-8601	Include only items which are updated within the given duration. The format is ISO-8601#Duration
enrollmentStatus	Corda	`ACTIVE`, `COMPLETED`, `CANCELLED`	The status of the events enrollment.
enrollmentEnrolledAfter	DateTime	ISO-8601	Start date and time for enrollment in the given program
enrollmentEnrolledBefore	DateTime	ISO-8601	End date and time for enrollment in the given program
enrollmentOccurredAfter	DateTime	ISO-8601	Start date for when the enrollment occurred in the given program
enrollmentOccurredBefore	DateTime	ISO-8601	End date for when the enrollment occurred in the given program
idScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is `UID`. Note: metadata in `event.relationships` will always be exported using UIDs.
dataElementIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for data element references. Defaults to the `idScheme` parameter.
orgUnitIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for organisation unit references. Defaults to the `idScheme` parameter.
programIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for program references. Defaults to the `idScheme` parameter.
programStageIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for program stage references. Defaults to the `idScheme` parameter.
categoryOptionComboIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for category option combo references. Defaults to the `idScheme` parameter.
categoryOptionIdScheme	Enum	`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	IdScheme used for category option references. Defaults to the `idScheme` parameter.
order	Corda	Comma-separated list of property name, attribute or data element UID and sort direction pairs in format `propName:sortDirection`.	Supported fields: `assignedUser, assignedUserDisplayName, attributeOptionCombo, completedAt, completedBy, createdAt, createdAtClient, createdBy, deleted, enrolledAt, enrollment, enrollmentStatus, event, followUp, occurredAt, orgUnit, program, programStage, scheduledAt, status, storedBy, trackedEntity, updatedAt, updatedAtClient, updatedBy`.
events	Corda	Comma-separated list of event `UID`s.	Filter the result down to a limited set of IDs by using `event=id1,id2`.
attributeCategoryCombo (see note)	Corda	Attribute category combo identifier. Must be combined with `attributeCategoryOptions`.
attributeCategoryOptions (see note)	Corda	Comma-separated attribute category option identifiers. Must be combined with `attributeCategoryCombo`.
includeDeleted	Boolean		When true, soft deleted events will be included in your query result.
assignedUserMode	Corda	`CURRENT`, `PROVIDED`, `NONE`, `ANY`	Assigned user selection mode
assignedUsers	Corda	Comma-separated list of user UIDs to filter based on events assigned to the users.	Filter the result down to a limited set of tracked entities with events that are assigned to the given user IDs by using `assignedUser=id1,id2`.This parameter will only be considered if `assignedUserMode` is either `PROVIDED` or `null`. The API will error out, if for example, `assignedUserMode=CURRENT` and `assignedUser=someId`.

Note

If the query contains neither attributeCategoryCombo nor attributeCategoryOptions, the server returns events for all attribute option combos where the user has read access.

Example requests¶

The query for all events with children of a particular organisation unit:

GET /api/tracker/events?orgUnit=YuQRtpLP10I&orgUnitMode=CHILDREN

The query for all events with all descendants of a particular organisation unit, implying all organisation units in the sub-hierarchy:

GET /api/tracker/events?orgUnit=O6uvpzGd5pu&orgUnitMode=DESCENDANTS

Consulta para todos os eventos com um determinado programa e unidade organizacional:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

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

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=scheduledAt

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

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=occurredAt:desc&pageSize=10&page=1

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

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=M3xtLkYBlKI&trackedEntity=dNpxRu1mWG5

Query for all events before or equal to 2024-02-03 and associated with a program and organisation unit:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&occurredBefore=2024-02-03

A query where multiple operand and filters are specified for a data element UID:

GET /api/tracker/events?orgUnit=g8upMTyEZGZ&program=M3xtLkYBlKI&filter=rFQNCGMYud2:GT:35&filter=rFQNCGMYud2:LT:50

A query filter with a value that needs escaping and will be interpreted as :,/:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//

Events response example¶

The API supports CSV and JSON response for GET /api/tracker/events.

JSON¶

The JSON response can look like the following:

{
  "pager": {
    "page": 1,
    "pageSize": 1
  },
  "events": [
    {
      "event": "A7rzcnZTe2T",
      "status": "ACTIVE",
      "program": "eBAyeGv0exc",
      "programStage": "Zj7UnCAulEk",
      "enrollment": "RiLEKhWHlxZ",
      "orgUnit": "DwpbWkiqjMy",
      "occurredAt": "2023-02-13T00:00:00.000",
      "scheduledAt": "2023-02-13T00:00:00.000",
      "followUp": false,
      "deleted": false,
      "createdAt": "2017-09-08T21:40:22.000",
      "createdAtClient": "2016-09-08T21:40:22.000",
      "updatedAt": "2017-09-08T21:40:22.000",
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "geometry": {
        "type": "Point",
        "coordinates": [-11.468912037323042, 7.515913998868316]
      },
      "dataValues": [
        {
          "createdAt": "2016-12-06T18:22:34.438",
          "updatedAt": "2016-12-06T18:22:34.438",
          "storedBy": "bjorn",
          "providedElsewhere": false,
          "dataElement": "F3ogKBuviRA",
          "value": "[-11.4880220438585,7.50978830548003]"
        },
        {
          "createdAt": "2013-12-30T14:23:57.423",
          "updatedAt": "2013-12-30T14:23:57.423",
          "storedBy": "lars",
          "providedElsewhere": false,
          "dataElement": "eMyVanycQSC",
          "value": "2018-02-07"
        },
        {
          "createdAt": "2013-12-30T14:23:57.382",
          "updatedAt": "2013-12-30T14:23:57.382",
          "storedBy": "lars",
          "providedElsewhere": false,
          "dataElement": "oZg33kd9taw",
          "value": "Male"
        }
      ],
      "notes": [],
      "followup": false
    }
  ]
}

CSV¶

The CSV response can look like the following:

event,status,program,programStage,enrollment,orgUnit,occurredAt,scheduledAt,geometry,latitude,longitude,followUp,deleted,createdAt,createdAtClient,updatedAt,updatedAtClient,completedBy,completedAt,updatedBy,attributeOptionCombo,attributeCategoryOptions,assignedUser,dataElement,value,storedBy,providedElsewhere,storedByDataValue,updatedAtDataValue,createdAtDataValue
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,F3ogKBuviRA,"[-11.4880220438585,7.50978830548003]",admin,false,,2016-12-06T17:22:34.438Z,2016-12-06T17:22:34.438Z
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,eMyVanycQSC,2018-02-07,admin,false,,2013-12-30T13:23:57.423Z,2013-12-30T13:23:57.423Z
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,msodh3rEMJa,2018-02-13,admin,false,,2013-12-30T13:23:57.467Z,2013-12-30T13:23:57.467Z

Events single object endpoint `GET /api/tracker/events/{uid}`¶

The purpose of this endpoint is to retrieve one Event given its uid.

Sintaxe de solicitação¶

GET /api/tracker/events/{uid}?fields={fields}

Request parameter	Modelo	Allowed values	Descrição
`uid`	`String`	`uid`	Return the Event with specified `uid`
`fields`	`String`	Any valid field filter (default `*,!relationships`)	Include specified sub-objects in the response

Example requests¶

A query for an Event:

GET /api/tracker/events/rgWr86qs0sI

Event response example¶

The API supports CSV and JSON response for GET /api/tracker/events/{uid}

JSON¶

{
  "event": "rgWr86qs0sI",
  "status": "ACTIVE",
  "program": "kla3mAPgvCH",
  "programStage": "aNLq9ZYoy9W",
  "enrollment": "Lo3SHzCnMSm",
  "orgUnit": "DiszpKrYNg8",
  "occurredAt": "2024-10-12T00:00:00.000",
  "followUp": false,
  "deleted": false,
  "createdAt": "2018-10-20T12:09:19.492",
  "createdAtClient": "2017-10-20T12:09:19.492",
  "updatedAt": "2018-10-20T12:09:19.492",
  "attributeOptionCombo": "amw2rQP6r6M",
  "attributeCategoryOptions": "RkbOhHwiOgW",
  "dataValues": [
    {
      "createdAt": "2015-10-20T12:09:19.640",
      "updatedAt": "2015-10-20T12:09:19.640",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "HyJL2Lt37jN",
      "value": "12"
    }
  ],
  "notes": [],
  "followup": false
}

CSV¶

The response will be the same as the collection endpoint but referring to a single event, although it might have multiple rows for each data element value.

Event data value change logs¶

GET /api/tracker/events/{uid}/changeLogs

This endpoint retrieves change logs for the data values of a specific event. It returns a list of all event data values and event fields (occurredAt, scheduledAt, and geometry) that have changed over time for the specified event.

Request parameter	Modelo	Allowed values
path `/{uid}`	Corda	Event `UID`.
order	Corda	Field and sort direction pair in the format `field:sortDirection`. Change logs are ordered by newest (creation date in descending order) by default, when no order parameter is provided. Example: `createdAt:desc` `field` is case-sensitive. Valid sortDirection values are `asc` and `desc`. `sortDirection` is case-insensitive and defaults to `asc` for fields without explicit `sortDirection`. Supported fields are `createdAt`, `change` and `username`, only one at a time.
filter	Corda	Colon-separated field name with the `eq` operator and value in the format `field:eq:value`. Example: `dataElement:eq:w75KJ2mc4zz` Filtering is supported for `field`, `dataElement` and `username` fields, one at a time. Only the `eq` (equals) operator is supported.

Event data value change logs response example¶

An example of a JSON response:

{
   "pager":{
      "page":1,
      "pageSize":10
   },
   "changeLogs":[
      {
         "createdBy":{
            "uid":"AIK2aQOJIbj",
            "username":"tracker",
            "firstName":"Tracker demo",
            "surname":"User"
         },
         "createdAt":"2024-06-20T15:43:36.342",
         "type":"DELETE",
         "change":{
            "dataValue":{
               "dataElement":"UXz7xuGCEhU",
               "previousValue":"12"
            }
         }
      },
      {
         "createdBy":{
            "uid":"AIK2aQOJIbj",
            "username":"tracker",
            "firstName":"Tracker demo",
            "surname":"User"
         },
         "createdAt":"2024-06-20T15:43:27.175",
         "type":"CREATE",
         "change":{
            "dataValue":{
               "dataElement":"UXz7xuGCEhU",
               "currentValue":"12"
            }
         }
      },
      {
         "createdBy":{
            "uid":"AIK2aQOJIbj",
            "username":"tracker",
            "firstName":"Tracker demo",
            "surname":"User"
         },
         "createdAt":"2024-06-20T14:51:16.433",
         "type":"UPDATE",
         "change":{
            "dataValue":{
               "dataElement":"bx6fsa0t90x",
               "previousValue":"true",
               "currentValue":"false"
            }
         }
      }
   ]
}

The change log type can be CREATE, UPDATE, or DELETE. CREATE and DELETE will always hold a single value: the former shows the current value, and the latter shows the value that was deleted. UPDATE will hold two values: the previous and the current.

Relacionamentos¶

GET /api/tracker/relationships

Relationships are links between two entities in the Tracker. These entities can be tracked entities, enrollments, and events.

The purpose of this endpoint is to retrieve relationships between objects.

Unlike other tracked objects endpoints, relationships only expose one endpoint:

GET /api/tracker/relationships?[trackedEntity={trackedEntityUid}|enrollment={enrollmentUid}|event={eventUid}]&fields=[fields]

Request parameters¶

Request parameter	Modelo	Allowed values	Descrição
trackedEntity	Corda	`uid`	Identifier of a tracked entity
enrollment	Corda	`uid`	Identifier of an enrollment
event	Corda	`uid`	Identifier of an event
fields	Corda	Any valid field filter (default `relationship,relationshipType,createdAtClient,from[trackedEntity[trackedEntity],enrollment[enrollment],event[event]],to[trackedEntity[trackedEntity],enrollment[enrollment],event[event]]`)	Include specified sub-objects in the response
order	Corda	Comma-separated list of property name or attribute or UID and sort direction pairs in format `propName:sortDirection`.	Supported fields: `createdAt, createdAtClient`.
includeDeleted	Boolean	`true`, `false`	whether to include soft-deleted elements in your query result

The following rules apply to the query parameters.

Only one parameter among trackedEntity, enrollment, event can be passed.

Note

Using trackedEntity, enrollment or event params, will return any relationship where the trackedEntity, enrollment or event is part of the relationship (either from or to). As long as the user has access to it.

Example response¶

{
  "pager": {
    "page": 1,
    "pageSize": 2
  },
  "relationships": [
    {
      "relationship": "oGtgtJpp6fG",
      "relationshipType": "Mv8R4MPcNcX",
      "from": {
        "trackedEntity": {
          "trackedEntity": "neR4cmMY22o"
        }
      },
      "to": {
        "trackedEntity": {
          "trackedEntity": "DsSlC54GNXy"
        }
      }
    },
    {
      "relationship": "SSfIicJKbh5",
      "relationshipType": "Mv8R4MPcNcX",
      "from": {
        "trackedEntity": {
          "trackedEntity": "neR4cmMY22o"
        }
      },
      "to": {
        "trackedEntity": {
          "trackedEntity": "rEYUGH97Ssd"
        }
      }
    }
  ]
}

Tracker access control¶

Tracker has a few different concepts in regards to access control, like sharing, organisation unit scopes, ownership, and access levels. The following sections provide a short introduction to the different topics.

Metadata sharing¶

Sharing setting is standard DHIS2 functionality that applies to both Tracker and Aggregate metadata/data as well as dashboards and visualization items. At the core of sharing is the ability to define who can see/do what. In general, there are five possible sharing configurations – no access, metadata read, metadata write, data read, and data write. These access configurations can be granted at user and/or user group level (for more flexibility). With a focus on Tracker, the following metadata and their sharing setting is of particular importance: Data Element, Category Option, Program, Program Stage, Tracked Entity Type, Tracked Entity Attribute as well as Tracker related Dashboards and Dashboard Items.

Sharing settings are enforced during Tracker data import/export. Data read/write access is needed to read and write respectively. Similarly, if a user is expected to modify metadata, it is essential to grant metadata write access.

One critical point with Tracker data is the need to have a holistic approach. For example, a user won’t be able to see the Data Element value by having read access to just the Data Element. The user needs to have data read to access the parent Program Stage and Program where this Data Element belongs. This works the same way as for category option combinations. In Tracker, events and enrollments are associated with an AttributeOptionCombo, which is composed of multiple Category Options. To read an event or enrollment, a user must have data read access to all Category Options and their corresponding Categories that make up the AttributeOptionCombo of that object. If the user lacks access to even one of the required Category Options or Categories, they will not have access to the entire event or enrollment..

When it comes to accessing Enrollment data, it is essential to have access to the Tracked Entity first. Access to a Tracked Entity is controlled through sharing setting of Program, Tracked Entity Type, and Tracked Entity Attribute. Once Enrollment is accessed, it is possible to access Event data, again depending on Program Stage and Data element sharing setting.

Another vital point to consider is how to map out access to different Program Stages of a Program. Sometimes we could be in a situation where we need to grant access to a specific stage – for example, “Lab Result” – to a specific group of users (Lab Technicians). In this situation, we can provide data write access to "Lab Result" stage, probably data read to one or more stages just in case we want Lab Technicians to read other medical results or no access if we think it not necessary for the Lab Technicians to see data other than lab related.

In summary, DHIS2 has a fine-grained sharing setting that we can use to implement access control mechanisms both at the data and metadata level. These sharing settings can be applied directly at the user level or user group level. How exactly to apply a sharing setting depends on the use-case at hand.

Organisation unit scopes¶

Organisation units are one of the most fundamental objects in DHIS2. They define a universe under which a user is allowed to record and/or read data. There are three types of organisation units that can be assigned to a user. These are data capture, data view (not used in tracker), and tracker search. As the name implies, these organisation units define a scope under which a user is allowed to conduct the respective operations. A user can search for data in their search scope and capture scope organisation units.

However, to further fine-tune the scope, DHIS2 Tracker introduces a concept that we call OrganisationUnitSelectionMode. Such a mode is often used at the time exporting tracker objects. For example, given that a user has a particular tracker search scope, does it mean that we have to use this scope every time a user tries to search for a tracker, Enrollment, or Event object? Or is the user interested in limiting the searching just to the selected org unit, or the entire capture org unit scope, and so on.

Users can do the fine-tuning by passing a specific value of orgUnitMode in their API request:

/api/tracker/trackedEntities?orgUnit=UID&orgUnitMode=specific_organisation_unit_selection_mode

Currently, there are six selection modes available: SELECTED, CHILDREN, DESCENDANTS, CAPTURE, ACCESSIBLE, and ALL.

Mode	Descrição
SELECTED	Specified organisation units.
CHILDREN	Specified organisation unit including immediate children, i.e. organisation units at the immediate level below.
DESCENDANTS	Specified organisation unit and all organisation units in the sub-hierarchy, i.e. at all organisation unit levels in the sub-hierarchy below the specified organisation units.
CAPTURE	The data capture organisation units associated with the current user and all organisation units in the sub-hierarchy.
ACCESSIBLE	The tracker search organisation units associated with the current user and all organisation units in the sub-hierarchy. This includes everything visible to the user, including open and audited programs within its search scope, as well as data in protected and closed programs within the user's capture scope. If a user lacks search organisation units, the system defaults to capture scope, ensuring that the user always has access to at least one universe. The capture scope, being mandatory, serves as a foundational element in guaranteeing a data environment for the user.
TODOS	All organisation units in the system. This mode is reserved for authorized users, specifically those with the authority ALL (super users). Users with the authority `F_TRACKED_ENTITY_INSTANCE_SEARCH_IN_ALL_ORGUNITS` can also search system-wide but need sharing access to the returned program, program stage, and/or tracked entity type. Non-authorized users are not permitted to search using this scope.

The first three modes, SELECTED, CHILDREN and DESCENDANTS, expect an organisation unit to be supplied in the request, while the last three, CAPTURE, ACCESSIBLE and ALL do not.

The organisation unit mode will be one of the ones listed above when it is explicitly provided in the API request. Since it is not a mandatory paramter, when not specified, the default value will be SELECTED if an organisation unit is present, and ACCESSIBLE if not.

It makes little sense to pass these modes at the time of tracker import operations. Because when writing tracker data, each of the objects needs to have a specific organisation unit attached to them. The system will then ensure if each of the mentioned organisation units falls under the CAPTURE scope. If not, the system will simply reject the write operation.

Note that there are four type of organisation unit associations relevant for tracker objects. A Tracked Entity has an organisation unit, commonly referred to as the Registration Organisation unit. Enrollments have an organisation unit associated with them. Events also have an organisation unit associated with them. There is also an Owner organisation unit for a tracker program combination.

When fetching Tracker objects, depending on the context, the organisation unit scope is applied to one of the above four organisation unit associations.

For example, when retrieving Tracked Entities without the context of a program, the organisation unit scope is applied to the registration organisation unit of the Tracked Entity. Whereas, when retrieving Tracked Entities, including specific program data, the organisation unit scope is applied to the owner organisation unit.

Tracker Program Ownership¶

Tracker Ownership, introduced in DHIS2 2.30, defines an organisation unit association for a TrackedEntity - Program combination. We call this the Owner (or Owning) Organisation unit of a TrackedEntity in the context of a Program. The Owner organisation unit is used to decide access privileges when reading and writing tracker data related to a program. This, along with the Program's Access Level configuration, decides the access behavior for Program-related data (Enrollments and Events). A user can access a TrackedEntity's Program data if the corresponding Owner OrganisationUnit for that TrackedEntity-Program combination falls under the user's organisation unit scope (Search/Capture). For Programs that are configured with access level OPEN or AUDITED , the Owner OrganisationUnit has to be in the user's search scope. For Programs that are configured with access level PROTECTED or CLOSED , the Owner OrganisationUnit has to be in the user's capture scope to be able to access the corresponding program data for the specific tracked entity. Irrespective of the program access level, to access Tracker objects, the requested organisation unit must always be within either the user's search scope or capture scope. A user cannot request objects outside these two scopes unless they are using the organisation unit mode ALL and have sufficient privileges to use that mode.

When requesting tracked entities without specifying a program, the response will include only tracked entities that satisfy metadata sharing settings and one of the following criteria:

The tracked entity is enrolled in at least one program the user has data access to, and the user has access to the owner organisation unit.
The tracked entity is not enrolled in any program the user has data access to, but the user has access to the tracked entity registering organisation unit.

Tracker Ownership Override: Break the Glass¶

It is possible to temporarily override the ownership privilege for a program that is configured with an access level of PROTECTED. Any user with the org unit owner within their search scope, can temporarily access the program-related data by providing a reason for accessing it.

This act of temporarily gaining access is termed breaking the glass. Currently, temporary access is granted for 3 hours. DHIS2 audit breaking the glass along with the reason specified by the user. This information is also stored in the database, but only if the tracked entity type is configured to allow auditing, which is disabled by default.

It is not possible to gain temporary access to a program that has been configured with an access level of CLOSED.

To break the glass for a TrackedEntity-Program combination, the following POST request can be used:

/api/tracker/ownership/override?trackedEntity=DiszpKrYNg8&program=eBAyeGv0exc&reason=patient+showed+up+for+emergency+care

Tracker Ownership Transfer¶

It is possible to transfer the ownership of a TrackedEntity-Program from one organisation unit to another. This will be useful in case of patient referrals or migrations. Only a user who has Ownership access (or temporary access by breaking the glass) can transfer the ownership. To transfer ownership of a TrackedEntity-Program to another organisation unit, the following PUT request can be used:

/api/tracker/ownership/transfer?trackedEntity=DiszpKrYNg8&program=eBAyeGv0exc&ou=EJNxP3WreNP

Access levels¶

Tracker data is handled with an extra level of protection. In addition to the standard feature of metadata and data protection through sharing settings, Tracker data are shielded with additional access level protection mechanisms. Currently, there are four access levels that can be configured for a Program: Open, Audited, Protected, and Closed.

These access levels are only triggered when users try to interact with program data, namely Enrollments and Events data. The different Access Level configuration for Program is a degree of openness (or closedness) of program data. Note that all other sharing settings are still respected, and the access level is only an additional layer of access control. Here is a short description of the four access levels that can be configured for a Program.

Open¶

This access level is the least restricted among the access levels. Data inside an OPEN program can be accessed and modified by users if the Owner organisation unit falls under the user's search scope. With this access level, accessing and modifying data outside the capture scope is possible without any justification or consequence.

Audited¶

This is the same as the Open access level. The difference here is that the system will automatically add an audit log entry on the data being accessed by the specific user.

Protected¶

This access level is slightly more restricted. Data inside a PROTECTED program can only be accessed by users if the Owner organisation unit falls under the user's capture scope. However, a user who only has the Owner organisation unit in the search scope can gain temporary ownership by breaking the glass. The user has to provide a justification of why they are accessing the data at hand. The system will then put a log of both the justification and access audit and provide temporary access for 3 hours to the user. Note that when breaking the glass, the Owner Organisation Unit remains unchanged, and only the user who has broken the glass gains temporary access.

Closed¶

This is the most restricted access level. Data recorded under programs configured with access level CLOSED will not be accessible if the Owner Organisation Unit does not fall within the user's capture scope. It is also not possible to break the glass or gain temporary ownership in this configuration. Note that it is still possible to transfer the ownership to another organisation unit. Only a user who has access to the data can transfer the ownership of a TrackedEntity-Program combination to another Organisation Unit. If ownership is transferred, the Owner Organisation Unit is updated. trackedEntities

Working lists¶

Working lists allow users to efficiently organize their workflow by saving filters and sorting preferences for tracked entities, enrollments, and events. Each type of working list—tracked entities, enrollments, and events—has a dedicated API for management.

Working lists are metadata, making them shareable and subject to the same sharing patterns as other metadata. When using the /api/sharing endpoint, the type parameter should be set to the name of the working list API. For example, use trackedEntityInstanceFilter for tracked entity working lists.

Since working lists are metadata refer to metadata on how to create, update and delete metadata. The following sections describe the payloads of each of the working lists endpoints.

Tracked entity working lists¶

Create, update and delete tracked entity working lists using

/api/trackedEntityInstanceFilters

Payload¶

Payload
Property	Descrição	Exemplo
nome	Name of the working list. Required.
descrição	A description of the working list.
sortOrder	The sort order of the working list.
style	Object containing css style.	`{"color": "blue", "icon": "fa fa-calendar"}`
“Registro de Casos de Malária”	Object containing the id of the program. Required.	`{ "id" : "uy2gU8kTjF"}`
entityQueryCriteria	An object representing various possible filtering values.	See Entity Query Criteria definition table below.
eventFilters	A list of eventFilters. See Event filters definition table below.	`[{"programStage": "eaDH9089uMp", "eventStatus": "OVERDUE", "eventCreatedPeriod": {"periodFrom": -15, "periodTo": 15}}]`

Entity query criteria definition
Property	Descrição	Exemplo
attributeValueFilters	A list of attributeValueFilters. This is used to specify filters for attribute values when listing tracked entities	`"attributeValueFilters":[{"attribute": "abcAttributeUid","le": "20","ge": "10","lt": "20","gt": "10","in": ["India", "Norway"],"like": "abc","sw": "abc","ew": "abc","dateFilter": {"startDate": "2014-05-01","endDate": "2019-03-20","startBuffer": -5,"endBuffer": 5,"period": "LAST_WEEK","type": "RELATIVE"}}]`
enrollmentStatus	The tracked entities enrollment status. Can be none(any enrollmentstatus) or `ACTIVE`, `COMPLETED`, `CANCELLED`
followUp	When this parameter is true, the working list only returns tracked entities that have an enrollment with `followUp=true`.
organisationUnit	To specify the uid of the organisation unit	`{"organisationUnit": "a3kGcGDCuk7"}`
ouMode	To specify the organisation unit selection mode. Options are `SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`	`"ouMode": "SELECTED"`
assignedUserMode	To specify the assigned user selection mode for events. Options are `CURRENT`, `PROVIDED`, `NONE`, `ANY`. See table below to understand what each value indicates. If `PROVIDED` (or null), non-empty assignedUsers in the payload will be considered.	`"assignedUserMode": "PROVIDED"`
assignedUsers	To specify a list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.	`"assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"]`
displayColumnOrder	To specify the output ordering of columns	`"displayOrderColumns": ["enrollmentDate", "program"]`
order	To specify ordering/sorting of fields and its directions in comma separated values. A single item in order is of the form "orderDimension:direction". Note: Supported orderDimensions are trackedEntity, created, createdAt, createdAtClient, updatedAt, updatedAtClient, enrolledAt, inactive and the tracked entity attributes	`"order":"a3kGcGDCuk6:desc"`
programStage	To specify a programStage uid to filter on. tracked entities will be filtered based on presence of enrollment in the specified program stage.	`"programStage":"a3kGcGDCuk6"`
trackedEntityType	To specify a trackedEntityType filter tracked entities on.	`{"trackedEntityType":"a3kGcGDCuk6"}`
trackedEntities	To specify a list of tracked entities to use when querying tracked entities.	`"trackedEntities":["a3kGcGDCuk6","b4jGcGDCuk7"]`
enrollmentCreatedDate	DateFilterPeriod object date filtering based on enrollment created date.	`"enrollmentCreatedDate": { "period": "LAST_WEEK", "type": "RELATIVE" }`
enrollmentIncidentDate	DateFilterPeriod object date filtering based on enrollment incident date.	`"enrollmentIncidentDate": { "startDate": "2014-05-01", "endDate": "2019-03-20", "startBuffer": -5, "endBuffer": 5, "period": "LAST_WEEK", "type": "RELATIVE" }`
eventStatus	The event status. Options are `ACTIVE`, `COMPLETED`, `VISITED`, `SCHEDULE`, `OVERDUE`, `SKIPPED` and `VISITED`	`"status":"VISITED"`
eventDate	DateFilterPeriod object date filtering based on event date.	`"eventDate": {"startBuffer": -5,"endBuffer": 5, "type": "RELATIVE" }`
lastUpdatedDate	DateFilterPeriod object date filtering based on last updated date.	`"lastUpdatedDate": {"startDate": "2014-05-01", "endDate": "2019-03-20", "type": "ABSOLUTE" }`

Event filters definition
Property	Descrição	Exemplo
programStage	Which programStage the tracked entity needs an event in to be returned.	`"eaDH9089uMp"`
eventStatus	The events status. Can be none(any event status) or ACTIVE, COMPLETED, SCHEDULE, OVERDUE	`ACTIVE`
eventCreatedPeriod	FilterPeriod object containing a period in which the event must be created. See Period definition below.	`{ "periodFrom": -15, "periodTo": 15}`
assignedUserMode	To specify the assigned user selection mode for events. Options are `CURRENT` (events assigned to current user), `PROVIDED` (events assigned to users provided in "assignedUsers" list), `NONE` (events assigned to no one) , ANY (events assigned to anyone). If PROVIDED (or null), non-empty assignedUsers in the payload will be considered.	`"assignedUserMode": "PROVIDED"`
assignedUsers	To specify a list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.	`"assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"]`

Period filter definition
Property	Descrição	Exemplo
periodFrom	Number of days from current day. Can be positive or negative integer.	-15
periodTo	Number of days from current day. Must be bigger than periodFrom. Can be positive or negative integer.	15

Query request parameters¶

Tracked entity instance filters query parameters
Query parameter	Descrição
“Registro de Casos de Malária”	Program identifier. Restricts filters to the given program.

Program stage working lists¶

Create, update and delete program stage working lists using

/api/programStageWorkingLists

Payload¶

Payload
Payload values	Descrição	Exemplo
nome	Name of the working list. Required.
descrição	A description of the working list.
“Registro de Casos de Malária”	Object containing the id of the program. Required.	`{"id" : "uy2gU8kTjF"}`
programStage	Object containing the id of the program stage. Required.	`{"id" : "oRySG82BKE6"}`
programStageQueryCriteria	An object representing various possible filtering values.	See Program Stage Query Criteria definition table below.

Program Stage Query Criteria
Criteria values	Descrição	Exemplo
eventStatus	The event status. Options are `ACTIVE`, `COMPLETED`, `VISITED`, `SCHEDULE`, `OVERDUE`, `SKIPPED` and `VISITED`	`"status":"VISITED"`
eventCreatedAt	DateFilterPeriod object filtering based on the event creation date.	`{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}`
eventOccurredAt	DateFilterPeriod object filtering based on the event occurred date.	`{"type":"RELATIVE","period":"TODAY"}`
eventScheduledAt	DateFilterPeriod object filtering based on the event scheduled date.	`{"type":"RELATIVE","period":"TODAY"}`
enrollmentStatus	Any valid EnrollmentStatus. Options are `ACTIVE`, `COMPLETED` and `CANCELLED`.	`"enrollmentStatus": "COMPLETED"`
followUp	Indicates whether to filter enrollments marked for follow up or not	`"followUp":true`
enrolledAt	DateFilterPeriod object filtering based on the event enrollment date.	`"enrolledAt": {"type":"RELATIVE","period":"THIS_MONTH"}`
enrollmentOccurredAt	DateFilterPeriod object filtering based on the event occurred date.	`{"type":"RELATIVE","period":"THIS_MONTH"}`
orgUnit	A valid organisation unit UID	`"orgUnit": "Rp268JB6Ne4"`
ouMode	A valid OU selection mode	`"ouMode": "SELECTED"`
assignedUserMode	A valid user selection mode for events. Options are `CURRENT`, `PROVIDED`, `NONE`, `ANY` and `ALL`. If `PROVIDED` (or null), non-empty assignedUsers in the payload will be expected.	"assignedUserMode":"PROVIDED"
assignedUsers	A list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.	"assignedUsers":["DXyJmlo9rge"]
order	List of fields and its directions in comma separated values, the results will be sorted according to it. A single item in order is of the form "orderDimension:direction".	"order": "w75KJ2mc4zz:asc"
displayColumnOrder	Output ordering of columns	"displayColumnOrder":["w75KJ2mc4zz","zDhUuAYrxNC"]
dataFilters	A list of items that contains the filters to be used when querying events	"dataFilters":[{"dataItem": "GXNUsigphqK","ge": "10","le": "20"}]
attributeValueFilters	A list of attribute value filters. This is used to specify filters for attribute values when listing tracked entities	"attributeValueFilters":[{"attribute": "ruQQnf6rswq","eq": "15"}]

See an example payload below.

{
  "name": "Test WL",
  "description": "Test WL definition",
  "program": {
    "id": "uy2gU8kT1jF"
  },
  "programStage": {
    "id": "oRySG82BKE6"
  },
  "programStageQueryCriteria": {
    "eventStatus": "VISITED",
    "eventCreatedAt": {
      "type": "ABSOLUTE",
      "startDate": "2020-03-01",
      "endDate": "2022-12-30"
    },
    "eventScheduledAt": {
      "type": "RELATIVE",
      "period": "TODAY"
    },
    "enrollmentStatus": "COMPLETED",
    "followUp": true,
    "enrolledAt": {
      "type": "RELATIVE",
      "period": "THIS_MONTH"
    },
    "enrollmentOccurredAt": {
      "type": "RELATIVE",
      "period": "THIS_MONTH"
    },
    "orgUnit": "Rp268JB6Ne4",
    "ouMode": "SELECTED",
    "assignedUserMode": "PROVIDED",
    "assignedUsers": [
      "DXyJmlo9rge"
    ],
    "order": "w75KJ2mc4zz:asc",
    "displayColumnOrder": [
      "w75KJ2mc4zz",
      "zDhUuAYrxNC"
    ],
    "dataFilters": [
      {
        "dataItem": "GXNUsigphqK",
        "ge": "10",
        "le": "20"
      }
    ],
    "attributeValueFilters": [
      {
        "attribute": "ruQQnf6rswq",
        "eq": "15"
      }
    ]
  }
}

Event working lists¶

Create, update and delete event working lists using the following endpoint.

/api/eventFilters

Payload¶

Payload
Property	Descrição	Exemplo
nome	Name of the working list.	"name":"My working list"
descrição	A description of the working list.	"description":"for listing all events assigned to me".
“Registro de Casos de Malária”	The uid of the program.	"program" : "a3kGcGDCuk6"
programStage	The uid of the program stage.	"programStage" : "a3kGcGDCuk6"
eventQueryCriteria	Object containing parameters for querying, sorting and filtering events.	"eventQueryCriteria": { "organisationUnit":"a3kGcGDCuk6", "status": "COMPLETED", "createdDate": { "from": "2014-05-01", "to": "2019-03-20" }, "dataElements": ["a3kGcGDCuk6:EQ:1", "a3kGcGDCuk6"], "filters": ["a3kGcGDCuk6:EQ:1"], "programStatus": "ACTIVE", "ouMode": "SELECTED", "assignedUserMode": "PROVIDED", "assignedUsers" : ["a3kGcGDCuk7", "a3kGcGDCuk8"], "followUp": false, "events": ["a3kGcGDCuk7", "a3kGcGDCuk8"], "fields": "eventDate,dueDate", "order": "dueDate:asc,createdDate:desc" }

Event query criteria definition
Property	Descrição	Exemplo
followUp	Used to filter events based on enrollment followUp flag. Options are `true`, `false`.	"followUp": true
organisationUnit	To specify the uid of the organisation unit	"organisationUnit": "a3kGcGDCuk7"
ouMode	To specify the OU selection mode. Options are `SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`	"ouMode": "SELECTED"
assignedUserMode	To specify the assigned user selection mode for events. Options are `CURRENT`, `PROVIDED`, `NONE`, `ANY`. See table below to understand what each value indicates. If `PROVIDED` (or null), non-empty assignedUsers in the payload will be considered.	"assignedUserMode": `PROVIDED`
assignedUsers	To specify a list of assigned users for events. To be used along with PROVIDED assignedUserMode above.	"assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"]
displayColumnOrder	To specify the output ordering of columns	"displayOrderColumns": ["eventDate", "dueDate", "program"]
order	To specify ordering/sorting of fields and its directions in comma separated values. A single item in order is of the form "dataItem:direction".	"order"="a3kGcGDCuk6:desc,eventDate:asc"
dataFilters	To specify filters to be applied when listing events	"dataFilters"=[{ "dataItem": "abcDataElementUid", "le": "20", "ge": "10", "lt": "20", "gt": "10", "in": ["India", "Norway"], "like": "abc", "dateFilter": { "startDate": "2014-05-01", "endDate": "2019-03-20", "startBuffer": -5, "endBuffer": 5, "period": "LAST_WEEK", "type": "RELATIVE" } }]
status	Any valid EventStatus	"eventStatus": "COMPLETED"
events	To specify list of events	"events"=["a3kGcGDCuk6"]
completedDate	DateFilterPeriod object date filtering based on completed date.	"completedDate": { "startDate": "2014-05-01", "endDate": "2019-03-20", "startBuffer": -5, "endBuffer": 5, "period": "LAST_WEEK", "type": "RELATIVE" }
eventDate	DateFilterPeriod object date filtering based on event date.	"eventDate": { "startBuffer": -5, "endBuffer": 5, "type": "RELATIVE" }
dueDate	DateFilterPeriod object date filtering based on due date.	"dueDate": { "period": "LAST_WEEK", "type": "RELATIVE" }
lastUpdatedDate	DateFilterPeriod object date filtering based on last updated date.	"lastUpdatedDate": { "startDate": "2014-05-01", "endDate": "2019-03-20", "type": "ABSOLUTE" }

See an example payload below.

{
  "name": "event working list",
  "program": "VBqh0ynB2wv",
  "eventQueryCriteria": {
    "eventDate": {
      "period": "LAST_WEEK",
      "type": "RELATIVE"
    },
    "dataFilters": [
      {
        "ge": "35",
        "le": "70",
        "dataItem": "qrur9Dvnyt5"
      }
    ],
    "assignedUserMode": "PROVIDED",
    "assignedUsers": [
      "CotVI2NX0rI",
      "xE7jOejl9FI"
    ],
    "status": "ACTIVE",
    "order": "occurredAt:desc",
    "displayColumnOrder": [
      "occurredAt",
      "status",
      "assignedUser",
      "qrur9Dvnyt5",
      "oZg33kd9taw"
    ]
  }
}

Common objects¶

DateFilterPeriod object definition
Property	Descrição	Exemplo
type	Specify whether the date period type is `ABSOLUTE`, `RELATIVE`	`"type" : "RELATIVE"`
period	Specify if a relative system defined period is to be used. Applicable only when `type` is RELATIVE. (see Relative Periods for supported relative periods)	`"period" : "THIS_WEEK"`
startDate	Absolute start date. Applicable only when `type` is ABSOLUTE	`"startDate":"2014-05-01"`
endDate	Absolute end date. Applicable only when `type` is ABSOLUTE	`"startDate":"2014-05-01"`
startBuffer	Relative custom start date. Applicable only when `type` is RELATIVE	`"startBuffer":-10`
endBuffer	Relative custom end date. Applicable only when `type` is RELATIVE	`"startDate":+10`

Potential duplicates¶

Potential duplicates are records identified by the data deduplication feature as possibly being duplicates. Due to the nature of this feature, the API endpoint has certain restrictions. A potential duplicate represents a pair of records suspected to be duplicates.

To retrieve a list of potential duplicates, use the following endpoint:

GET /api/potentialDuplicates

The response payload for a potential duplicate looks like this.

{
  "created": "2024-06-04T10:11:29.110",
  "lastUpdated": "2024-06-04T10:11:29.110",
  "original": "<UID>",
  "duplicate": "<UID>",
  "status": "OPEN|INVALID|MERGED",
  "id": "<id>"
}

These are the parameters this endpoint accepts:

Request parameter	Descrição	Modelo	Allowed values
trackedEntities	List of tracked entities	List of string (separated by comma)	existing tracked entity UIDs
status	Potential duplicate status	string	`OPEN`, `INVALID`, `MERGED`, `ALL`

To inspect individual potential duplicate records, use the following endpoint:

GET /api/potentialDuplicates/<{id}

To create a new potential duplicate, use this endpoint:

POST /api/potentialDuplicates

The payload you provide must include the UIDs of the original and duplicate tracked entities. New potential duplicates are open by default.

{
  "original": "<UID>",
  "duplicate": "<UID>"
}

Status code	Descrição
400	Input original or duplicate is null or has invalid uid
403	User do not have access to read original or duplicate TEs
404	TE not found
409	Pair of original and duplicate TEs already existing

To update the status of a potential duplicate, use the following endpoint:

PUT /api/potentialDuplicates/<id>

Request parameter	Descrição	Modelo	Allowed values
status	Potential duplicate status	string	`OPEN`, `INVALID`

Status code	Descrição
400	You can't update a potential duplicate to MERGED as this is possible only by a merging request
400	You can't update a potential duplicate that is already in a MERGED status

Merging tracked entities¶

Tracked entities can be merged together if they are deemed viable. To initiate a merge, the first step is to define two tracked entities as a Potential Duplicate. The merge endpoint moves data from the duplicate tracked entity to the original tracked entity and deletes the remaining data of the duplicate.

To merge a Potential Duplicate, i.e. the two tracked entities the Potential Duplicate represents, use the following endpoint:

POST /api/potentialDuplicates/<id>/merge

Request parameter	Descrição	Modelo	Allowed values
mergeStrategy	Strategy to use for merging the potentialDuplicate	string	AUTO(default) or MANUAL

The endpoint accepts a single parameter, mergeStrategy, which determines the strategy used when merging. For the AUTO strategy, the server will attempt to merge the two tracked entities automatically without user input. This strategy only allows merging tracked entities without conflicting data (see examples below). The MANUAL strategy requires the user to send in a payload describing how the merge should be done. For examples and rules for each strategy, see their respective sections below.

Merge strategy AUTO¶

The automatic merge evaluates the mergability of the two tracked entities and merges them if they are deemed mergeable. The mergability is based on whether the two tracked entities have any conflicts. Conflicts refer to data that cannot be merged automatically. Examples of possible conflicts include:

The same attribute has different values in each tracked entity.
Both tracked entities are enrolled in the same program.
Tracked entities have different types.

If any conflict is encountered, an error message is returned to the user.

When no conflicts are found, all data in the duplicate that is not already in the original will be moved to the original. This includes attribute values, enrollments (including events), and relationships. After the merge completes, the duplicate is deleted and the Potential Duplicate is marked as MERGED. When requesting an automatic merge, a payload is not required and will be ignored.

Merge strategy MANUAL¶

The manual merge is suitable when there are resolvable conflicts or when not all the data needs to be moved during the merge. For example, if an attribute has different values in both tracked entities , the user can specify whether to keep the original value or move over the duplicate's value. Since the manual merge involves the user explicitly requesting to move data, there are some additional checks:

Relationship cannot be between the original and the duplicate (This results in an invalid self-referencing relationship)
Relationship cannot be of the same type and to the same object in both tracked entities (IE. between original and other, and duplicate and other; This would result in a duplicate relationship)

There are two ways to do a manual merge: With and without a payload.

When a manual merge is requested without a payload, we are telling the API to merge the two tracked entities without moving any data. In other words, we are just removing the duplicate and marking the potentialDuplicate MERGED. This might be valid in a lot of cases where the tracked entity was just created, but not enrolled for example.

Otherwise, if a manual merge is requested with a payload, the payload refers to what data should be moved from the duplicate to the original. The payload looks like this:

{
  "trackedEntityAttributes": ["B58KFJ45L9D"],
  "enrollments": ["F61SJ2DhINO"],
  "relationships": ["ETkkZVSNSVw"]
}

This payload contains three lists, one for each of the types of data that can be moved. trackedEntityAttributes is a list of uids for tracked entity attributes, enrollments is a list of uids for enrollments and relationships a list of uids for relationships. The uids in this payload have to refer to data that actually exists on the duplicate. There is no way to add new data or change data using the merge endpoint - Only moving data.

Additional information about merging¶

Currently it is not possible to merge tracked entities that are enrolled in the same program, due to the added complexity. A workaround is to manually remove the enrollments from one of the tracked entities before starting the merge.

All merging is based on data already persisted in the database, which means the current merging service is not validating that data again. This means if data was already invalid, it will not be reported during the merge. The only validation done in the service relates to relationships, as mentioned in the previous section.

Program notification template¶

The Program Notification Template allows you to create message templates that can be sent based on different types of events. The message and subject templates are translated into actual values and sent to the configured destination. Each program notification template is transformed into either a MessageConversation object or a ProgramMessage object, depending on whether the recipient is external or internal. These intermediate objects will contain only the translated message and subject text.

There are several configuration parameters in the Program Notification Template that are essential for the proper functioning of notifications. These parameters are explained in the table below.

POST /api/programNotificationTemplates

{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}

Table: Program Notification Template payload¶

Campo	Requerido	Descrição	Values
nome	sim	Name of the Program Notification Template	case-notification-alert
notificationTrigger	sim	When notification should be triggered. Options are `ENROLLMENT`, `COMPLETION`, `PROGRAM_RULE`, `SCHEDULED_DAYS_DUE_DATE`	`ENROLLMENT`
subjectTemplate	Não	Subject template string	Case notification V{org_unit_name}
messageTemplate	sim	Message template string	Case notification A{h5FuguPFF2j}
notificationRecipient	sim	Who is going to receive notification. Options are `USER_GROUP`, `ORGANISATION_UNIT_CONTACT`, `TRACKED_ENTITY_INSTANCE`, `USERS_AT_ORGANISATION_UNIT`, `DATA_ELEMENT`, `PROGRAM_ATTRIBUTE`, `WEB_HOOK`	USER_GROUP
deliveryChannels	Não	Which channel should be used for this notification. It can be either `SMS`, `EMAIL`, or `HTTP`	`SMS`
sendRepeatable	Não	Whether notification should be sent multiple times	falso

The WEB_HOOK notificationRecipient is used exclusively for sending HTTP POST requests to external systems. Ensure that the HTTP delivery channel is selected when using this option.

Retrieving and Deleting Program Notification Template¶

As program notification template is a type of metadata, you can create, update, and delete it just like other metadata.

Program Messages¶

The program message feature enables you to send messages to tracked entities, contact addresses associated with organisation units, phone numbers, and email addresses. Messages can be sent using the messages resource.

POST /api/messages

Enviando mensagens do programa¶

As mensagens do programa podem ser enviadas usando dois canais de entrega:

SMS (SMS)
Endereço de email (EMAIL)

Recipients¶

As mensagens do programa podem ser enviadas para vários destinatários:

Tracked entity: The system will look up attributes of value type PHONE_NUMBER or EMAIL (depending on the specified delivery channels) and use the corresponding attribute values.
Organisation unit: The system will use the phone number or email information registered for the organisation unit.
List of phone numbers: The system will use the explicitly defined phone numbers.
List of email addresses: The system will use the explicitly defined email addresses.

Below is a sample JSON payload for sending messages using POST requests.

{
  "programMessages": [{
    "recipients": {
      "trackedEntity": {
        "id": "UN810PwyVYO"
      },
      "organisationUnit": {
        "id": "Rp268JB6Ne4"
      },
      "phoneNumbers": [
        "55512345",
        "55545678"
      ],
      "emailAddresses": [
        "johndoe@mail.com",
        "markdoe@mail.com"
      ]
    },
    "enrollment": {
      "id": "f3rg8gFag8j"
    },
    "event": {
      "id": "pSllsjpfLH2"
    },
    "deliveryChannels": [
      "SMS", "EMAIL"
    ],
    "notificationTemplate": "Zp268JB6Ne5",
    "subject": "Outbreak alert",
    "text": "An outbreak has been detected",
    "storeCopy": false
  }]
}

Table: Program message payload¶

Campo	Requerido	Descrição	Values
recipients	sim	Recipients of the program message. At least one recipient must be specified.	Can be trackedEntity, organisationUnit, an array of phoneNumbers or an array of emailAddresses.
enrollment	Não	Enrollment which ProgramMessage is attached to.	Enrollment ID.
event	Não	Event which ProgramMessage is attached to.	Event ID.
deliveryChannels	sim	Array of delivery channels.	`SMS`, `EMAIL`
notificationTemplate	Não	ProgramNotificationTemplate UID is used to cross-check which program message belongs to which notification template.	Text.
subject	Não	The message subject. Not applicable for SMS delivery channel.	Text.
texto	sim	The message text.	Text.
storeCopy	Não	Whether to store a copy of the program message in DHIS2.	`false`, `true`

Consultando mensagens do programa¶

The program message API supports querying messages using specific request parameters.

GET /api/messages

To retrieve a specific message.

GET /api/messages/scheduled/sent?enrollment={uid}

GET /api/messages/scheduled/sent?event={uid}

To retrieve a specific message.

GET /api/messages/{uid}

To delete a message.

DELETE /api/messages/{uid}

The program message API supports querying messages using specific request parameters. You can filter messages based on the parameters listed below. All requests should use the GET HTTP verb to retrieve information.

Query program messages API
Parameter	URL
enrollment	/api/messages?enrollment=6yWDMa0LP7
event	/api/messages?event=SllsjpfLH2
trackedEntity	/api/messages?trackedEntity=xdfejpfLH2
organisationUnit	/api/messages?ou=Sllsjdhoe3
processedDate	/api/messages?processedDate=2016-02-01

Program Notification Instance¶

/api/programNotificationInstances exposes program notification instances, i.e. concrete scheduled or sent notifications created from program notification templates.

Returns program notification instances, optionally filtered and paginated.

GET /api/programNotificationInstances

Query program notification instance API
Nome	Modelo	Requerido	Descrição
`scheduledAt`	`date` (ISO-8601)	no	Returns notification instances scheduled to be sent on the given date. Example: `scheduledAt=2025-01-01`.
`paging`	`boolean`	no	Enables or disables pagination. Default is `true`. Use `paging=false` to return all matching instances without pagination.
`page`	`integer`	no	Page number to return when pagination is enabled.
`pageSize`	`integer`	no	Number of items per page when pagination is enabled.
`event`	`UID`	no	Program notification instances attached to this event.
`enrollment`	`UID`	no	Program notification instances attached to this enrollment.

Performance¶

This section covers general performance principles followed by endpoint-specific guidance for the tracker export endpoints. Further performance optimizations require knowledge of real-world access patterns and data distribution. If your implementation can share this information, it will help prioritize improvements.

For tracker performance improvements relative to previous releases, see the corresponding release note, e.g. 2.43.

Import¶

Notifications¶

Notifications are dispatched asynchronously after import but compete with concurrent requests for database connections, CPU, and memory. With many entities and notification templates this can increase latency. For bulk imports where notifications are not needed, skip them:

POST /api/tracker?skipSideEffects=true

Program Rules¶

The rule engine runs synchronously during import for every enrollment and event in the bundle, which can increase latency significantly for bulk imports. Skip it only if the programs have no rules with validations or assignments that must be enforced on import:

POST /api/tracker?skipRuleEngine=true

Export¶

General Principles¶

Export endpoint response times are typically dominated by database query execution. The recommendations below focus on reducing the amount of work the database has to do.

Query at the Right Level¶

The tracker data model has three levels: tracked entities, enrollments, and events. Always query at the lowest level that satisfies your need. Use GET /api/tracker/events instead of GET /api/tracker/trackedEntities?fields=enrollments[events]. Querying via a parent endpoint increases query complexity or the number of queries.

Use Explicit `fields`¶

By default, all endpoints exclude nested collections such as enrollments, events, and relationships. Each additional collection increases resource utilization and response times. Only request the fields you need and avoid fields=*.

Selectivity¶

Query performance depends on how many records the database must process before returning results. The fewer records to scan, sort, and deduplicate, the faster the response. This is selectivity: the fraction of total records that match the query conditions.

Selectivity comes from several sources, all of which compound: request parameters (such as program, filter, date ranges), user scope, and orgUnitMode.

Filtros¶

Filters narrow the result set before sorting and pagination. They are most effective when backed by a database index. Broad filters (e.g., filter=w75KJ2mc4zz:like:J) may match a large portion of the dataset and provide little selectivity. Narrow filters (e.g., filter=w75KJ2mc4zz:eq:Jerald or a tight date range) reduce the working set significantly. like filters on tracked entity attributes can benefit from trigram indexing.

The "Minimum number of attributes required to search" setting on programs and tracked entity types requires a minimum number of attribute filters when searching outside the user's capture scope.

Program¶

Specifying program enables ownership-based access control. Without program, the system must evaluate access rules dynamically across all programs a tracked entity is enrolled in. Always include program when querying program-specific data.

Note that even with program specified, selectivity depends on how much data exists for that program. A program enrolling most tracked entities will not be very selective.

Organisation Unit Mode¶

orgUnitMode and the user's organisation unit scope directly affect how many records the database processes. Performance depends on how much data the included org units own. A user scoped to a single facility queries a small subset of records; a user with root-level access may scan the entire program. SELECTED is the most efficient as the database can seek directly to records owned by the specified org units.

CHILDREN is slow when the children do not own data. Data is typically captured at facilities (the lowest level). Using CHILDREN at a higher level (e.g. district) returns administrative org units that have no events, forcing the database to scan all events in the program to confirm this. CHILDREN is fast when the children are org units that actually capture data.

ALL includes no geographic restriction. ACCESSIBLE depends on the user's search scope, which for users with broad access can cover most of the program's data. Combine with selective filters to keep the working set manageable.

Ordering¶

The order parameter can significantly impact query performance. Order fields fall into performance tiers:

Fast (indexed): The database walks an index in order and stops after filling the requested page. Cost scales with page size and offset, not dataset size. This assumes the query conditions allow the database to use the index, which depends on filters and orgUnitMode.
Slow (no index): The database must scan and sort all matching records before returning the page. Cost is dominated by the total number of matching records.
Very slow (cross-resource): The sort value comes from a related resource (e.g., sorting tracked entities by enrolledAt or an attribute value). The database must look up these values for every matching record before sorting.

Selectivity matters more than order field choice. With selective filters or narrow user scope, even slow order fields are fast because the database only sorts a small set. Note that filters without a backing index still reduce the sort cost but not the scan cost.

See the endpoint-specific sections below for which order fields fall into which tier.

Pagination¶

DHIS2 uses offset-based pagination. High page numbers are inherently slower because the database must compute and discard all preceding rows. This is a fundamental property of offset-based pagination, not specific to DHIS2.

Recomendações: * Keep page sizes reasonable (default is 50) * Avoid navigating to very high page numbers * Avoid totalPages=true unless necessary as it runs an additional count query that must process all matching records regardless of page size * Avoid paging=false as it returns all matching records in a single response

Configure collection limits to cap the result set size and protect database and server resources.

`/api/tracker/trackedEntities`¶

Filtros¶

Either program or trackedEntityType is required. Prefer program as it enables direct ownership-based access control.

Ordering¶

Tier	Order fields	Cost
Fast	`trackedEntity`, `createdAt`	Proportional to `page` (offset) + `pageSize`
Slow	`updatedAt`, `createdAtClient`, `updatedAtClient`, `inactive`	Proportional to total matching tracked entities
Very slow	`enrolledAt`, tracked entity attribute UIDs	Proportional to total matching tracked entities + per-record lookup in related tables

enrolledAt additionally requires deduplication when a tracked entity has multiple enrollments in the same program. Programs configured with "Only enroll once" avoid this deduplication cost.

`/api/tracker/enrollments`¶

Ordering¶

Tier	Order fields	Cost
Slow	`enrolledAt`, `createdAt`, `completedAt`, `updatedAt`, `createdAtClient`, `updatedAtClient`	Proportional to total matching enrollments

All enrollment order fields currently lack a composite index. The database must scan and sort all matching enrollments before returning the requested page.

`/api/tracker/events` (Tracker Programs)¶

Filtros¶

program is mandatory and can be combined with programStage to narrow to a single stage.

Ownership¶

Every tracker event query must traverse enrollment and ownership records to enforce access control. On a program with hundreds of thousands of enrollments, broad queries (e.g., orgUnitMode=ALL without filters) must process all ownership records before any event-level work can begin. An index on the event table alone cannot help because the ownership check happens on a different table.

The most effective way to reduce cost is to provide a narrow org unit scope. A user scoped to a single facility produces a small ownership set, making the rest of the query fast regardless of other parameters.

Enrollment-level filters (enrollmentStatus, followUp, enrollment date ranges) are not backed by indexes. They can still reduce the result set but do not reduce the number of records the database scans.

Ordering¶

Tier	Order fields	Cost
Slow	`occurredAt`, `scheduledAt`, `createdAt`, `updatedAt`, `completedAt`, `createdAtClient`, `updatedAtClient`, `enrolledAt`, data element UIDs	Proportional to total matching events (after ownership join)
Very slow	tracked entity attribute UIDs	Proportional to total matching events + per-event cross-resource lookup

All tracker event order fields lack a composite index at the program level. The database must traverse enrollment and ownership records, collect all matching events, sort them, and return the requested page. Cost scales with total matching events, not page size.

Specifying programStage does not improve ordering performance because the bottleneck is the ownership join, not the event-level scan.

enrolledAt comes from the enrollment table which is already part of the ownership join, so it does not require an additional lookup. Attribute UIDs require a cross-resource lookup to the tracked entity for every matching event.

`/api/tracker/events` (Event Programs)¶

Event programs (programs without registration) have no enrollment or ownership overhead. The database goes directly from the event to its org unit, making these queries structurally faster than tracker program queries.

Filtros¶

program is mandatory.

Organisation Unit Mode¶

With the default occurredAt order, the database walks the sorted index and filters each event by org unit. This is fast when matching events appear early in the index. For SELECTED, DESCENDANTS, and ACCESSIBLE, performance depends on how the matching org units' events are distributed across the sort order. If matching events are rare or concentrated at the end of the index, the database must scan many non-matching events first. On program stages with millions of events where the user's org units cover only a small fraction, this can result in scanning large portions of the index before filling a single page. Adding occurredAfter and/or occurredBefore limits the scan to a bounded window and is recommended for high-volume program stages.

ALL avoids org unit filtering entirely and is fast with the default order. CHILDREN is slow for the same reasons described in the general principles.

Without the default occurredAt order, all modes require scanning and sorting all matching events.

Ordering¶

The default order is occurredAt desc. This is the most efficient order for event programs.

Tier	Order fields	Cost
Fast (indexed)	`occurredAt`	Proportional to `page` (offset) + `pageSize`. Degrades when org unit filtering is active but matches are sparse — see Organisation Unit Mode above.
Slow (no index)	`createdAt`, `updatedAt`, `completedAt`, `createdAtClient`, `updatedAtClient`	Proportional to total events for the program stage
Slow (JSON extraction)	Data element UIDs	Requires extracting and sorting JSON values for every matching event