Trasovač¶

Caution

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

Tracker (deprecated) describes the deprecated 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

The deprecated endpoints will be 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.

Objekty Trasovače¶

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

Události¶

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 all events are either connected to the same enrollment (EVENT PROGRAM) or 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 actual values describing the tracked entities. They can either be connected through a tracked entity type or a program. Implicitly this means attributes can be part of both a tracked entity and an enrollment.

Note

For attributes only the "attribute" and "value" properties are required when adding data. "value" can be null, which implies the user should remove the value.

In the context of tracker objects, we refer to Tracked Entity Attributes and Tracked Entity Attribute Values as "attributes". However, attributes are also their own thing, related to metadata. Therefore, it's vital to separate Tracker attributes and metadata attributes. In the tracker API, it is possible to reference the metadata attributes when specifying idScheme (See request parameters for more information).

Data Values¶

Zatímco Attributes popisuje trasovanou entitu nebo zápis, datové hodnoty popisují událost. Hlavní rozdíl spočívá v tom, že atributy mohou mít pro danou trasovanou entitu pouze jednu hodnotu. Naproti tomu datové hodnoty mohou mít mnoho různých hodnot pro různé události - i když všechny události patří ke stejnému zápisu nebo trasované entitě.

Note

For data elements only the "dataElement" and "value" properties are required when adding data. "value" can be null, which implies the user should remove the value.

Poznámky¶

DHIS2 tracker allows for capturing of data using data elements and tracked entity attributes. However, sometimes there could be a situation where it is necessary to record additional information or comment about the issue at hand. Such additional information can be captured using notes. Notes are equivalent to data value comments from the Aggregate DHIS2 side.

There are two types of notes - notes recorded at the event level and those recorded at the enrollment level. An enrollment can have one or more events. Comments about each of the events - for example, why an event was missed, rescheduled, or why only a few data elements were filled and the like - can be documented using event notes. Each of the events within an enrollment can have its own story/notes. One can then record, for example, an overall observation of these events using the parent enrollment note. Enrollment notes are also helpful to document, for example, why an enrollment is canceled. It is the user's imagination and use-case when and how to use notes.

Both enrollment and event can have as many notes as needed - there is no limit. However, it is not possible to delete or update neither of these notes. They are like a logbook. If one wants to amend a note, one can do so by creating another note. The only way to delete a note is by deleting the parent object - either event or enrollment.

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

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

Uživatelé¶

One between uid or username field must be provided. If both are provided, only username is considered.

Program stage working lists¶

The program stage working lists feature within the Capture app is designed to display pre-established working lists relevant to a particular program stage. This functionality enables users to save filters and sorting preferences that are related to program stages, facilitating the organisation and management of their workflow. To interact with them, you'll need to use the /api/programStageWorkingLists resource. These lists can be shared and follow the same sharing pattern as any other metadata. When using the /api/sharing the type parameter will be programStageWorkingLists.

/api/40/programStageWorkingLists

Payload on CRUD operations to program stage working lists¶

The endpoint above can be used to get all program stage working lists. To get a single one, just add at the end the id of the one you are interested in. This is the same in case you want to delete it. On the other hand, if you are looking to create or update a program stage working list, besides the endpoint mentioned above, you'll need to provide a payload in the following format:

Tabulka: Datový obsah

See an example payload below:

{
    "name":"Test WL",
    "program":{"id":"uy2gU8kT1jF"},
    "programStage":{"id":"oRySG82BKE6"},
    "description": "Test WL definition",
    "programStageQueryCriteria":
        {
            "status":"VISITED",
            "eventCreatedAt":{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"},
            "scheduledAt": {"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"
            }]
        }
}

Import trackeru (POST /api/tracker)¶

The POST /api/tracker endpoint allows clients to import the following tracker objects

• Trasované entity
• Zápisy
• Události
• Relationships
• Data vložená do jiných trasovacích objektů

Request parameters¶

V současné době koncový bod importu trackeru podporuje následující parametry:

NOTE: idScheme and its metadata specific idScheme parameters like orgUnitIdScheme, programIdScheme, ... used to allow and use the default AUTO. AUTO has been removed. The default idScheme has already been UID. Any requests sent with idScheme AUTO will see the same behavior as before, namely matching done using UID.

Flat and nested payloads¶

The importer support both flat and nested payloads.

Flat

The flat payload can contain collections for each of the core tracker objects we have at the

top level. This works seamlessly with existing data, which already have UIDs assigned. However,

for new data, the client will have to provide new UIDs for any references between objects. For

example, if you import a new tracked entity with a new enrollment, the tracked entity requires

the client to provide a UID so that the enrollment can be linked to that UID.

Nested

Nested payloads are the most commonly used structure. Here, tracker objects are embedded within

their parent object. For example, 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 done

automatically.

NOTE

While nested payloads might prove simpler for clients to deal with, the payload will always be flattened before the import. This means that for large imports, providing a flat structured payload will provide both more control and lower overhead for the import process itself.

Examples for the FLAT and the NESTED versions of the payload are listed below.

FLAT payload¶

{
  "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"
    }
  ],
  "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¶

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

SYNC and ASYNC¶

For the user, the main difference between importing synchronously rather than asynchronously is the immediate response from the API. For the synchronous import, the response will be returned as soon as the import finishes with the importSummary. However, for asynchronous imports, the response will be immediate and contain a reference where the client can poll for updates to the import.

For significant imports, it might be beneficial for the client to use the asynchronous import to avoid waiting too long for a response.

Examples of the ASYNC response is shown below. For SYNC response, look at the importSummary section.

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

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

Souhrn importu¶

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": "mru3HJrFGKA",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.313",
    "message": "Running Validation",
    "completed": false,
    "id": "mru3HJrFGKA"
  },
  {
    "uid": "oTbCUJ2RnA6",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.312",
    "message": "Running PreProcess",
    "completed": false,
    "id": "oTbCUJ2RnA6"
  },
  {
    "uid": "lcUNbWTn6uh",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.312",
    "message": "Calculating Payload Size",
    "completed": false,
    "id": "lcUNbWTn6uh"
  },
  {
    "uid": "l4jQiSS9qdK",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:15.903",
    "message": "Running PreHeat",
    "completed": false,
    "id": "l4jQiSS9qdK"
  },
  {
    "uid": "qGbiuqgwPX5",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:15.850",
    "message": "Loading file content",
    "completed": false,
    "id": "qGbiuqgwPX5"
  },
  {
    "uid": "eWNHzVf7iAj",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:15.838",
    "message": "Loading file resource",
    "completed": false,
    "id": "eWNHzVf7iAj"
  },
  {
    "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 Structure¶

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.

validationReport

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.

stats

The stats provide a quick overview of the import. After an import is completed, these will be the actual counts representing how much data was created, updated, deleted, or ignored.

Příklad:

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

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

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

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

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

bundleReport

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

Například 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": []
          }
        ]
      }
    }
  }
}

As seen, 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 is applicable.

message

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

Import Summary Report Level¶

As previously stated, GET /tracker/jobs/{uid}/report can be retrieved using a specific reportMode parameter. By default the endpoint will return an importSummary with reportMode ERROR.

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

Kódy chyb¶

There are various error codes for different error scenarios. The following table has the list of error codes thrown from the new 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.

Ověření¶

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 Object 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 (Organisation Unit 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's access will be treated as if it doesn't 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.

Attribute 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. Currently, removing mandatory attributes is not 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 fpound 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:

• Typ prvku (pro geometrii)
• Uživatelsky přiřaditelné události
• Povolit budoucí data
• Zapsat se jednou
• A více.

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

Pravidla programu¶

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:

• The program rule must be linked to the data being imported. For example, a program stage or a data element.
• Podmínka programového pravidla musí být vyhodnocena jako true

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

• Akce programových pravidel mohou skončit se 2 různými výsledky: Varování nebo Chyby.
• Errors will make the validation fail, while the warnings will be reported as a message in the import summary.
  • Akce SHOWWARNING a WARNINGONCOMPLETION mohou generovat pouze varování.
  • 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 set to 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.

POZNÁMKA

Programová pravidla lze během importu přeskočit pomocí parametru skipProgramRules.

Vedlejší účinky¶

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:

POZNÁMKA

Určité konfigurace mohou řídit provádění vedlejších účinků. Během importu lze nastavit příznak skipSideEffects, aby se vedlejší efekty zcela vynechaly. Tento parametr může být užitečný, pokud například importujete něco, na co nechcete spouštět upozornění.

Přiřadit uživatele k událostem¶

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:

• tracked entities
• events
• enrollments
• relationships

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 endpoint supports standard parameters for pagination.

• Tracked entities GET /api/tracker/trackedEntities
• Události GET /api/tracker/events
• Enrollments GET /api/tracker/enrollments
• Relationships GET /api/tracker/relationships

Request parameters for pagination¶

Caution

Be aware that the performance is directly related to the amount of data requested. Larger pages will take more time to return.

Request parameters for Organisational Unit selection mode¶

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

Request parameter to 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}
• načte trasovanou entitu podle poskytnutého 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 (UID)
• createdAt (Datetime)
• createdAtClient (Datetime)
• updatedAt (Datetime)
• updatedAtClient (Datetime)
• orgUnit (UID)
• inactive (boolean)
• deleted (boolean)
• potentialDuplicate (boolean)
• geometry (WKT, https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry. 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 (UID)
• 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 Entities Collection endpoint 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 specifikováno.

• 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 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 in an IN filter:

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

K filtrování můžete použít řadu operátorů:

Tracked Entities response example¶

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

JSON¶

Responses can be filtered on desired fields, see Request parameter to filter responses

A JSON response can look 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 can look 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}¶

Účelem tohoto koncového bodu je načíst jednu trasovanou entitu s jejím uid.

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

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

JSON¶

Příklad odpovědi json:

{
  "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",
      "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": [],
          "followup": false
        }
      ],
      "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 response example¶

Příklad odpovědi json:

{
   "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":{
            "dataValue":{
               "dataElement":"bx6fsa0t90x",
               "previousValue":"true",
               "currentValue":"false"
            }
         }
      },
      {
         "createdBy":{
            "uid":"AIK2aQOJIbj",
            "username":"tracker",
            "firstName":"Tracker demo",
            "surname":"User"
         },
         "createdAt":"2024-06-20T14:50:32.966",
         "type":"CREATE",
         "change":{
            "dataValue":{
               "dataElement":"ebaJjqltK5N",
               "currentValue":"0"
            }
         }
      }
   ]
}

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

Pro zápisy jsou vyhrazeny dva koncové body:

• GET /api/tracker/enrollments
  • načte zápisy odpovídající zadaným kritériím
• GET /api/tracker/enrollments/{id}
  • načte zápis podle poskytnutého ID

Enrollment Collection endpoint GET /api/tracker/enrollments¶

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

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

• 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 followUp is specified, then program must also be specified.

• If enrolledAfter or enrolledBefore is specified, then program must also be specified.

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

Odpověď JSON může vypadat následovně.

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

Koncový bod registrace jednoho objektu GET /api/tracker/enrollments/{uid}¶

Účelem tohoto koncového bodu je načíst jednu prohlášku s jejím uid.

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:

• GET /api/tracker/events
  • načte události odpovídající zadaným kritériím
• GET /api/tracker/events/{id}
  • načte událost se zadaným 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:

• event (UID)
• status (String)
• program (UID)
• programStage (UID)
• enrollment (UID)
• orgUnit (UID)
• occurredAt (DateTime)
• scheduledAt (DateTime)
• geometry (WKT, https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry. 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)
• followUp (boolean)
• deleted (boolean)
• createdAt (DateTime)
• createdAtClient (DateTime)
• updatedAt (DateTime)
• updatedAtClient (DateTime)
• completedBy (String)
• completedAt (DateTime)
• updatedBy (UserName of user)
• attributeOptionCombo (UID)
• attributeCategoryOptions (UID)
• assignedUser (UserName of user)
• dataElement (UID)
• value (String)
• storedBy (String)
• providedElsewhere (boolean)
• storedByDataValue (String)
• createAtDataValue (DateTime)
• updatedAtDataValue (DateTime)

See Events and Data Values for more field descriptions.

Events GZIP¶

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

Events ZIP¶

The response is fileevents.json.gz or events.json.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 attributeCategoryOptions 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 older 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

Koncový bod jednoho objektu událostí GET /api/tracker/events/{uid}¶

Účelem tohoto koncového bodu je načíst jednu událost s jejím uid.

Požádat o syntaxi¶

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

Example requests¶

Dotaz na událost:

GET /api/tracker/events/rgWr86qs0sI

Event response example¶

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

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
}