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¶

Le Tracker est constitué de différents types d'objets interconnectés destinés à représenter les données. Dans cette section, nous montrerons et décrirons chacun des objets utilisés dans l'API du Tracker.

Tracked entities¶

Les entités suivies constituent la base du modèle Tracker.

Remarque

Les entités suivies "possèdent" toutes les Valeurs d'attribut d'entités suivies (ou les "attributs" décrits dans le tableau précédent). Cependant, les attributs d'entités suivies sont soit connectés à une entité suivie via son type d'entité suivie soit à un programme. Nous désignons souvent cette séparation par Attributs de type d'entité suivi et Attributs de programme d'entité suivi. L'importance de cette distinction est liée au contrôle d'accès et à la limitation des informations que l'utilisateur peut voir.

Les "attributs" mentionnés dans Entité suivie sont des Attributs de type d'entité suivie.

Inscriptions¶

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.

Remarque

Les entités suivies "possèdent" toutes les Valeurs d'attribut d'entités suivies (ou les "attributs" décrits dans le tableau précédent). Cependant, les attributs d'entités suivies sont soit connectés à une entité suivie via son type d'entité suivie soit à un programme. Nous désignons souvent cette séparation par Attributs de type d'entité suivi et Attributs de programme d'entité suivi. L'importance de cette distinction est liée au contrôle d'accès et à la limitation des informations que l'utilisateur peut voir.

Les "attributs" mentionnés dans Inscription sont des Attributs de programmes d'entités suivies.

Events¶

Les Événements font partie d'un PROGRAMME D'ÉVÉNEMENT ou d'un PROGRAMME TRACKER. Pour le PROGRAMME TRACKER, les événements appartiennent à une Inscription, laquelle appartient à une Entité suivie. D'un autre côté, PROGRAMME D'ÉVÉNEMENT concerne les Événements non rattachées à une Inscription ou à une Entité suivie spécifique. La différence réside dans le fait que nous effectuons ou non un suivi pour une Entité suivie spécifique. Nous désignons parfois les événements PROGRAMME D'ÉVÉNEMENT "événements anonymes "ou "événements uniques" puisqu'ils ne se représentent qu'eux-mêmes et non une autre Entité suivie.

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.

Relations¶

Les Relations sont des objets qui relient deux autres objets Tracker. Les contraintes auxquelles chaque côté de la relation doit se conformer sont basées sur le Type de relation de la Relation.

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

Les attributs¶

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.

Remarques¶

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

Utilisateurs¶

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

• Entités suivies
• Enrollments
• Événements
• Relations
• 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.

Importation CSV¶

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

Événements¶

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¶

Votre fichier CSV peut se présenter comme suit :

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

Voir Événements CSV dans la section relative à l'exportation pour une définition plus détaillée des champs CSV.

Import summary¶

L'API du Tracker dispose de deux endpoints de base qui permettent aux consommateurs d'obtenir des commentaires sur leurs importations. Ces endpoints concernent plus les tâches d'importation asynchrone, mais ils sont également disponibles pour les importations synchrones. Ces endpoints renverront soit le journal de l'importation, soit le récapitulatif de l'importation lui-même.

Remarque

Ces endpoints s'appuient sur des informations stockées dans la mémoire de l'application. Cela signifie que les informations seront indisponibles après certaines situations, telle qu'un redémarrage de l'application ou après un grand nombre de requêtes d'importation qui commencent après celle-ci.

Après avoir soumis une requête d'importation Tracker, nous pouvons accéder aux endpoints suivants afin de surveiller la progression de la tâche en fonction des journaux:

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

De plus, le endpoint suivant renverra le récapitulatif de la tâche d’importation. Ce récapitulatif ne sera disponible qu'une fois l'importation terminée:

GET /tracker/jobs/{uid}/report

Request example¶

GET /tracker/jobs/mEfEaFSCKCC/report

Response example¶

La charge de la réponse est la même que celle renvoyée après une requête d'importation synchrone.

Remarque

Les deux endpoints sont principalement utilisés pour l'importation asynchrone. Cependant, GET /tracker/jobs/{uid} devrait également fonctionner pour les requêtes synchrones car au final il utilise le même processus d'importation et la même journalisation que les requêtes asynchrones.

Import summary response¶

La structure globale des récapitulatifs d'importation se présente comme suit, en fonction du mode de rapport faisant l'objet de la requête :

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

Statut¶

La propriété statut du récapitulatif d'importation indique l'état global de l'importation. Si aucune erreur ou avertissement n'est signalé(e) lors de l'importation, le statut est OK. Par contre, si une erreur ou un avertissement est signalé(e) lors de l'importation, le statut devient ERREUR ou AVERTISSEMENT.

Le statut dépend de la présence du Rapport de validation le plus important. ERREUR est le plus important, suivi de AVERTISSEMENT et enfin OK. Cela signifie que le statut est ERREUR si une seule erreur est détectée lors de l'importation, quel que soit le nombre d'avertissements.

Remarque

Si l'importation est faite selon le mode atomique "OBJET", où les données sont importées sans erreurs de validation, le statut sera toujours ERREUR si des erreurs sont détectées.

Validation report¶

Le Rapport de validation peut inclure des Rapports d'erreur et des Rapports d'avertissement si des erreurs ou des avertissements étaient présents lors de l'importation. Lorsqu'ils sont présents, ils fournissent une liste détaillée des erreurs ou avertissements rencontrés.

Prenons l'exemple d'une erreur de validation lors de l'importation d'une ENTIÉE_SUIVIE :

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

Remarque

Les uid des objets trackers servent de noms à ces objets dans la charge. Par exemple, l'uid d'une entité suivie dans la charge serait "trackedEntity". La même chose s'applique aux inscriptions, aux événements et aux relations qui portent respectivement les noms "enrollment", "event" et "relationship".

Si aucun uid n'est fourni dans la charge, le processus d'importation générera de nouveaux uids. Cela signifie que le rapport d'erreur peut faire référence à un uid qui n'existe pas dans votre charge.

Les erreurs signalent des problèmes avec la charge que l'importateur ne peut pas contourner. Toute erreur empêchera l'importation de ces données. Les avertissements, en revanche, sont des problèmes qui peuvent être contournés en toute sécurité, mais dont l'utilisateur doit être informé. Les avertissements ne bloquent pas l'importation des données.

Statistiques¶

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.

Exemple de réponse :

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

Une fois l'importation terminée, le bundleReport contient tous les objets tracker importés.

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¶

Si l'importation se termine brusquement, le message va contenir des informations supplémentaires sur ce qui s'est passé.

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.

De plus, tous les reportModes (modes de rapports) renverront statut, statistiques, bundleReport et message le cas échéant.

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¶

Lors de l'importation de données à l'aide de l'importateur du Tracker, une série de validations est effectuée pour garantir la validité des données. Cette section décrit certains types de validation effectués afin que vous puissiez mieux comprendre un échec de validation lors de votre importation.

Propriétés requises¶

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.

Lors de la validation des propriétés requises, nous parlons généralement de références à d'autres données ou métadonnées. Dans ces cas, on note trois critères principaux :

1. La référence est présente dans la charge utile et est non nulle.
2. La référence indique le bon type de données et existe dans la base de données
3. L'utilisateur est autorisé à voir la référence

Si la première condition n'est pas remplie, l'importation échouera et un message indiquant une référence manquante sera généré. Cependant, si la référence indique un objet qui n'existe pas ou auquel l'utilisateur n'a pas accès, le message généré indiquera que la référence n'a pas été trouvée.

Formats¶

Certaines propriétés des objets Tracker requièrent un format spécifique. Lors de l'importation des données, chacune de ces propriétés est validée au regard du format attendu et renvoie des erreurs en fonction de la propriété dont le format est incorrect. Voici quelques exemples de propriétés validées de cette manière :

• Les identifiants d'utilisateur ou UID (Ils couvrent toutes les références à d’autres données ou métadonnées dans DHIS2.)
• Dates
• Géométrie (Les coordonnées doivent correspondre au format spécifié par son type)

Accès des utilisateurs¶

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.

Les utilisateurs disposant de l'autorité TOUS ne sont pas affectés par les limites des champs d'application de partage et d'unité d'organisation lorsqu'ils importent des données. Cependant, ils ne peuvent pas importer d'inscriptions dans des unités d'organisation qui n'ont pas accès au programme d'inscription.

Attributes and data values¶

Les attributs et les valeurs de données font partie respectivement d'une entité suivie et d'un événement. Cependant, les attributs peuvent être liés à une entité suivie soit par son type (TrackedEntityType), soit par son programme (Program). Les attributs peuvent également être uniques.

La première validation effectuée lors de l'importation consiste à s'assurer que la valeur fournie pour un attribut ou un élément de données est conforme au type de valeur attendu. Par exemple, supposons que vous importiez une valeur pour un élément de données de type numérique. Dans ce cas, la valeur doit être numérique. Toute erreur liée à une non-concordance entre un type et une valeur se traduira par le même code d'erreur, mais avec un message spécifique lié au type de 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.

Configuration¶

Les dernières validations dans l'importateur sont des validations basées sur la configuration des métadonnées pertinentes par l'utilisateur. Pour plus d'informations sur chaque configuration, consultez les sections correspondantes. Trouvez ci-après quelques exemples de validations configurables :

• Feature type (geometry)
• Événements attribuables à l'utilisateur
• Autoriser les dates futures
• Inscrire une fois

Ces configurations apporteront des modifications supplémentaires à la manière dont la validation est effectuée lors de l'importation.

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

Point d'extrémité de de génération de valeur¶

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

Point d'extrémité de génération et de réservation de valeur¶

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

Valeurs réservées¶

Les valeurs réservées ne sont actuellement pas accessibles via l'API, mais elles sont renvoyées par les points d'extrémité generate (génération) et generate And Reserve (génération et réservation). Le tableau suivant explique les propriétés de l'objet de valeur réservée :

Tableau : Valeurs réservées

Les réservations expirées sont supprimées quotidiennement. Si un modèle change, les valeurs déjà réservées seront acceptées lors du stockage des données, même si elles ne correspondent pas au nouveau modèle, tant que la réservation n'a pas expiré.

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.

Toutes les actions de règles de programme ne sont pas prises en charge, car elles ne sont adaptées qu'à une présentation de type « frontend ». Une liste complète des actions de règles de programme prises en charge est présentée ci-dessous.

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:

• La règle de programme doit être liée aux données importées ; par exemple, une étape de programme ou un élément de données.
• The program rule condition must be evaluated to true.

Les résultats des règles de programme dépendent des actions définies dans ces règles :

• Program rule actions may end in 2 different results: warnings or errors.
• Les erreurs feront échouer la validation, tandis que les avertissements seront rapportés sous forme de message dans le récapitulatif de l'importation.
  • 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.
  • Lorsque l'action attribue une valeur à un attribut/élément de données vide, un avertissement est généré.
  • Lorsque l'action attribue une valeur à un attribut/élément de données qui a déjà la même valeur à attribuer, un avertissement est généré.
  • 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.

Les règles de programme peuvent également entraîner des effets secondaires, telles que l'envoi et la planification de messages. Pour plus d’informations sur les actions non voulues, veuillez consulter la section suivante.

Note

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

Side effects¶

Une fois qu'une importation est terminée, des tâches spécifiques peuvent être déclenchées du fait de cette importation. Ces tâches sont ce que nous appelons des « effets secondaires ». Ces tâches exécutent des opérations qui n'affectent pas l'importation elle-même.

Les effets secondaires sont des tâches qui s'exécutent séparément de l'importation, mais qui sont toujours déclenchées par une importation. Étant donné que les effets secondaires sont dissociés de l'importation, ils peuvent échouer même si l'importation réussit. De plus, les effets secondaires ne sont exécutés que lorsque l'importation réussit ; ils ne peuvent donc pas échouer dans l'autre sens.

Voici donc les effets secondaires actuellement pris en charge :

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¶

Certains processus bénéficient du fait que des événements soient traités comme des tâches, et pour cette raison, vous pouvez assigner un utilisateur à un événement.

L'assignation d'un utilisateur à un événement ne modifie pas l'accès ou les autorisations des utilisateurs, mais crée un lien entre l'événement et l'utilisateur. Lorsqu'un utilisateur est assigné à un événement, vous pouvez lancer des requêtes sur les événements à partir de l'API en utilisant le champ assignedUser (utilisateur attribué) en tant que paramètre.

Lorsque vous voulez assigner un utilisateur à un événement, fournissez simplement l'UID de cet utilisateur dans le champ assignedUser. Voir l'exemple suivant:

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

Pour utiliser cette fonctionnalité, l'assignation d'utilisateurs doit être activée pour l'étape de programme concernée et l'uid fourni pour l'utilisateur doit renvoyer à un utilisateur existant et valide.

Tracker export¶

Les points d'extrémité de l'exportation Tracker vous permettent de récupérer les objets précédemment importés, à savoir :

• Entités suivies
• Événements
• Enrollments
• Relations

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.

Paramètres de requête courants¶

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

Paramètres de requête pour la 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¶

Tous les points d'extrémité d'exportation acceptent un paramètre fields (champs) qui contrôle les champs qui seront renvoyés dans la réponse JSON. Le paramètre fields accepte une liste de noms de champs ou de modèles séparés par des virgules. Quelques filtres fields possibles sont présentés ci-dessous. Consultez la section [filtre de champ de métadonnées (#webapi_metadata_field_filter)] pour obtenir un guide plus complet sur l'utilisation du paramètre fields.

Exemples¶

Tracked entities¶

GET /api/tracker/trackedEntities

Deux points d'extrémité sont dédiés aux entités suivies :

• GET /api/tracker/trackedEntities
• récupère les entités suivies correspondant aux critères donnés
• 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:

• Entité suivie (UID)
• trackedEntityType (identifier in requested idScheme)
• createdAt (Date et heure)
• createdAtClient (Date et heure)
• updatedAt (Date et heure)
• updatedAtClient (Date et heure)
• orgUnit (identifier in requested idScheme)
• inactif (booléen)
• supprimé (booléen)
• potentialDuplicate (booléen)
• geometry (WKT) Vous pouvez l'omettre dans le cas d'un type de Point et si la latitude et la longitude sont fournies)
• latitude (Latitude d'un type de géométrie Point)
• longitude (Longitude d'un type de géométrie Point)
• attribute (identifier in requested idScheme)
• Afficher le nom (Chaîne)
• attrCreatedAt (Date de création de l'attribut)
• attrUpdatedAt (Date de la dernière mise à jour de l'attribut)
• type de valeur (Chaîne)
• valeur (Chaîne)
• stockéBy (Chaîne)
• createdBy (Nom d'utilisateur de l'utilisateur)
• updatedBy (Nom d'utilisateur de l'utilisateur)

Voir Entités suivies et Attributs pour plus de descriptions de champs.

GZIP¶

La réponse est le fichier trackedEntities.csv.gz contenant le fichier trackedEntities.csv.

ZIP¶

La réponse est le fichier trackedEntities.csv.zip contenant le fichier trackedEntities.csv.

Tracked entity collections¶

GET /api/tracker/trackedEntities

Le but de ce point d'extrémité est de récupérer les entités suivies correspondant aux critères fournis par le client.

Le point d'extrémité renvoie une liste d'entités suivies qui correspondent aux paramètres de la requête.

Les modes d'utilisateur assigné disponibles sont expliqués dans le tableau suivant.

Tableau : Modes d'utilisateur assigné

La requête n'est pas sensible à la casse. Les règles suivantes s'appliquent aux paramètres de requête.

• Au moins une unité d'organisation doit être spécifiée avec le paramètre orgUnit (un ou plusieurs), ou orgUnitMode=ALL doit être spécifié.
• Un seul des paramètres program et trackedEntity peut être spécifié (zéro ou un).
• If programStatus is specified, then program must also be specified.
• If enrollmentStatus is specified, then program must also be specified.
• Si followUp est spécifié, alors program doit également être spécifié.

• Si enrollmentEnrolledAfter ou enrollmentEnrolledBefore est spécifié, alors program doit également être spécifié.

• Les éléments du filtre ne peuvent être spécifiés qu'une seule fois.

Exemples de requêtes¶

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

Pour lancer une requête sur les entités suivies en utilisant un attribut avec un filtre et un attribut sans filtre, avec une unité d'organisation en utilisant le mode de requête par unité d'organisation descendante :

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

Une requête dans laquelle plusieurs opérandes et filtres sont spécifiés pour un élément de filtre :

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

Un filtre de requête avec une valeur qui doit être échappée et qui sera interprétée comme :,/ :

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

Pour spécifier les dates d'inscription au programme dans la requête :

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,storedBy,createdBy,updatedBy,attrCreatedAt,attrUpdatedAt,attribute,displayName,value,valueType
F8yKM85NbxW,Zy2SEgA61ys,2019-08-21T11:25:38.022Z,2019-03-19T00:12:16.624Z,2019-08-21T11:31:33.410Z,2019-03-19T00:12:16.624Z,DiszpKrYNg8,false,false,false,"POINT (-11.7896 8.2593)",8.2593,-11.7896,,,,2019-08-21T11:25:38.477Z,2019-08-21T11:25:38.477Z,B6TnnFMgmCk,"Age (years)",30,INTEGER_ZERO_OR_POSITIVE
F8yKM85NbxW,Zy2SEgA61ys,2019-08-21T11:25:38.022Z,2019-03-19T00:12:16.624Z,2019-08-21T11:31:33.410Z,2019-03-19T00:12:16.624Z,DiszpKrYNg8,false,false,false,"POINT (-11.7896 8.2593)",8.2593,-11.7896,,,,2019-08-21T11:25:38.066Z,2019-08-21T11:25:38.067Z,TfdH5KvFmMy,"First Name",Sarah,TEXT
F8yKM85NbxW,Zy2SEgA61ys,2019-08-21T11:25:38.022Z,2019-03-19T00:12:16.624Z,2019-08-21T11:31:33.410Z,2019-03-19T00:12:16.624Z,DiszpKrYNg8,false,false,false,"POINT (-11.7896 8.2593)",8.2593,-11.7896,,,,2019-08-21T11:25:38.388Z,2019-08-21T11:25:38.388Z,aW66s2QSosT,"Last Name",Johnson,TEXT

Tracked entities collection limits¶

The collection endpoint limits results in three ways:

• KeyTrackedEntityMaxLimit in System settings: KeyTrackedEntityMaxLimit defines the maximum tracked entities in an API response, protecting database and server resources. No limit applies when set to 0. Configure it via /api/systemSettings as described in the documentation.

• Max number of TEs to return in Program or tracked entity type: it limits results when searching outside the capture scope with a specified program or tracked entity type. The API returns an error if matches exceed this limit. No limit applies when searching within the capture scope or when set to 0. This limit is configurable in the maintenance app.

• Pagination: As explained here.

For paginated requests with non-zero KeyTrackedEntityMaxLimit:

• If pageSize ≤ KeyTrackedEntityMaxLimit: pageSize is enforced

• If pageSize > KeyTrackedEntityMaxLimit: The API returns an error

Tracked entities single object endpoint¶

GET /api/tracker/trackedEntities/{uid}

This endpoint retrieves a tracked entity given by ID.

Syntaxe de la requête¶

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

Exemples de requêtes¶

Une requête pour une entité suivie:

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

Inscriptions¶

GET /api/tracker/enrollments

Two endpoints are dedicated to enrollments.

• GET /api/tracker/enrollments
  • récupère les inscriptions correspondant aux critères donnés
• GET /api/tracker/enrollments/{id}
  • retrieves an enrollment given the provided ID

Point d'extrémité de la collecte d'inscriptions 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.

Exemples de requêtes¶

Une requête pour toutes les inscriptions associées à une unité d'organisation spécifique peut ressembler à ceci :

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

Pour spécifier les dates d'inscription au programme dans la requête :

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

Pour limiter la réponse aux inscriptions d'une entité suivie spécifique, vous pouvez inclure un paramètre de requête d'entité suivie:

GET /api/tracker/enrollments?trackedEntity=ClJ3fn47c4s

Pour limiter la réponse aux inscriptions d'une entité suivie spécifique, vous pouvez inclure un paramètre de requête d'entité suivie. Dans ce cas, nous avons limité la réponse aux inscriptions disponibles pour l'utilisateur actuel :

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

Format de réponse¶

The JSON response can look like the following.

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

Enrollments single object endpoint¶

GET /api/tracker/enrollments/{uid}

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

Syntaxe de la requête¶

GET /api/tracker/enrollment/{uid}

Exemples de requêtes¶

A query for an enrollment.

GET /api/tracker/enrollments/JMgRZyeLWOo

Format de réponse¶

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

Événements 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.

Événements GZIP¶

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

Événements ZIP¶

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

Point d'extrémité de la collecte d'événements GET /api/tracker/events¶

Renvoie une liste d'événements en fonction des filtres fournis.

Note

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

Exemples de requêtes¶

La requête pour tous les événements associés aux subordonnées d'une unité d'organisation donnée :

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

La requête pour tous les événements associés à tous les descendants d'une unité d'organisation donnée, c'est-à-dire toutes les unités d'organisation qui lui sont inférieurs dans la hiérarchie :

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

Requête pour tous les événements associés à un programme et à une unité d'organisation :

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

La requête pour tous les événements disposant d'un programme et d'une unité d'organisation, ordonnés par date programmée en ordre croissant :

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

La requête pour les 10 événements dont la date de déroulement est la plus récente dans un programme et une unité d'organisation donné - par pagination et ordonnés par date de déroulement en ordre décroissant :

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

La requête pour tous les événements avec un programme et une unité d'organisation pour une entité suivie donnée :

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

Une requête dans laquelle plusieurs opérandes et filtres sont spécifiés pour un UID d'élément de données :

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

Un filtre de requête avec une valeur qui doit être échappée et qui sera interprétée comme :,/ :

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

Exemple de réponse des événements¶

L'API prend en charge les réponses CSV et JSON pour GET /api/tracker/events.

JSON¶

La réponse JSON peut ressembler à ce qui suit:

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