Tracker¶

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

• POST /api/tracker
• GET /api/tracker/enrollments
• GET /api/tracker/events
• GET /api/tracker/trackedEntities
• GET /api/tracker/relationships

Tracker (deprecated) describes the deprecated endpoints

• GET/POST/PUT/DELETE /api/trackedEntityInstances
• GET/POST/PUT/DELETE /api/enrollments
• GET/POST/PUT/DELETE /api/events

• GET/POST/PUT/DELETE /api/relationships

• If your are still using the deprecated tracker endpoints in production, please plan to migrate over to the new endpoints. Migrating to new tracker endpoints should help you get started. Reach out on the community of practice if you need further assistance. NOTE: The feature for data sync(importMode=SYNC) is not implemented in the new tracker endpoints, and if you are using this feature you will have to postpone the migration until a new SYNC feature is in place.

Objets du Tracker¶

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.

Entité suivie¶

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.

Inscription¶

Les Entités suivies peuvent s'inscrire aux Programmes pour lesquels elles sont éligibles. Les entités suivies sont éligibles tant que le programme est configuré avec le même Type d'entité suivie que l'entité suivie. Nous représentons l'inscription avec l'objet Inscription, que nous décrivons dans cette 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.

Événements¶

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.

Dans l'API, la différence majeure est que tous les événements sont soit rattachés à la même inscription (PROGRAMME D'ÉVÈNEMENT), soit à des inscriptions différentes (PROGRAMME TRACKER). Le tableau ci-dessous signalera les cas exceptionnels entre ces deux.

Relation¶

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.

Remarque

Un Élément de relation représente un lien vers un objet. Étant donné qu'il peut y avoir une relation entre n'importe quel objet Tracker tel qu'une entité suivie, une inscription et un évènement, la valeur dépend du type de relation. Par exemple, si le type de relation relie un événement et une entité suivie, le format est strict :

{
 "de": {
 "événement": { "événement": "ABCDEF12345" }
 },
 "à": {
 "trackedEntity": { "trackedEntity": "FEDCBA12345" }
 }
}

Attribut¶

Les Attributs sont les valeurs qui décrivent les entités suivies. Ils peuvent être reliés via un type d'entité suivi ou un programme. Implicitement, cela signifie que les attributs peuvent faire partie à la fois d'une entité suivie et d'une inscription.

Remarque

Pour les attributs, seules les propriétés "attribut" et "valeur" sont requises lors de l'ajout des données. Une "valeur" peut être nulle, et dans ce cas l'utilisateur doit la supprimer.

Dans le contexte des objets Tracker, nous considérons les Attributs d'entité suivie et les Valeurs d'attribut d'entité suivie comme des "attributs". Cependant, les attributs sont également des éléments distincts, liés aux métadonnées. Il est donc essentiel de séparer les attributs Tracker et les attributs de métadonnées. Dans l'API du Tracker, il est possible de référencer les attributs des métadonnées lors de la spécification du Schéma d'identification (voir les paramètres de requête pour plus d'informations).

Valeurs de données¶

Alors que les Attributs décrivent une entité suivie ou une inscription, les valeurs de données décrivent un évènement. La différence majeure est que les attributs ne peuvent avoir qu'une seule valeur pour une entité suivie donnée. En revanche, les valeurs de données peuvent avoir plusieurs valeurs différentes selon les événements - même si les événements appartiennent tous à la même inscription ou à la même entité suivie.

Remarque

Pour les éléments de données, seules les propriétés "élément de données" et "valeur" sont requises lors de l'ajout des données. Une "valeur" peut être nulle, et dans ce cas l'utilisateur doit la supprimer.

Notes Tracker¶

Le Tracker de DHIS2 permet de recueillir des données à l'aide d'éléments de données et d'attributs d'entités suivies. Cependant, il est parfois nécessaire d'enregistrer des informations supplémentaires ou des commentaires sur le sujet en question. Ces informations supplémentaires peuvent être saisies à l'aide de notes Tracker. Les notes Tracker correspondent aux commentaires sur les valeurs de données dans DHIS2 Agrégé.

Il existe deux types de notes Tracker : les notes enregistrées au niveau de l'événement et celles enregistrées au niveau de l'inscription. Une inscription peut comporter un ou plusieurs événements. Des commentaires sur chaque événement - par exemple, pourquoi un événement a été manqué, reprogrammé, ou pourquoi seuls quelques éléments de données ont été renseignés et ainsi de suite - peuvent être documentés à l'aide de notes d'événements. Chaque événement d'une inscription peut avoir son propre récit ou ses propres notes. Il est alors possible d'enregistrer, par exemple, une observation générale de ces événements à l'aide de la note d'inscription racine. Les notes d'inscription permettent également de documenter, par exemple, les raisons pour lesquelles une inscription est annulée. C'est à l'utilisateur de faire preuve d'imagination et de déterminer quand et comment utiliser les 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.

Les notes Tracker n'ont pas de point d'extrémité qui leur soit dédié. Elles sont échangées dans la charge utile de l'événement racine et/ou de l'inscription. Vous trouverez ci-dessous un exemple de charge utile.

{
  "trackedEntityInstance": "oi3PMIGYJH8",
  <entity_details>,
  ],
  "enrollments": [
    {
      "enrollment": "EbRsJr8LSSO",
      <enrollment_details>
      "notes": [
        {
          "note": "vxmCvYcPdaW",
          "value": "Enrollment note 2.",
        },
        {
          "value": "Enrollment note 1",
        }
      ],

      "events": [
        {
          "event": "zfzS9WeO0uM",
          <event_details>,
          "notes": [
            {
              "note": "MAQFb7fAggS",
              "value": "Event Note 1.",
            },
            {
              "value": "Event Note 2.",
            }
          ],
        },
        {
          ...
        }
      ]
    }
  ]
}

Utilisateur¶

L'uid ou le nom d'utilisateur doit être fourni. Si les deux sont fournis, seul le nom d’utilisateur est pris en compte.

Listes des tâches de l'étape de programme¶

La fonctionnalité "Listes des tâches de l'étape de programme" de l'application Saisie est conçue pour afficher des listes de tâches préétablies correspondant à une étape de programme spécifique. Cette fonctionnalité permet aux utilisateurs de sauvegarder des filtres et des préférences de tri liés aux étapes de programme, ce qui facilite l'organisation et la gestion de leur flux de travail. Pour interagir avec ces listes, vous devez utiliser la ressource /api/programStageWorkingLists. Ces listes peuvent être partagées et elles respectent le même modèle de partage que n'importe quelle autre métadonnée. Lors de l'utilisation de la ressource /api/sharing, le paramètre type sera programStageWorkingLists.

/api/40/programStageWorkingLists

Charge utile pour les opérations CRUD sur les listes de tâches des étapes de programme{ #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:

Tableau : Charge utile

Tableau : Critères de requête de l'étape de programme

Ci-dessous, un exemple de charge :

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

Importation Tracker (POST /api/tracker)¶

Le point d'extrémité POST /api/tracker permet aux clients d'importer les objets Tracker suivants dans DHIS2 :

• Entités suivies
• Inscriptions
• Événements
• Relations
• Données intégrées dans d'autres objets Tracker

Les principaux changements à noter par rapport aux autres points d'extrémité dédiés à l'importation Tracker sont :

1. La charge utile d'importation peut être imbriquée ou plate
2. L'appel peut être synchrone ou asynchrone
3. Importation de la charge utile des événements CSV

Paramètres de requête¶

Actuellement, le point d'extrémité de l'importation Tracker prend en charge les paramètres suivants :

REMARQUE : Le schéma d'identification (idScheme) et ses paramètres spécifiques aux métadonnées comme 'schéma d'unité d'organisation' (orgUnitIdScheme), 'schéma d'identification de programme' (programIdScheme), etc. permettaient d'autoriser et d'utiliser le paramètre par défaut AUTO. AUTO a été supprimé. UID est déjà le schéma d'identification par défaut. Toutes les requêtes envoyées avec le schéma d'identification AUTO se comporteront de la même manière qu'auparavant, c'est à dire que la correspondance sera faite en utilisant UID.

Charges utiles plates et imbriquées¶

L'importateur prend en charge les charges utiles plates et imbriquées. La principale différence réside dans la manière dont le client exige que ses données soient structurées.

Charge utile plate

La charge utile de type plate est simple. Elle peut contenir des collections pour chacun des principaux objets Tracker dont nous disposons. Cela fonctionne de manière transparente avec les données existantes, auxquelles des UID sont déjà attribués. Cependant, pour les nouvelles données, le client devra fournir de nouveaux UID pour toutes les références entre les objets. Par exemple, si vous importez une nouvelle entité suivie avec une nouvelle inscription, l'entité suivie demande au client de fournir un UID afin que l'inscription puisse être reliée à cet UID.

Charge utile imbriqué

Les charges utiles imbriquées sont la structure la plus couramment utilisée. Ici, les objets Tracker sont intégrés dans leur objet racine - par exemple, une inscription dans une entité suivie. L'avantage avec cette structure est que le client n'a pas besoin de fournir d'UID pour toutes ces connexions puisqu'il se verra attribuer la connexion au cours du processus d'importation, étant donné qu'elles sont imbriquées les unes aux autres.

REMARQUE

Même si les charges utiles imbriquées peuvent s'avérer plus simples à gérer pour les clients, elles seront toujours aplaties avant l'importation. Cela signifie que pour les importations volumineuses, le fait de fournir une charge utile plate permettra non seulement d'avoir plus de contrôle mais aussi moins de surcharge sur le processus d'importation.

Ci-dessous, des exemples de versions PLATES et IMBRIQUÉES de la charge utile. Les mêmes données sont utilisées dans les deux cas.

Charge utile PLATE¶

{
  "trackedEntities": [
    {
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "Q9GufDoplCL"
    }
  ],
  "enrollments": [
    {
      "orgUnit": "O6uvpzGd5pu",
      "program": "f1AyMswryyQ",
      "trackedEntity": "Kj6vYde4LHh",
      "enrollment": "MNWZ6hnuhSw",
      "trackedEntityType": "Q9GufDoplCL",
      "enrolledAt": "2019-08-19T00:00:00.000",
      "deleted": false,
      "occurredAt": "2019-08-19T00:00:00.000",
      "status": "ACTIVE",
      "notes": [],
      "attributes": [],
    }
  ],
  "events": [
    {
      "scheduledAt": "2019-08-19T13:59:13.688",
      "program": "f1AyMswryyQ",
      "event": "ZwwuwNp6gVd",
      "programStage": "nlXNK4b7LVr",
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "status": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "attributeCategoryOptions": "xYerKDKCefk",
      "deleted": false,
      "attributeOptionCombo": "HllvX50cXC0",
      "dataValues": [
        {
          "updatedAt": "2019-08-19T13:58:37.477",
          "storedBy": "admin",
          "dataElement": "BuZ5LGNfGEU",
          "value": "20",
          "providedElsewhere": false
        },
        {
          "updatedAt": "2019-08-19T13:58:40.031",
          "storedBy": "admin",
          "dataElement": "ZrqtjjveTFc",
          "value": "Male",
          "providedElsewhere": false
        },
        {
          "updatedAt": "2019-08-19T13:59:13.691",
          "storedBy": "admin",
          "dataElement": "mB2QHw1tU96",
          "value": "[-11.566044,9.477801]",
          "providedElsewhere": false
        }
      ],
      "notes": []
    },
    {
      "scheduledAt": "2019-08-19T13:59:13.688",
      "program": "f1AyMswryyQ",
      "event": "XwwuwNp6gVE",
      "programStage": "PaOOjwLVW23",
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "status": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "attributeCategoryOptions": "xYerKDKCefk",
      "deleted": false,
      "attributeOptionCombo": "HllvX50cXC0",
      "notes": []
    }
  ],
  "relationships": [
    {
      "relationshipType": "Udhj3bsdHeT",
      "from": {
        "trackedEntity": { "trackedEntity": "Kj6vYde4LHh" }
      },
      "to": {
        "trackedEntity": { "trackedEntity": "Gjaiu3ea38E" }
      }
    }
  ]
}

Charge utile IMBRIQUÉES¶

{
  "trackedEntities": [
    {
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "Q9GufDoplCL",
      "relationships": [
        {
          "relationshipType": "Udhj3bsdHeT",
          "from": {
            "trackedEntity": { "trackedEntity": "Kj6vYde4LHh" }
          },
          "to": {
            "trackedEntity": { "trackedEntity": "Gjaiu3ea38E" }
          }
        }
      ],
      "enrollments": [
        {
          "orgUnit": "O6uvpzGd5pu",
          "program": "f1AyMswryyQ",
          "trackedEntity": "Kj6vYde4LHh",
          "enrollment": "MNWZ6hnuhSw",
          "trackedEntityType": "Q9GufDoplCL",
          "enrolledAt": "2019-08-19T00:00:00.000",
          "deleted": false,
          "occurredAt": "2019-08-19T00:00:00.000",
          "status": "ACTIVE",
          "notes": [],
          "relationships": [],
          "attributes": [],
          "events": [
            {
              "scheduledAt": "2019-08-19T13:59:13.688",
              "program": "f1AyMswryyQ",
              "event": "ZwwuwNp6gVd",
              "programStage": "nlXNK4b7LVr",
              "orgUnit": "O6uvpzGd5pu",
              "trackedEntity": "Kj6vYde4LHh",
              "enrollment": "MNWZ6hnuhSw",
              "enrollmentStatus": "ACTIVE",
              "status": "ACTIVE",
              "occurredAt": "2019-08-01T00:00:00.000",
              "attributeCategoryOptions": "xYerKDKCefk",
              "deleted": false,
              "attributeOptionCombo": "HllvX50cXC0",
              "dataValues": [
                {
                  "updatedAt": "2019-08-19T13:58:37.477",
                  "storedBy": "admin",
                  "dataElement": "BuZ5LGNfGEU",
                  "value": "20",
                  "providedElsewhere": false
                },
                {
                  "updatedAt": "2019-08-19T13:58:40.031",
                  "storedBy": "admin",
                  "dataElement": "ZrqtjjveTFc",
                  "value": "Male",
                  "providedElsewhere": false
                },
                {
                  "updatedAt": "2019-08-19T13:59:13.691",
                  "storedBy": "admin",
                  "dataElement": "mB2QHw1tU96",
                  "value": "[-11.566044,9.477801]",
                  "providedElsewhere": false
                }
              ],
              "notes": [],
              "relationships": []
            },
            {
              "scheduledAt": "2019-08-19T13:59:13.688",
              "program": "f1AyMswryyQ",
              "event": "XwwuwNp6gVE",
              "programStage": "PaOOjwLVW23",
              "orgUnit": "O6uvpzGd5pu",
              "trackedEntity": "Kj6vYde4LHh",
              "enrollment": "MNWZ6hnuhSw",
              "enrollmentStatus": "ACTIVE",
              "status": "ACTIVE",
              "occurredAt": "2019-08-01T00:00:00.000",
              "attributeCategoryOptions": "xYerKDKCefk",
              "deleted": false,
              "attributeOptionCombo": "HllvX50cXC0",
              "notes": [],
              "relationships": []
            }
          ]
        }
      ]
    }
  ]
}

SYNC et ASYNC¶

Pour l'utilisateur, la principale différence entre une importation synchrone et une importation asynchrone est la réponse immédiate de l'API. Dans le cas d'une importation synchrone, la réponse sera renvoyée avec le récapitulatif de l'importation (importSummary) dès que l'importation sera terminée. En revanche, pour les importations asynchrones, la réponse sera immédiate et contiendra une référence à travers laquelle le client pourra demander des mises à jour de l'importation.

Dans le cadre des importations importantes, il peut être avantageux pour le client d'utiliser l'importation asynchrone afin de ne pas attendre trop longtemps une réponse.

Des exemples de réponse ASYNC sont présentés ci-dessous. Pour la réponse SYNC, consultez la section Récapitulatif d'importation.

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

Charge utile des événements CSV¶

Afin de maintenir la compatibilité avec les anciennes versions du Tracker, l'API permet d'importer des événements en utilisant le format CSV. Étant donné que ce format ne permet pas d'utiliser une liste comme champ, chaque ligne de la charge utile CSV représente un événement et une valeur de données. Ainsi, pour les événements comportant plusieurs valeurs de données, le fichier CSV comportera x lignes par événement où x est le nombre de valeurs de données dans cet événement. Les autres champs présentés sous forme de listes tels que comme relations et notes ne sont pas pris en charge. Pour importer un fichier CSV, le contenu de la requête doit être de type application/csv ou texte/csv.

*** Exemple de charge utile CSV ***¶

Récapitulatif des importations¶

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

Remarque

Ces points d'extrémité 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 points d'extrémité suivants afin de surveiller la progression de la tâche en fonction des journaux :

GET /tracker/jobs/{uid}

exemple de REQUÊTE¶

GET /tracker/jobs/mEfEaFSCKCC

Exemple de RÉPONSE¶

[
  {
    "uid": "mEfEaFSCKCC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:06.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) finished in 6.00000 sec. Import:Done",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:05.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) commit completed in 1.00000 sec. Import:commit",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:04.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) programruleValidation completed in 1.00000 sec. Import:programruleValidation",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:03.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) programrule completed in 1.00000 sec. Import:programrule",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:02.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) validation completed in 1.00000 sec. Import:validation",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:01.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) preheat completed in 1.00000 sec. Import:preheat",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:00.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) started by admin ( xE7jOejl9FI ) Import:Start",
    "completed": true,
    "id": "mEfEaFSCKCC"
  }
]

De plus, le point d'extrémité 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

exemple de REQUÊTE¶

GET /tracker/jobs/mEfEaFSCKCC/report

Exemple de RÉPONSE¶

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

Remarque

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

Structure du récapitulatif d'importation¶

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": "...",
  "validationReport": { },
  "stats": { },
  "timingsStats": { },
  "bundleReport": { },
  "message" : { }
}

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.

Rapport de validation

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

Le rapport contient un message et un code décrivant l'erreur (voir la section [codes d'erreur] (#error-codes) pour plus d'informations sur les erreurs). Il contient également le type de tracker et l'uid, lesquels permettent d'identifier l'emplacement de l'erreur dans les données. Dans ce cas, il y avait une ENTITÉ_SUIVIE avec l'uid Kj6vYde4LHh qui renvoyait à un type d'entité suivi qui n'a pas été trouvé.

Remarque

Les uid des objets trackers servent de noms à ces objets dans la charge utile. Par exemple, l'uid d'une entité suivie dans la charge utile 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 utile, 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 utile.

Les erreurs signalent des problèmes avec la charge utile 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

Les statistiques donnent un aperçu rapide de l'importation. Une fois l'importation terminée, ces statistiques indiqueront la quantité de données créées, mises à jour, supprimées ou ignorées.

Exemple:

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

updated fait référence au nombre d'objets mis à jour. Si un objet a un UID défini dans la charge utile, il sera considéré comme étant à jour tant que ce même UID se trouve dans la base de données.

deleted fait référence au nombre d'objets supprimés lors de l'importation. La suppression ne se produit que lorsque l'importation est configurée pour supprimer des données et uniquement lorsque les objets présents dans la charge utile ont des UID définis.

ignored fait référence aux objets qui n'ont pas été conservés. Les objets peuvent être ignorés pour plusieurs raisons, par exemple pour éviter de créer un objet qui existe déjà. Ignorer des objets ne pose pas de réel problème, car si un objet est ignoré, c'est parce que sa création n'était pas nécessaire ou cela lié à la configuration de l'importation.

timingStats (Statistiques de temps)

timingStats représente le temps consacré aux différentes étapes de l'importation. Ces statistiques n'informent pas sur le temps total exact de l'importation, mais plutôt sur le temps consacré aux différentes étapes dans le code.

Les timingStats servent principalement à déboguer les importations qui posent des problèmes afin de voir quelle partie de l'importation rencontre des problèmes.

{
  "timingsStats": {
    "timers": {
      "preheat": "0.234086 sec.",
      "preprocess": "0.000058 sec.",
      ...
      "totalImport": "0.236810 sec.",
      "validation": "0.001533 sec."
    }
  }
}

bundleRapport (Rapport d'ensemble)

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

Prenons en exemple l'ENTITÉ_SUIVIE :

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

message

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

Niveau du rapport récapitulatif de l'importation¶

Comme indiqué précédemment, GET /tracker/jobs/{uid}/report peut être récupéré à l'aide d'un paramètre reportMode spécifique. Par défaut, le point d'extrémité renverra un importSummary avec pour reportMode ERREUR.

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

Codes d'erreur¶

Il existe plusieurs codes d'erreur pour différents scénarios d'erreur. Le tableau suivant contient la liste des codes d'erreur générés par la nouvelle API du Tracker, ainsi que les messages d'erreur et quelques descriptions supplémentaires. Les espaces réservés dans les messages d'erreur ({0}, {1}, {2}..) sont généralement des uids, sauf indication contraire.

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¶

Chaque objet Tracker possède quelques propriétés qui doivent être présentes lors de l'importation des données. Pour obtenir une liste exhaustive des propriétés requises, consultez la [section sur les objets Tracker] (#webapi_nti_tracker_objects).

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¶

Toutes les données importées seront validées en fonction des métadonnées (Partage) et des unités d'organisation (Champs d'application des unités d'organisation) référencées dans les données. Vous pourrez trouver plus d’informations sur les champs d'application du partage et des unités d’organisation dans les sections suivantes.

Le partage est validé en même temps que la recherche des références dans la base de données. Les métadonnées auxquelles l'utilisateur n'a pas accès seront traitées comme si elles n'existaient pas. L'importation validera toutes les métadonnées référencées dans les données.

Les unités d'organisation, quant à elles, servent un double objectif. D'une part, elles permettent de s'assurer que les données ne soient importées que pour une unité d'organisation figurant dans le "champ de saisie" de l'utilisateur. D'autre part, elles sont également utilisées pour restreindre les programmes disponibles. Cela signifie que si vous essayez d'importer des données pour une unité d'organisation qui n'a pas accès au programme que vous importez, l'importation ne sera pas valide.

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.

Valeurs d'attribut et de données¶

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.

Les attributs et les valeurs de données obligatoires sont également vérifiés. Actuellement, la suppression des attributs obligatoires n'est pas autorisée. Dans certains cas d'utilisation, les valeurs doivent être envoyées séparément, tandis que dans d'autres, toutes les valeurs doivent être envoyées en une seule fois. Les programmes peuvent être configurés pour valider les attributs obligatoires ON_COMPLETE (complet) ou ON_UPDATE_AND_INSERT (mise à jour et insertion) pour s'adapter à ces cas d'utilisation.

Les attributs uniques sont validés au moment de l'importation. Cela signifie que tant que la valeur fournie est unique pour l'attribut et ce dans tout le système, l'importation sera acceptée. Cependant, si la valeur unique est utilisée par une autre entité suivie que celle qui est importée, l'importation échouera.

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 : - Type de fonctionnalité (pour la géométrie) - Événements attribuables à l'utilisateur - Autoriser les dates futures - Inscrire une fois - Et plus.

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

Règles de programme¶

Les utilisateurs peuvent configurer des Règles de programme, qui vont ajouter un fonctionnement conditionnel aux formulaires du Tracker. En plus d'exécuter ces règles dans les applications du Tracker, l'importateur du Tracker va également procéder à une sélection de ces règles. Puisque l'importateur exécute également ces règles, nous pouvons garantir un niveau de validation supplémentaire.

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.

Les règles de programme sont évaluées dans l'importateur de la même manière que dans les applications du Tracker. En résumé, les conditions suivantes sont prises en compte lors de l'application des règles de programme :

• 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.
• La condition de la règle de programme doit être évaluée comme étant vraie

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

• Les actions des règles de programme peuvent aboutir à 2 résultats différents : avertissements ou erreurs.
• Les erreurs feront échouer la validation, tandis que les avertissements seront rapportés sous forme de message dans le récapitulatif de l'importation.
  • Les actions SHOWWARNING (afficher l'avertissement) et WARNINGONCOMPLETION (avertissement à la fin) ne peuvent générer que des avertissements.
  • Les actions SHOWERROR (afficher l'erreur), ERRORONCOMPLETION (erreur à la fin), et SETMANDATORYFIELD (définir un champ obligatoire) ne peuvent générer que des erreurs.
  • L'action ASSIGN (attribuer) peut générer à la fois des avertissements et des erreurs.
  • 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é.
  • Lorsque l'action attribue une valeur à un attribut/élément de données qui a déjà une valeur et que la valeur à attribuer est différente, une erreur est générée à moins que le paramètre système RULE_ENGINE_ASSIGN_OVERWRITE soit défini sur "vrai".

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.

REMARQUE

Les règles de programme peuvent être ignorées lors de l'importation à l'aide du paramètre skipProgramRules (ignorer les règles de programme).

Effets secondaires¶

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 :

REMARQUE

Certaines configurations peuvent contrôler l'exécution des effets secondaires. La fonction skipSideEffects (ignorer les effets secondaires) peut être activée lors de l'importation pour ignorer complètement les effets secondaires. Par exemple, vous pouvez utiliser ce paramètre lors de l'importation d'un objet pour lequel vous ne voulez pas déclencher de notifications.

Assigner un utilisateur à des événements¶

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

Dans cet exemple, l'utilisateur avec l'uid M0fCOxtkURr sera assigné à l'événement avec l'uid ZwwuwNp6gVd. Un seul utilisateur peut être assigné à un événement.

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.

Exportation Tracker¶

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
• inscriptions
• relations

REMARQUE

• Tous ces points d'extrémité prennent actuellement en charge le format JSON. Le CSV n'est pris en charge que par les entités suivies et les événements.

Paramètres de requête courants¶

Le point d'extrémité suivant prend en charge les paramètres normalisés pour la pagination.

• Entités suivies GET /api/tracker/trackedEntities
• Évènements GET /api/tracker/events
• Inscriptions GET /api/tracker/enrollments
• Relations GET /api/tracker/relationships

Paramètres de requête pour la pagination¶

Attention

Sachez que les performances sont directement liées à la quantité de données qui fait l'objet de la requête. Le renvoi des pages plus volumineuses prendra plus de temps.

Paramètres de requête pour le mode de sélection des unités d'organisation{ #request-parameters-for-organisational-unit-selection-mode }¶

Les modes de sélection d'unités d'organisation disponibles sont expliqués dans le tableau suivant.

Paramètre de requête pour filtrer les réponses¶

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¶

Entités suivies (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}
• récupère une entité suivie en fonction de l'identifiant fourni

Point d'extrémité de la collection d'entités suivies 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.

Syntaxe 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 ouMode=ALL doit être spécifié.

• Un seul des paramètres program et trackedEntity peut être spécifié (zéro ou un).

• Si programStatus est spécifié, alors program doit également être spécifié.

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

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

GET /api/tracker/trackedEntities?orgUnit=DiszpKrYNg8

Pour effectuer une requête sur des instances à l'aide d'un attribut avec filtre et d'un attribut sans filtre, avec une unité d'organisation en utilisant le mode de requête de l'unité d'organisation subordonnée, utilisez ceci :

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &attribure=AMpUYgxuCaE&orgUnit=DiszpKrYNg8;yMCshbaVExv

Une requête pour les instances où les attributs sont inclus dans la réponse et où un attribut est utilisé comme filtre :

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &filter=AMpUYgxuCaE:LIKE:Road
    &orgUnit=DiszpKrYNg8

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

GET /api/tracker/trackedEntities?orgUnit=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?orgUnit=DiszpKrYNg8
    &program=ur1Edk5Oe2n
    &filter=lw1SqmMlnfh:EQ:/:/,//

Pour effectuer une requête sur un attribut en utilisant plusieurs valeurs dans un filtre IN :

GET /api/tracker/trackedEntities?orgUnit=DiszpKrYNg8
    &filter=dv3nChNSIxy:IN:Scott;Jimmy;Santiago

Pour limiter la réponse aux instances qui font partie d'un programme spécifique, vous pouvez inclure un paramètre de requête 'program' :

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS
    &program=ur1Edk5Oe2n

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

GET /api/tracker/trackedEntities?
    &orgUnit=O6uvpzGd5pu&program=ur1Edk5Oe2n
    &enrollmentEnrolledAfter=2013-01-01
    &enrollmentEnrolledBefore=2013-09-01

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

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &orgUnit=O6uvpzGd5pu
    &ouMode=DESCENDANTS
    &trackedEntity=cyl5vuJ5ETQ

Par défaut, les instances sont renvoyées dans des pages de taille 50. Pour modifier cela, vous pouvez utiliser les paramètres de requête 'page' et 'taille de page' (pageSize) :

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &orgUnit=O6uvpzGd5pu
    &ouMode=DESCENDANTS
    &page=2&pageSize=3

Vous pouvez utiliser une gamme d'opérateurs pour effectuer le filtrage :

Format de réponse¶

La réponse JSON peut ressembler à ceci :

Les réponses peuvent être filtrées en fonction des champs recherchés ; voir Paramètre de requête pour filtrer les réponses

{
  "instances": [
    {
      "trackedEntity": "IzHblRD2sDH",
      "trackedEntityType": "nEenWmSyUEp",
      "createdAt": "2014-03-26T15:40:36.669",
      "createdAtClient": "2014-03-26T15:40:36.669",
      "updatedAt": "2014-03-28T12:28:17.544",
      "orgUnit": "g8upMTyEZGZ",
      "inactive": false,
      "deleted": false,
      "relationships": [],
      "attributes": [
        {
          "attribute": "VqEFza8wbwA",
          "code": "MMD_PER_ADR1",
          "displayName": "Address",
          "createdAt": "2016-01-12T00:00:00.000",
          "updatedAt": "2016-01-12T00:00:00.000",
          "valueType": "TEXT",
          "value": "1061 Marconi St"
        },
        {
          "attribute": "RG7uGl4w5Jq",
          "code": "Longitude",
          "displayName": "Longitude",
          "createdAt": "2016-01-12T00:00:00.000",
          "updatedAt": "2016-01-12T00:00:00.000",
          "valueType": "TEXT",
          "value": "27.866613"
        },
        ...,
        ...,
      ],
      "enrollments": [],
      "programOwners": []
    }
  ],
  "page": 1,
  "total": 39,
  "pageSize": 1
}

Point d'extrémité d'objet unique d'entités suivies GET /api/tracker/trackedEntities/{uid}¶

Le but de ce point d'extrémité est de récupérer une entité suivie en se basant sur son UID.

Syntaxe de la requête¶

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

Exemples de requêtes¶

Une requête pour une instance d'entité suivie :

GET /api/tracker/trackedEntities/IzHblRD2sDH?program=ur1Edk5Oe2n&fields=*

Format de réponse¶

Ce point d'extrémité permet de renvoyer des sous-objets lorsque le paramètre de requête fields (champs) est transmis après que le format json soit demandé. Dans le cas du format csv, le paramètre de requête fields n'a pas d'effet et la réponse contiendra toujours les mêmes champs, qui sont : - trackedEntity (Identifiant) - trackedEntityType (identifiant) - createdAt (Date et heure) - createdAtClient (Date et heure) - updatedAt (Date et heure) - updatedAtClient (Date et heure) - orgUnit (Identifiant) - inactif (booléen) - supprimé (booléen) - potentialDuplicate (booléen) - géométrie (WKT, https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) - stockéBy (Chaîne) - createdBy (Nom d'utilisateur de l'utilisateur) - updatedBy (Nom d'utilisateur de l'utilisateur) - attributs (tout attribut valide répertorié dans une autre colonne)

Exemple de réponse json :

{
    "trackedEntity": "IzHblRD2sDH",
    "trackedEntityType": "nEenWmSyUEp",
    "createdAt": "2014-03-26T15:40:36.669",
    "updatedAt": "2014-03-28T12:28:17.544",
    "orgUnit": "g8upMTyEZGZ",
    "inactive": false,
    "deleted": false,
    "relationships": [],
    "attributes": [
        {
            "attribute": "w75KJ2mc4zz",
            "code": "MMD_PER_NAM",
            "displayName": "First name",
            "createdAt": "2016-01-12T09:10:26.986",
            "updatedAt": "2016-01-12T09:10:35.884",
            "valueType": "TEXT",
            "value": "Wegahta"
        },
        {
            "attribute": "zDhUuAYrxNC",
            "displayName": "Last name",
            "createdAt": "2016-01-12T09:10:26.986",
            "updatedAt": "2016-01-12T09:10:35.884",
            "valueType": "TEXT",
            "value": "Goytiom"
        }
    ],
    "enrollments": [
        {
            "enrollment": "uT5ZysTES7j",
            "createdAt": "2017-03-28T12:28:17.539",
            "createdAtClient": "2016-03-28T12:28:17.539",
            "updatedAt": "2017-03-28T12:28:17.544",
            "trackedEntity": "IzHblRD2sDH",
            "trackedEntityType": "nEenWmSyUEp",
            "program": "ur1Edk5Oe2n",
            "status": "ACTIVE",
            "orgUnit": "g8upMTyEZGZ",
            "orgUnitName": "Njandama MCHP",
            "enrolledAt": "2020-11-10T12:28:17.532",
            "occurredAt": "2020-10-12T12:28:17.532",
            "followUp": false,
            "deleted": false,
            "events": [
                {
                    "event": "ixDYEGrNQeH",
                    "status": "ACTIVE",
                    "program": "ur1Edk5Oe2n",
                    "programStage": "ZkbAXlQUYJG",
                    "enrollment": "uT5ZysTES7j",
                    "enrollmentStatus": "ACTIVE",
                    "trackedEntity": "IzHblRD2sDH",
                    "relationships": [],
                    "scheduledAt": "2019-10-12T12:28:17.532",
                    "followup": false,
                    "deleted": false,
                    "createdAt": "2017-03-28T12:28:17.542",
                    "createdAtClient": "2016-03-28T12:28:17.542",
                    "updatedAt": "2017-03-28T12:28:17.542",
                    "attributeOptionCombo": "HllvX50cXC0",
                    "attributeCategoryOptions": "xYerKDKCefk",
                    "dataValues": [],
                    "notes": []
                }
            ],
            "relationships": [],
            "attributes": [],
            "notes": []
        }
    ],
    "programOwners": [
        {
            "orgUnit": "g8upMTyEZGZ",
            "trackedEntity": "IzHblRD2sDH",
            "program": "ur1Edk5Oe2n"
        }
    ]
}

Événements (GET /api/tracker/events)¶

Deux points d'extrémité sont dédiés aux événements :

• GET /api/tracker/events
  • récupère les événements correspondant aux critères donnés
• GET /api/tracker/events/{id}
  • récupère un événement en fonction de l'identifiant fourni

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 attributeCC nor attributeCos, 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&ouMode=CHILDREN

La requête pour tous les événements contenant 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&ouMode=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 associés à un programme et à une unité d'organisation, ordonnés par date d'échéance en ordre croissant :

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

Requête pour les 10 événements avec la date d'événement la plus récente dans un programme et une unité d'organisation - par pagination et ordonnés par date d'échéance en ordre décroissant :

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

Requête pour tous les événements associées à un programme et à une unité d'organisation pour une instance d'entité suivie donnée :

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

La requête pour tous les événements associés à un programme et une unité d'organisation plus ancien(ne) ou égal(e) au 03/02/2014 :

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&endDate=2014-02-03

Requête pour tous les événements associés à une étape de programme, une unité d'organisation et une instance d'entité suivie de l'an 2014 :

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  &trackedEntityInstance=gfVxE3ALA9m&occurredAfter=2014-01-01&occurredBefore=2014-12-31

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=DiszpKrYNg8
    &program=lxAQ7Zs9VYR
    &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/events?orgUnit=DiszpKrYNg8
    &program=lxAQ7Zs9VYR
    &filter=lw1SqmMlnfh:EQ:/:/,//

Format de réponse¶

La réponse JSON peut ressembler à ceci :

{
    "instances": [
        {
            "event": "rgWr86qs0sI",
            "status": "ACTIVE",
            "program": "kla3mAPgvCH",
            "programStage": "aNLq9ZYoy9W",
            "orgUnit": "DiszpKrYNg8",
            "orgUnitName": "Ngelehun CHC",
            "relationships": [],
            "occurredAt": "2021-10-12T00:00:00.000",
            "followup": false,
            "deleted": false,
            "createdAt": "2018-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": []
        }
    ],
    "page": 1,
    "pageSize": 1
}

La réponse CSV peut ressembler à ceci :

|event|status|program|programStage|enrollment|orgUnit|occurredAt|scheduledAt|dataElement|value|storedBy|providedElsewhere
|---|---|---|---|---|---|---|---|---|---|---|---|
|V1CerIi3sdL|COMPLETED|IpHINAT79UW|A03MvHHogjR|CCBLMntFuzb|DiszpKrYNg8|2020-02-26T23:00:00Z|2020-02-27T23:00:00Z|a3kGcGDCuk6|11|admin|false
|V1CerIi3sdL|COMPLETED|IpHINAT79UW|A03MvHHogjR|CCBLMntFuzb|DiszpKrYNg8|2020-02-26T23:00:00Z|2020-02-27T23:00:00Z|mB2QHw1tU96|[-11.566044,9.477801]|admin|false

Point d'extrémité d'objet unique d'événements GET /api/tracker/events/{uid}¶

Le but de ce point d'extrémité est de récupérer un événement en se basant sur son UID.

Syntaxe de la requête¶

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

Exemples de requêtes¶

Une requête pour un événement :

GET /api/tracker/events/rgWr86qs0sI

Format de réponse¶

{
  "event": "rgWr86qs0sI",
  "status": "ACTIVE",
  "program": "kla3mAPgvCH",
  "programStage": "aNLq9ZYoy9W",
  "enrollment": "Lo3SHzCnMSm",
  "enrollmentStatus": "ACTIVE",
  "orgUnit": "DiszpKrYNg8",
  "orgUnitName": "Ngelehun CHC",
  "relationships": [],
  "occurredAt": "2021-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"
    },
    {
      "createdAt": "2015-10-20T12:09:19.514",
      "updatedAt": "2015-10-20T12:09:19.514",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "b6dOUjAarHD",
      "value": "213"
    },
    {
      "createdAt": "2015-10-20T12:09:19.626",
      "updatedAt": "2015-10-20T12:09:19.626",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "UwCXONyUtGs",
      "value": "3"
    },
    {
      "createdAt": "2015-10-20T12:09:19.542",
      "updatedAt": "2015-10-20T12:09:19.542",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "fqnXmRYo5Cz",
      "value": "123"
    },
    {
      "createdAt": "2015-10-20T12:09:19.614",
      "updatedAt": "2015-10-20T12:09:19.614",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "Qz3kfeKgLgL",
      "value": "23"
    },
    {
      "createdAt": "2015-10-20T12:09:19.528",
      "updatedAt": "2015-10-20T12:09:19.528",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "W7aC8jLASW8",
      "value": "12"
    },
    {
      "createdAt": "2015-10-20T12:09:19.599",
      "updatedAt": "2015-10-20T12:09:19.599",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "HrJmqlBqTFG",
      "value": "3"
    }
  ],
  "notes": []
}

Inscriptions (GET /api/tracker/enrollments)¶

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

• GET /api/tracker/enrollments
  • récupère les inscriptions correspondant aux critères donnés
• GET /api/tracker/enrollments/{id}
  • récupère une inscription en fonction de l'identifiant fourni

Point d'extrémité de la collecte d'inscriptions GET /api/tracker/enrollments¶

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

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

• Au moins une unité d'organisation doit être spécifiée avec le paramètre orgUnit (un ou plusieurs), ou ouMode=ALL doit être spécifié.

• Un seul des paramètres program et trackedEntity peut être spécifié (zéro ou un).

• Si programStatus est spécifié, alors program doit également être spécifié.

• Si followUp est spécifié, alors program doit également être spécifié.

• Si enrolledAfter ou enrolledBefore est spécifié, alors program doit également être spécifié.

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?orgUnit=DiszpKrYNg8

Pour limiter la réponse aux inscriptions qui font partie d'un programme spécifique, vous pouvez inclure un paramètre de requête de programme :

GET /api/tracker/enrollments?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

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

GET /api/tracker/enrollments?&orgUnit=O6uvpzGd5pu&program=ur1Edk5Oe2n
  &enrolledAfter=2013-01-01&enrolledBefore=2013-09-01

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?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS&trackedEntity=cyl5vuJ5ETQ

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

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

Format de réponse¶

La réponse JSON peut ressembler à ceci :

{
  "instances": [
    {
      "enrollment": "iKaBMOyq7QQ",
      "createdAt": "2017-03-28T12:28:19.812",
      "createdAtClient": "2016-03-28T12:28:19.812",
      "updatedAt": "2017-03-28T12:28:19.817",
      "trackedEntity": "PpqV8ytvW5i",
      "trackedEntityType": "nEenWmSyUEp",
      "program": "ur1Edk5Oe2n",
      "status": "ACTIVE",
      "orgUnit": "NnQpISrLYWZ",
      "orgUnitName": "Govt. Hosp. Bonthe",
      "enrolledAt": "2020-10-23T12:28:19.805",
      "occurredAt": "2020-10-07T12:28:19.805",
      "followUp": false,
      "deleted": false,
      "events": [],
      "relationships": [],
      "attributes": [],
      "notes": []
    }
  ],
  "page": 1,
  "total": 1,
  "pageSize": 5
}

Point d'extrémité d'objet unique d'inscriptions GET /api/tracker/enrollments/{uid}¶

Le but de ce point d'extrémité est de récupérer une inscription en se basant sur son UID.

Syntaxe de la requête¶

GET /api/tracker/enrollment/{uid}

Exemples de requêtes¶

Une requête pour une inscription :

GET /api/tracker/enrollments/iKaBMOyq7QQ

Format de réponse¶

{
  "enrollment": "iKaBMOyq7QQ",
  "createdAt": "2017-03-28T12:28:19.812",
  "createdAtClient": "2016-03-28T12:28:19.812",
  "updatedAt": "2017-03-28T12:28:19.817",
  "trackedEntity": "PpqV8ytvW5i",
  "trackedEntityType": "nEenWmSyUEp",
  "program": "ur1Edk5Oe2n",
  "status": "ACTIVE",
  "orgUnit": "NnQpISrLYWZ",
  "orgUnitName": "Govt. Hosp. Bonthe",
  "enrolledAt": "2020-10-23T12:28:19.805",
  "occurredAt": "2020-10-07T12:28:19.805",
  "followUp": false,
  "deleted": false,
  "events": [],
  "relationships": [],
  "attributes": [],
  "notes": []
}

Relations (GET /api/tracker/relationships)¶

Les relations sont des liens entre deux entités dans le Tracker. Ces entités peuvent être des instances d'entités suivies, des inscriptions et des événements.

Le but de ce point d'extrémité est de récupérer les relations entre les objets.

Contrairement aux autres points d'extrémité d'objets suivis, les relations n'exposent qu'un seul point d'extrémité :

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

Paramètres de requête¶

Les règles suivantes s'appliquent aux paramètres de requête.

• un seul paramètre parmi trackedEntity, enrollment et event peut être transmis

REMARQUE

L'utilisation des paramètres "tracked entity", "Enrollment" ou "Event" renverra toute relation à laquelle fait partie l'entité suivie, l'inscription ou l'événement (que ce soit 'à partir de' ou 'vers'), à condition que l'utilisateur y ait accès.

Exemple de réponse¶

{
  "instances": [
    {
      "relationship": "SSfIicJKbh5",
      "relationshipType": "Mv8R4MPcNcX",
      "from": {
        "trackedEntity": {
          "trackedEntity": "neR4cmMY22o"
        }
      },
      "to": {
        "trackedEntity": {
          "trackedEntity": "rEYUGH97Ssd"
        }
      }
    },
    {
      "relationship": "S9kZGYPKk3x",
      "relationshipType": "Mv8R4MPcNcX",
      "from": {
        "trackedEntity": {
          "trackedEntity": "neR4cmMY22o"
        }
      },
      "to": {
        "trackedEntity": {
          "trackedEntity": "k8TU70vWtnP"
        }
      }
    }
  ],
  "page": 1,
  "pageSize": 2
}

Contrôle de l'accès au Tracker¶

Le Tracker dispose de quelques concepts en ce qui concerne le contrôle d'accès, tels que le partage, les champs d'application des unités d'organisation, la propriété et les niveaux d'accès. Les sections suivantes fournissent une brève introduction aux différents sujets.

Partage de métadonnées¶

Le paramètre de partage est une fonctionnalité standard de DHIS2 qui s'applique aux métadonnées/données du Tracker et de l'Agrégé, ainsi qu'aux tableaux de bord et aux éléments de visualisation. Au cœur du partage se trouve la possibilité de définir qui peut voir/faire quoi. En général, il existe cinq configurations de partage possibles : aucun accès, lecture des métadonnées, écriture des métadonnées, lecture des données et écriture des données. Ces configurations d'accès peuvent être accordées au niveau de l'utilisateur et/ou du groupe d'utilisateurs (pour plus de flexibilité). En ce qui concerne le Tracker, les métadonnées suivantes et leur configuration de partage sont d'une importance particulière : Élément de données, option de catégorie, programme, étape de programme, type d'entité suivie, attribut d'entité suivie, ainsi que les tableaux de bord et les éléments de tableau de bord liés au Tracker.

Le fonctionnement des paramètres de partage est simple : les paramètres sont appliqués lors des processus d'importation/exportation des données Tracker. Pour lire des valeurs, il faut disposer d'un accès en lecture aux données. Un utilisateur qui souhaite modifier des données doit disposer d'un accès en écriture. De même, un utilisateur qui souhaite modifier des métadonnées doit disposer d'un accès en écriture aux métadonnées.

Un point essentiel concernant les données Tracker est la nécessité d'adopter une approche holistique. Par exemple, un utilisateur ne pourra pas voir la valeur de l'élément de données s'il n'a accès qu'à l'élément de données en lecture. L'utilisateur doit disposer d'un accès en lecture aux données pour accéder au stade du programme parent et au programme auquel l'élément de données appartient. Il en va de même pour la combinaison d'options de catégorie. Dans Tracker, l'événement est lié à AttributeOptionCombo, qui se compose d'une combinaison d'options de catégorie. Par conséquent, pour qu'un utilisateur puisse lire les données d'un événement, il doit avoir un accès en lecture à toutes les options de catégorie et aux catégories correspondantes qui constituent la combinaison d'options d'attributs de l'événement en question. Si un utilisateur n'a pas accès à une seule option de catégorie ou à une seule catégorie, il n'a pas accès à l'ensemble de l'événement.

Lorsqu'il s'agit d'accéder aux données d'inscription, il est essentiel d'avoir d'abord accès à l'entité suivie. L'accès à une entité suivie est contrôlé par le partage des paramètres du programme, du type d'entité suivie et de l'attribut d'entité suivie. Une fois que l'on a accédé à l'inscription, il est possible d'accéder aux données d'événement, là encore en fonction de l'étape du programme et des paramètres de partage des éléments de données.

Un autre point essentiel à prendre en considération est la manière de définir l'accès aux différentes étapes d'un programme. Il peut arriver que nous devions accorder l'accès à une étape spécifique - par exemple, « Résultat de laboratoire » - à un groupe d'utilisateurs spécifique (techniciens de laboratoire). Dans ce cas, nous pouvons accorder un accès en écriture aux données de l'étape « Résultat du laboratoire », probablement un accès en lecture à une ou plusieurs étapes au cas où nous voudrions que les techniciens de laboratoire lisent d'autres résultats médicaux, ou aucun accès si nous pensons qu'il n'est pas nécessaire qu'ils consultent des données autres que celles relatives au laboratoire.

En résumé, DHIS2 dispose d'un paramètre de partage très précis que nous pouvons utiliser pour implémenter les mécanismes de contrôle d'accès au niveau des données et des métadonnées. Ces paramètres de partage peuvent être appliqués directement au niveau de l'utilisateur ou du groupe d'utilisateurs. Le paramètre de partage à appliquer dépend du cas d'utilisation.

Pour plus d'informations sur le partage de données, consultez Partage de données.

Champs d'application des unités d'organisation¶

Les unités d'organisation font partie des objets les plus fondamentaux de DHIS2. Elles définissent un univers dans lequel un utilisateur est autorisé à enregistrer et/ou à lire des données. Trois types d'unités d'organisation peuvent être attribués à un utilisateur. Il s'agit de la saisie de données, de la consultation de données et de la recherche Tracker. Comme leur nom l'indique, ces unités d'organisation définissent un champ d'application dans lequel un utilisateur est autorisé à effectuer les opérations requises.

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

Les utilisateurs peuvent affiner un champ d'application en transmettant une valeur spécifique de ouMode (mode d'unité d'organisation) dans leur requête API :

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

Actuellement, six modes de sélection sont disponibles : SÉLECTIONNÉ, SUBORDONNÉES, DESCENDANTS, SAISIE, ACCESSIBLE et TOUS.

1. SÉLECTIONNÉ : comme son nom l'indique, toutes les opérations prévues par l'API qui fait la requête se limitent à l'unité d'organisation sélectionnée.
2. CHILDREN: under this mode, the organisation unit scope will be constructed using the selected organisation unit and its immediate children.
3. DESCENDANTS : ici, il s'agit de l'unité d'organisation sélectionnée et toutes les unités qui se trouvent en dessous de celle-ci, pas seulement les subordonnés immédiats.
4. SAISIE : comme le nom l'indique, il s'agit ici des unités d'organisation destinées à la saisie des données. Il convient de noter que, parmi les trois unités d'organisation pouvant être attribuées à un utilisateur, celle de la saisie de données est obligatoire. Si un utilisateur ne dispose pas d'unités d'organisation pour la visualisation des données et pour la recherche Tracker, le système reviendra à la saisie des données. De cette manière, nous sommes toujours sûrs que l'utilisateur possède au moins un univers.
5. ACCESSIBLE : techniquement, il s'agit du même champ d'application que les unités d'organisation de recherche Tracker dont dispose l'utilisateur.
6. TOUS : "TOUS" s'applique parfaitement aux superutilisateurs. Pour ces derniers, ce champ d'application désigne toutes les unités d’organisation disponibles dans le système. Cependant, pour les non-superutilisateurs, TOUS se limite aux unités d'organisation ACCESSIBLES.

Il n'est pas judicieux de transmettre ces modes lors des opérations d'importation du Tracker. En effet, lors de l'écriture des données Tracker, chaque objet doit être rattaché à une unité d'organisation spécifique. Le système vérifiera alors si chacune des unités d'organisation mentionnées relève du champ d'application de la SAISIE. Si ce n'est pas le cas, le système rejettera simplement l'opération d'écriture.

Note that there is 4 type of organisation unit associations relevant for Tracker objects. A TrackedEntity has an organisation unit, commonly referred to as the Registration Organisation unit. Enrollments have an organisation unit associated with them. Events also have an organisation unit associated with them. There is also an Owner organisation unit for a TrackedEntity-Program combination.

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

For example, when retrieving TrackedEntities without the context of a program, the organisation unit scope is applied to the registration organisation unit of the TrackedEntity. Whereas, when retrieving TrackedEntities, including specific program data, the organisation unit scope is applied to the Owner organisation unit.

• Explique leur lien avec la propriété - Lien vers la propriété du programme

Propriété du programme Tracker¶

A new concept called Tracker Ownership is introduced from 2.30. This introduces a new organisation unit association for a TrackedEntity - Program combination. We call this the Owner (or Owning) Organisation unit of a TrackedEntity in the context of a Program. The Owner organisation unit is used to decide access privileges when reading and writing tracker data related to a program. This, along with the Program's Access Level configuration, decides the access behavior for Program-related data (Enrollments and Events). A user can access a TrackedEntity's Program data if the corresponding Owner OrganisationUnit for that TrackedEntity-Program combination falls under the user's organisation unit scope (Search/Capture). For Programs that are configured with access level OPEN or AUDITED , the Owner OrganisationUnit has to be in the user's search scope. For Programs that are configured with access level PROTECTED or CLOSED , the Owner OrganisationUnit has to be in the user's capture scope to be able to access the corresponding program data for the specific tracked entity.

When requesting tracked entities without specifying a program, the response will include only tracked entities that satisfy metadata sharing settings and one of the following criteria: - The tracked entity is enrolled in at least one program the user has data access to, and the user has access to the owner organisation unit. - The tracked entity is not enrolled in any program the user has data access to, but the user has access to the tracked entity registering organisation unit.

Tracker Ownership Override: Break the Glass¶

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

This act of temporarily gaining access is termed breaking the glass. Currently, temporary access is granted for 3 hours. DHIS2 audits breaking the glass along with the reason specified by the user. It is not possible to gain temporary access to a program that has been configured with an access level of CLOSED.

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

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

Transfert de la propriété du Tracker¶

Il est possible de transférer la propriété d'une combinaison Entité suivie - Programme d'une unité d'organisation à une autre. Cela peut s'avérer utile en cas de transfert de patients ou de migration. Seul un utilisateur disposant d'un accès à la propriété (ou d'un accès temporaire en brisant la glace) peut transférer la propriété. Pour transférer la propriété d'une combinaison Entité suivie - Programme à une autre unité d'organisation, la requête "PUT" suivante peut être utilisée :

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

Niveau d'accès¶

DHIS2 traite les données Tracker avec un niveau de protection supplémentaire. En plus de la protection standard des métadonnées et des données via les paramètres de partage, les données Tracker sont protégées par des mécanismes supplémentaires en matière de niveau d'accès. Actuellement, quatre niveaux d'accès peuvent être configurés pour un programme : Ouvert, Audité, Protégé et Fermé.

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

1. Open: This access level is the least restricted among the access levels. Data inside an OPEN program can be accessed and modified by users if the Owner organisation unit falls under the user's search scope. With this access level, accessing and modifying data outside the capture scope is possible without any justification or consequence.
2. Audité : Il s'agit du même niveau d'accès que le niveau Ouvert. La différence est que le système ajoutera automatiquement une entrée dans le journal d'audit sur les données auxquelles l'utilisateur accède.
3. Protected: This access level is slightly more restricted. Data inside a PROTECTED program can only be accessed by users if the Owner organisation unit falls under the user's capture scope. However, a user who only has the Owner organisation unit in the search scope can gain temporary ownership by breaking the glass. The user has to provide a justification of why they are accessing the data at hand. The system will then put a log of both the justification and access audit and provide temporary access for 3 hours to the user. Note that when breaking the glass, the Owner Organisation Unit remains unchanged, and only the user who has broken the glass gains temporary access.
4. Fermé : Il s'agit du niveau d'accès le plus restreint. Les données enregistrées pour le compte de programmes configurés avec le niveau d'accès FERMÉ ne seront pas accessibles si l'unité d'organisation propriétaire n'est pas dans le champ de saisie de l'utilisateur. Il est également impossible de briser la vitre ou d'obtenir une propriété temporaire dans cette configuration. Notez qu'il est toujours possible de transférer la propriété à une autre unité d'organisation. Seul un utilisateur ayant accès à ces données peut transférer la propriété d'une combinaison Entité Suivie - Programme à une autre unité d'organisation. Si la propriété est transférée, l'unité d'organisation propriétaire est mise à jour.