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¶

Trasované entity jsou kořenovým objektem pro model trasování.

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.

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.

Vztahy¶

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.

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" }
  }
}

Atributy¶

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.

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.

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.

Poznámky¶

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."
            }
          ]
        }
      ]
    }
  ]
}

Uživatelé¶

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.

• import
• tracked entity export
• event export

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

• Sledované entity
• Enrollments
• Události
• Vztahy
• Objects embedded in other tracker objects

Request parameters¶

The tracker importer supports the following parameters:

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.

Události¶

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 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 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¶

Souhrny importu mají v závislosti na požadovaném reportMode následující celkovou strukturu:

{
  "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.

Například chyba ověření při importu 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.

Příklad odpovědi:

{
  "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¶

Když je import dokončen, bundleReport obsahuje všechny importované objekty sledování.

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.

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.

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:

1. Reference je přítomna a není nulová v užitečném zatížení.
2. Odkaz ukazuje na správný typ dat a existuje v databázi
3. Uživatel má přístup k zobrazení 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:

• UID (Pokrývají všechny odkazy na jiná data nebo metadata v DHIS2.)
• Termíny
• Geometrie (souřadnice musí odpovídat formátu určenému jeho typem)

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.

Konfigurace¶

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)
• Uživatelsky přiřaditelné události
• Povolit budoucí data
• Zapsat se jednou

Tyto konfigurace dále změní způsob provádění ověřování během importu.

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"
  ]
}

Generovat koncový bod hodnoty¶

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"
}

Generovat a rezervovat koncový bod hodnoty¶

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"
  }
]

Rezervované hodnoty¶

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:

Tabulka: Rezervované hodnoty

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 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:

• Programové pravidlo musí být propojeno s importovanými daty. Například fáze programu nebo datový prvek.
• The program rule condition must be evaluated to true.

Výsledky pravidel programu závisí na akcích definovaných v těchto pravidlech:

• Program rule actions may end in 2 different results: warnings or errors.
• Chyby způsobí selhání ověření, zatímco varování budou hlášena jako zpráva v souhrnu importu.
  • 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.
  • Když akce přiřazuje hodnotu prázdnému prvku atributu/dat, vygeneruje se varování.
  • Když akce přiřazuje hodnotu atributu/datovému prvku, který již má stejnou hodnotu, která má být přiřazena, vygeneruje se varování.
  • 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.

V současné době jsou podporovány následující vedlejší účinky:

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:

• Sledované entity
• Události
• Enrollments
• Vztahy

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¶

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.

Příklady¶

Tracked entities¶

GET /api/tracker/trackedEntities

Dva koncové body jsou vyhrazeny trasovaným entitám:

• GET /api/tracker/trackedEntities
• načte trasované entity odpovídající daným kritériím
• 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)
• 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

Účelem tohoto koncového bodu je načíst trasované entity odpovídající kritériím zadaným klientem.

Koncový bod vrátí seznam trasovaných entit, které odpovídají parametrům požadavku.

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

Tabulka: Přiřazené uživatelské režimy

V dotazu se nerozlišují velká a malá písmena. Pro parametry dotazu platí následující pravidla.

• 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 specifikováno (nula nebo jedna).
• 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.

• Položky filtru lze zadat pouze jednou.

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

Dotaz, kde je pro položku filtru zadáno více operandů a filtrů:

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:/:/,//

Chcete-li zadat data zápisu programu jako součást dotazu:

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:

*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:

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

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,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.

Požádat o syntaxi¶

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

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.

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.

More on change log configuration here

Enrollments¶

GET /api/tracker/enrollments

Two endpoints are dedicated to enrollments.

• GET /api/tracker/enrollments
  • načte zápisy odpovídající zadaným kritériím
• 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.

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

Example requests¶

Dotaz na všechny zápisy přidružené ke konkrétní organizační jednotce může vypadat takto:

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

Chcete-li zadat data zápisu programu jako součást dotazu:

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

Formát odpovědi¶

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,
      "notes": []
    }
  ]
}

Enrollments single object endpoint¶

GET /api/tracker/enrollments/{uid}

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

Požádat o syntaxi¶

GET /api/tracker/enrollment/{uid}

Example requests¶

A query for an enrollment.

GET /api/tracker/enrollments/JMgRZyeLWOo

Formát odpovědi¶

{
  "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:

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¶

Vrátí seznam událostí na základě poskytnutých filtrů.

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¶

Dotaz na všechny události s potomky konkrétní organizační jednotky:

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

Dotaz na všechny události s určitou programovou a organizační jednotkou:

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",
          "providedElsewhere": false,
          "dataElement": "F3ogKBuviRA",
          "value": "[-11.4880220438585,7.50978830548003]"
        },
        {
          "createdAt": "2013-12-30T14:23:57.423",
          "updatedAt": "2013-12-30T14:23:57.423",
          "providedElsewhere": false,
          "dataElement": "eMyVanycQSC",
          "value": "2018-02-07"
        },
        {
          "createdAt": "2013-12-30T14:23:57.382",
          "updatedAt": "2013-12-30T14:23:57.382",
          "providedElsewhere": false,
          "dataElement": "oZg33kd9taw",
          "value": "Male"
        }
      ],
      "notes": [],
      "followup": false
    }
  ]
}