Tracker (API obsolètes)¶

Attention

Le Tracker a été réimplémenté dans DHIS2 2.36. Les nouveaux points d'extrémité sont documentés à l'adresse suivante Tracker.

Les points d'extrémité

• GET/POST/PUT/DELETE /api/trackedEntityInstance
• GET/POST/PUT/DELETE /api/enrollments
• GET/POST/PUT/DELETE /api/events
• GET/POST/PUT/DELETE /api/relationships

seront supprimés dans la version 42 !

• Si vous prévoyez d'utiliser les points d'extrémité du Tracker, utilisez les nouveaux points d'extrémité décrits dans Tracker
• Si vous utilisez encore les points d'extrémité obsolètes du Tracker dans la production, veuillez migrer vers les nouveaux points d'extrémité . La page Migration vers les nouveaux points d'extrémité du Tracker devrait vous aider > à commencer le processus. Contactez la [communauté de pratique] (https://community.dhis2.org) si vous avez besoin d'aide supplémentaire. .

Migration vers de nouveaux points d'extrémité du Tracker¶

Les sections suivantes montrent les principales différences entre les points d'extrémité obsolètes

• GET/POST/PUT/DELETE /api/trackedEntityInstance
• GET/POST/PUT/DELETE /api/enrollments
• GET/POST/PUT/DELETE /api/events
• GET/POST/PUT/DELETE /api/relationships

et ceux introduits nouvellement.

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

Noms de propriétés¶

Les noms des propriétés d'API ont été modifiés afin qu'ils soient cohérents pour tous les points d'extrémité. Le tableau suivant énumère les anciens et les nouveaux noms de propriétés.

Remarque

La propriété assignedUser (utilisateur assigné) était auparavant une chaîne de caractères et est maintenant un objet de la forme suivante (type utilisateur) :

{
"assignedUser" : {
"uid" : "ABCDEF12345",
"username" : "username",
"firstName" : "John",
"nom de famille" : "Doe"
}
}

Point-virgule comme séparateur pour les identifiants (UID)¶

Les champs ou les paramètres de requête acceptant plusieurs valeurs, comme les UID, sont désormais séparés par une virgule au lieu d'un point-virgule. Cela permet de s'assurer que les UID soient systématiquement séparés par une virgule dans tous les points d'extrémité de DHIS2.

Les champs suivants sont concernés

• event.attributeCategoryOptions (ainsi qu'un événement renvoyé dans le cadre d'une relation from/to)

Journal des modifications (changelog) de l'importation Tracker (POST)¶

Les précédents points d'extrémité de l'importation Tracker

• POST/PUT/DELETE /api/trackedEntityInstance
• POST/PUT/DELETE /api/enrollments
• POST/PUT/DELETE /api/events
• POST/PUT/DELETE /api/relationships

sont remplacés par le nouveau point d'extrémité

• POST /api/tracker

[Importation Tracker] (https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker.html#webapi_nti_import) décrit comment utiliser ce nouveau point d'extrémité.

Journal des modifications de l'exportation Tracker (GET)¶

En plus des noms modifiés indiqués dans Noms de propriétés, certains paramètres de requête ont également été modifiés.

Les tableaux suivants énumèrent les différences entre les anciens et les nouveaux paramètres de requête pour les points d'extrémité GET.

Modifications apportées aux paramètres de requête pour GET /api/tracker/trackedEntities¶

Modifications apportées aux paramètres de requête pour GET /api/tracker/enrollments¶

Modifications apportées aux paramètres de requête pour GET /api/tracker/events¶

Modifications apportées aux paramètres de requête pour GET /api/tracker/relationships¶

API Web du Tracker¶

L'API Web du Tracker est constitué de 3 points d'extrémité qui ont un support CRUD complet (créer, lire, mettre à jour, supprimer). Les 3 points d'extrémité sont /api/trackedEntityInstances, /api/enrollments et /api/events et ils prennent en charge les instances d'entités suivies, les inscriptions et les événements.

Gestion des instances d'entités suivies¶

Les instances d'entités suivies bénéficient d'une prise en charge CRUD complète dans l'API. Avec l'API d'inscription, la plupart des opérations nécessaires pour travailler avec les instances d'entités suivies et les programmes sont prises en charge.

/api/33/trackedEntityInstances

Création d'une nouvelle instance d'entité suivie¶

Pour créer une nouvelle personne dans le système, vous devez utiliser la ressource trackedEntityInstances (instances d'entités suivies). Un modèle de charge est présenté ci-dessous :

{
  "trackedEntity": "tracked-entity-id",
  "orgUnit": "org-unit-id",
  "geometry": "<Geo JSON>",
  "attributes": [{
    "attribute": "attribute-id",
    "value": "attribute-value"
  }]
}

Le champ "geometry" accepte un objet GeoJson, dont le type doit correspondre au featureType (type de fonctionnalité) du TrackedEntityType (type d'entité suivie). Voici un exemple d'objet GeoJson :

{
  "type": "Point",
  "coordinates": [1, 1]
}

Le champ "coordinates" a été introduit dans la version 2.29 et accepte comme valeur une coordonnée ou un polygone.

Pour obtenir les ID de relationship et attributes, vous pouvez consulter respectivement les ressources relationshipTypes et trackedEntityAttributes. Pour créer une instance d'entité suivie, vous devez utiliser la méthode HTTP POST. Vous pouvez envoyer la charge à l'URL suivante :

/api/trackedEntityInstances

Par exemple, créons une nouvelle instance pour une entité suivie de personne et spécifions ses attributs 'prénom' et 'nom' :

{
  "trackedEntity": "nEenWmSyUEp",
  "orgUnit": "DiszpKrYNg8",
  "attributes": [
    {
      "attribute": "w75KJ2mc4zz",
      "value": "Joe"
    },
    {
      "attribute": "zDhUuAYrxNC",
      "value": "Smith"
    }
  ]
}

Pour envoyer ces données au serveur, vous pouvez utiliser la commande cURL comme suit :

curl -d @tei.json "https://play.dhis2.org/demo/api/trackedEntityInstances" -X POST
  -H "Content-Type: application/json" -u admin:district

Pour créer plusieurs instances à l'aide d'une seule requête, vous pouvez envelopper la charge dans un tableau extérieur comme ceci et effectuer une requête POST à la même ressource comme ci-dessus :

{
  "trackedEntityInstances": [
    {
      "trackedEntity": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "value": "Joe"
        },
        {
          "attribute": "zDhUuAYrxNC",
          "value": "Smith"
        }
      ]
    },
    {
      "trackedEntity": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "value": "Jennifer"
        },
        {
          "attribute": "zDhUuAYrxNC",
          "value": "Johnson"
        }
      ]
    }
  ]
}

Le système ne permet pas la création d'une instance d'entité suivie (ainsi que l'inscription et l'événement) avec un UID déjà utilisé dans le système. Cela signifie que les UID ne peuvent pas être réutilisés.

Mise à jour d'une instance d'entité suivie¶

Pour la mise à jour d'une instance d'entité suivie, la charge est identique à celle de la section précédente. La différence est que vous devez utiliser la méthode HTTP PUT pour la requête lors de l'envoi de la charge. Vous devrez également ajouter l'identifiant de la personne à la ressource trackedEntityInstances dans l'URL comme suit, où <tracked-entity-instance-identifier> doit être remplacé par l'identifiant de l'instance d'entité suivie :

/api/trackedEntityInstances/<tracked-entity-instance-id>

La charge doit contenir tous les attributs et relations, même ceux qui n'ont pas été modifiés. Les attributs ou les relations qui étaient présents auparavant et qui ne sont plus présents dans la charge actuelle seront supprimés du système. Cela signifie que si des attributs/relations sont vides dans la charge actuelle, tous les attributs/relations existants seront supprimés du système. Depuis la version 2.31, il est possible d'ignorer les attributs/relations vides dans la charge en cours d'utilisation. Vous pouvez définir le paramètre de requête ignoreEmptyCollection sur true si vous ne voulez pas envoyer des attributs ou des relations et que vous ne voulez pas non plus qu'ils soient supprimés du système.

Il n'est pas autorisé de mettre à jour une instance d'entité suivie déjà supprimée. Il n'est pas non plus autorisé de marquer une instance d'entité suivie comme supprimée via une requête de mise à jour. Les mêmes règles s'appliquent aux inscriptions et aux événements.

Suppression d'une instance d'entité suivie¶

Pour supprimer une instance d'entité suivie, envoyez une requête à l'URL qui identifie cette instance d'entité suivie avec la méthode DELETE. L'URL est la même que celle utilisée plus haut pour la mise à jour.

Création et inscription des instances d'entités suivies¶

Il est également possible de créer (et de mettre à jour) une instance d'entité suivie et de l'inscrire en même temps à un programme.

{
  "trackedEntity": "tracked-entity-id",
  "orgUnit": "org-unit-id",
  "attributes": [{
    "attribute": "attribute-id",
    "value": "attribute-value"
  }],
  "enrollments": [{
    "orgUnit": "org-unit-id",
    "program": "program-id",
    "enrollmentDate": "2013-09-17",
    "incidentDate": "2013-09-17"
   }, {
    "orgUnit": "org-unit-id",
    "program": "program-id",
    "enrollmentDate": "2013-09-17",
    "incidentDate": "2013-09-17"
   }]
}

Vous l'enverrez au serveur comme vous le feriez normalement lors de la création ou de la mise à jour d'une nouvelle instance d'entité suivie.

curl -X POST -d @tei.json -H "Content-Type: application/json"
  -u user:pass "http://server/api/33/trackedEntityInstances"

Exemple complet de charge comprenant : l'instance d'entité suivie, l'inscription et l'événement.¶

Il est également possible de créer (et de mettre à jour) une instance d'entité suivie, de l'inscrire en même temps à un programme et de créer un événement.

{
  "trackedEntityType": "nEenWmSyUEp",
  "orgUnit": "DiszpKrYNg8",
  "attributes": [
    {
      "attribute": "w75KJ2mc4zz",
      "value": "Joe"
    },
    {
      "attribute": "zDhUuAYrxNC",
      "value": "Rufus"
    },
    {
     "attribute":"cejWyOfXge6",
     "value":"Male"
    }
  ],
  "enrollments":[
    {
      "orgUnit":"DiszpKrYNg8",
      "program":"ur1Edk5Oe2n",
      "enrollmentDate":"2017-09-15",
      "incidentDate":"2017-09-15",
      "events":[
        {
          "program":"ur1Edk5Oe2n",
          "orgUnit":"DiszpKrYNg8",
          "eventDate":"2017-10-17",
          "status":"COMPLETED",
          "storedBy":"admin",
          "programStage":"EPEcjy3FWmI",
          "coordinate": {
            "latitude":"59.8",
            "longitude":"10.9"
          },
          "dataValues": [
            {
              "dataElement":"qrur9Dvnyt5",
              "value":"22"
            },
            {
              "dataElement":"oZg33kd9taw",
              "value":"Male"
            }
         ]
      },
      {
         "program":"ur1Edk5Oe2n",
         "orgUnit":"DiszpKrYNg8",
         "eventDate":"2017-10-17",
         "status":"COMPLETED",
         "storedBy":"admin",
         "programStage":"EPEcjy3FWmI",
         "coordinate": {
           "latitude":"59.8",
           "longitude":"10.9"
         },
         "dataValues":[
           {
             "dataElement":"qrur9Dvnyt5",
             "value":"26"
           },
           {
             "dataElement":"oZg33kd9taw",
             "value":"Female"
           }
         ]
       }
     ]
    }
  ]  
}

Vous l'enverrez au serveur comme vous le feriez normalement lors de la création ou de la mise à jour d'une nouvelle instance d'entité suivie.

curl -X POST -d @tei.json -H "Content-Type: application/json"
  -u user:pass "http://server/api/33/trackedEntityInstances"

Attributs d'instances d'entités suivies générés¶

Les attributs d'instances d'entités suivies dont les valeurs uniques sont générées automatiquement ont trois points d'extrémité qui sont utilisés par les applications. Ces points d'extrémité sont tous utilisés pour générer et réserver des valeurs.

Dans la version 2.29, nous avons introduit TextPattern pour définir et générer ces modèles. Tous les modèles existants seront convertis en modèles TextPattern valides lors de la mise à jour vers la version 2.29.

Remarque

À partir de la version 2.29, tous ces points d'extrémité vous demanderont d'inclure toutes les variables rapportées par le point d'extrémité requiredValues et qui sont listées comme obligatoires. Les modèles existants, composés uniquement de #, seront mis à jour vers la nouvelle syntaxe TextPattern RANDOM(<old-pattern>). Le > segment RANDOM du TextPattern n'est pas une variable obligatoire, donc ce > point d'extrémité fonctionnera comme auparavant pour les modèles définis avant la version 2.29.

Recherche des valeurs obligatoires¶

Un TextPattern peut contenir des variables qui changent en fonction de différents facteurs. Certains de ces facteurs sont inconnus du serveur. De ce fait, des valeurs doivent être fournies pour ces variables lorsque l'on veut générer et réserver des valeurs.

Cet point d'extrémité va renvoyer un plan de valeurs obligatoires et optionnelles, que le serveur va intégrer dans le TextPattern lorsqu'il génère de nouvelles valeurs. Les variables obligatoires doivent être fournies pour la génération, mais les variables optionnelles ne doivent être fournies que si vous savez ce que vous faites.

GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/requiredValues

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

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

Les applications web en ligne et les autres clients qui souhaitent générer une valeur qui sera utilisée immédiatement peuvent utiliser le point d'extrémité de génération. Ce point d'extrémité génère une valeur dont l'unicité est garantie au moment de la génération. La valeur ne sera pas non plus réservée. Depuis la version 2.29, ce point d'extrémité réserve également la valeur générée pendant 3 jours.

Si votre TextPattern comprend des valeurs obligatoires, vous pouvez les utiliser comme paramètres dans l'exemple ci-dessous :

Le délai d'expiration peut également être modifié au moment de la génération, en ajoutant ?expiration=<number-of-days> à la requête.

GET /api/33/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¶

Le point d'extrémité de génération et de réservation est utilisé par les clients hors ligne qui ont besoin d'enregistrer des entités suivies avec des identifiants uniques. Ils réservent un certain nombre d'identifiants uniques que ce dispositif utilisera ensuite lors de l'enregistrement de nouvelles instances d'entités suivies. Une requête est envoyée à ce point d'extrémité afin de récupérer un certain nombre de valeurs réservées pour les instances d'entités suivies. Un paramètre facultatif, "numberToReserve", indique le nombre d'identifiants à générer (par défaut, ce paramètre est défini sur 1).

Si votre TextPattern comprend des valeurs obligatoires, vous pouvez les utiliser comme paramètres dans l'exemple ci-dessous :

Comme pour le point d'extrémité de génération, ce point d'extrémité peut également spécifier le délai d'expiration de la même manière. En ajoutant ?expiration=<number-of-days>, vous pouvez remplacer le délai par défaut qui est de 60 jours.

GET /api/33/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é.

Attributs d'image¶

Travailler avec les attributs d'image ressemble beaucoup à travailler avec les valeurs de données de fichier. La valeur d'un attribut de type image est l'identifiant de la ressource de fichier associée. Une requête GET au point d'extrémité /api/trackedEntityInstances/<entityId>/<attributeId>/image renverra l'image proprement dite. Les paramètres facultatifs height (hauteur) et width (largeur) peuvent être utilisés pour spécifier les dimensions de l'image.

curl "http://server/api/33/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/image?height=200&width=200"
  > image.jpg

L'API prend également en charge un paramètre dimension. Celui-ci peut accepter trois types de valeurs (les lettres majuscules sont importantes) : PETITE (254x254), MOYENNE (512x512), GRANDE (1024x1024) ou ORIGINALE. Les attributs de type image seront stockés dans des tailles pré-générées et seront fournis par requête en fonction de la valeur du paramètre dimension.

curl "http://server/api/33/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/image?dimension=MEDIUM"

Attributs de fichier¶

Travailler avec les attributs de fichier ressemble beaucoup à travailler avec les valeurs de données d'image. La valeur d'un attribut de type fichier est l'identifiant de la ressource de fichier associée. Une requête GET à l'adresse /api/trackedEntityInstances/<entityId>/<attributeId>/file renvoie le contenu du fichier.

curl "http://server/api/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/file

Requête pour des instances d'entités suivies¶

Pour rechercher des instances d'entités suivies, vous pouvez interagir avec la ressource /api/trackedEntityInstances.

/api/33/trackedEntityInstances

Syntaxe de la requête¶

Tableau : Paramètres de requête pour les instances d'entités suivies

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

Tableau : Modes de sélection des unités d'organisation

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 à l'aide de l'attribut ou. (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 programStartDate ou programEndDate 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.

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

/api/33/trackedEntityInstances.json?ou=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 :

/api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A
  &filter=AMpUYgxuCaE&ou=DiszpKrYNg8;yMCshbaVExv

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

/api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A
  &filter=AMpUYgxuCaE:LIKE:Road&ou=DiszpKrYNg8

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

api/33/trackedEntityInstances.json?ou=DiszpKrYNg8&program=ur1Edk5Oe2n
  &filter=lw1SqmMlnfh:GT:150:LT:190

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

api/33/trackedEntityInstances.json?ou=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' :

api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu
  &ouMode=DESCENDANTS&program=ur1Edk5Oe2n

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

api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu
  &program=ur1Edk5Oe2n&programStartDate=2013-01-01&programEndDate=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 :

api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&ou=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) :

api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu
  &ouMode=DESCENDANTS&page=2&pageSize=3

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

Tableau : Opérateurs de filtre

Format de la réponse¶

Cette ressource prend en charge les représentations JSON, JSONP, XLS et CSV.

• json (application/json)

• jsonp (application/javascript)

• xml (application/xml)

La réponse en JSON/XML est au format objet et peut ressembler à ce qui suit. Le filtrage des champs est possible, donc si vous voulez un affichage complet, vous pouvez ajouter fields=* à la requête :

{
  "trackedEntityInstances": [
    {
      "lastUpdated": "2014-03-28 12:27:52.399",
      "trackedEntity": "cyl5vuJ5ETQ",
      "created": "2014-03-26 15:40:19.997",
      "orgUnit": "ueuQlqb8ccl",
      "trackedEntityInstance": "tphfdyIiVL6",
      "relationships": [],
      "attributes": [
        {
          "displayName": "Address",
          "attribute": "AMpUYgxuCaE",
          "type": "string",
          "value": "2033 Akasia St"
        },
        {
          "displayName": "TB number",
          "attribute": "ruQQnf6rswq",
          "type": "string",
          "value": "1Z 989 408 56 9356 521 9"
        },
        {
          "displayName": "Weight in kg",
          "attribute": "OvY4VVhSDeJ",
          "type": "number",
          "value": "68.1"
        },
        {
          "displayName": "Email",
          "attribute": "NDXw0cluzSw",
          "type": "string",
          "value": "LiyaEfrem@armyspy.com"
        },
        {
          "displayName": "Gender",
          "attribute": "cejWyOfXge6",
          "type": "optionSet",
          "value": "Female"
        },
        {
          "displayName": "Phone number",
          "attribute": "P2cwLGskgxn",
          "type": "phoneNumber",
          "value": "085 813 9447"
        },
        {
          "displayName": "First name",
          "attribute": "dv3nChNSIxy",
          "type": "string",
          "value": "Liya"
        },
        {
          "displayName": "Last name",
          "attribute": "hwlRTFIFSUq",
          "type": "string",
          "value": "Efrem"
        },
        {
          "code": "Height in cm",
          "displayName": "Height in cm",
          "attribute": "lw1SqmMlnfh",
          "type": "number",
          "value": "164"
        },
        {
          "code": "City",
          "displayName": "City",
          "attribute": "VUvgVao8Y5z",
          "type": "string",
          "value": "Kranskop"
        },
        {
          "code": "State",
          "displayName": "State",
          "attribute": "GUOBQt5K2WI",
          "type": "number",
          "value": "KwaZulu-Natal"
        },
        {
          "code": "Zip code",
          "displayName": "Zip code",
          "attribute": "n9nUvfpTsxQ",
          "type": "number",
          "value": "3282"
        },
        {
          "code": "National identifier",
          "displayName": "National identifier",
          "attribute": "AuPLng5hLbE",
          "type": "string",
          "value": "465700042"
        },
        {
          "code": "Blood type",
          "displayName": "Blood type",
          "attribute": "H9IlTX2X6SL",
          "type": "string",
          "value": "B-"
        },
        {
          "code": "Latitude",
          "displayName": "Latitude",
          "attribute": "Qo571yj6Zcn",
          "type": "string",
          "value": "-30.659626"
        },
        {
          "code": "Longitude",
          "displayName": "Longitude",
          "attribute": "RG7uGl4w5Jq",
          "type": "string",
          "value": "26.916172"
        }
      ]
    }
  ]
}

Requête de la grille d'instances d'entités suivies¶

Pour effectuer une requête sur les instances d'entités suivies, vous pouvez interagir avec la ressource /api/trackedEntityInstances/grid. Il existe deux types de requêtes : L'une où un paramètre de requête query et éventuellement des paramètres attribute sont définis, et l'autre où des paramètres attribute et filter sont définis. Ce point d'extrémité utilise un format de "grille" plus compact et constitue une alternative à la requête de la section précédente.

/api/33/trackedEntityInstances/query

Syntaxe de la requête{ #webapi_tei_grid_query_request_syntax }¶

Tableau : Paramètres de requête pour les instances d'entités suivies

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

Tableau : Modes de sélection des unités d'organisation

Vous pouvez spécifier "attribute" avec des filtres ou directement utiliser les paramètres de filtrage pour restreindre les instances à renvoyer.

Certaines règles s'appliquent aux attributs renvoyés.

• Si "query" est spécifié sans aucun attribut ou programme, alors tous les attributs qui sont marqués comme "Afficher dans la liste sans programme" seront inclus dans la réponse.

• Si le programme est spécifié, tous les attributs qui lui sont associés seront inclus dans la réponse.

• Si le type d'entité suivie est spécifié, alors tous les attributs de type entité suivie seront inclus dans la réponse.

Vous pouvez spécifier des requêtes avec des mots séparés par des espaces - dans ce cas, le système recherchera chaque mot indépendamment et renverra les enregistrements où chaque mot est contenu dans n'importe quel attribut. Un élément de requête peut être spécifié une fois en tant qu'attribut et une fois en tant que filtre si nécessaire. La requête est insensible à 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 à l'aide de l'attribut ou. (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 programStartDate ou programEndDate est spécifié, alors program doit également être spécifié.

• Si eventStatus est spécifié, alors eventStartDate et eventEndDate doivent également être spécifiés.

• Une requête ne peut pas être spécifiée en même temps que des filtres.

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

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

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

/api/33/trackedEntityInstances/query.json?ou=DiszpKrYNg8

Une requête sur tous les attributs pour une valeur et une unité d'organisation spécifiques, en utilisant une correspondance exacte des mots :

/api/33/trackedEntityInstances/query.json?query=scott&ou=DiszpKrYNg8

Une requête sur tous les attributs pour une valeur spécifique, en utilisant une correspondance partielle des mots :

/api/33/trackedEntityInstances/query.json?query=LIKE:scott&ou=DiszpKrYNg8

Vous pouvez effectuer une requête sur plusieurs mots séparés par le caractère URL pour l'espace (%20), ce qui utilisera une requête logique ET pour chaque mot :

/api/33/trackedEntityInstances/query.json?query=isabel%20may&ou=DiszpKrYNg8

Une requête dans laquelle sont spécifiés les attributs à inclure dans la réponse :

/api/33/trackedEntityInstances/query.json?query=isabel
  &attribute=dv3nChNSIxy&attribute=AMpUYgxuCaE&ou=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 :

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  &attribute=AMpUYgxuCaE&ou=DiszpKrYNg8;yMCshbaVExv

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

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  &filter=AMpUYgxuCaE:LIKE:Road&ou=DiszpKrYNg8

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

/api/33/trackedEntityInstances/query.json?ou=DiszpKrYNg8&program=ur1Edk5Oe2n
  &filter=lw1SqmMlnfh:GT:150:LT:190

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

/api/33/trackedEntityInstances/query.json?ou=DiszpKrYNg8
  &attribute=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' :

/api/33/trackedEntityInstances/query.json?filter=zHXD5Ve1Efw:EQ:A
  &ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

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

/api/33/trackedEntityInstances/query.json?filter=zHXD5Ve1Efw:EQ:A
  &ou=O6uvpzGd5pu&program=ur1Edk5Oe2n&programStartDate=2013-01-01
  &programEndDate=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 :

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  &ou=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) :

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  &ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3

Pour effectuer une requête sur les instances qui ont des événements d'un statut donné dans un intervalle de temps donné :

/api/33/trackedEntityInstances/query.json?ou=O6uvpzGd5pu
  &program=ur1Edk5Oe2n&eventStatus=COMPLETED
  &eventStartDate=2014-01-01&eventEndDate=2014-09-01

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

Tableau : Opérateurs de filtre

Format de la réponse¶

Cette ressource prend en charge les représentations JSON, JSONP, XLS et CSV.

• json (application/json)

• jsonp (application/javascript)

• xml (application/xml)

• csv (application/csv)

• xls (application/vnd.ms-excel)

La réponse au format JSON se présente sous la forme d'un tableau et peut ressembler à ce qui suit. La section headers décrit le contenu de chaque colonne. Les colonnes "instance", "créé", "dernière mise à jour", "unité d'organisation" et "entité suivie" sont toujours présentes. Les colonnes suivantes correspondent aux attributs spécifiés dans la requête. La section rows contient une ligne par instance.

{
  "headers": [{
    "name": "instance",
    "column": "Instance",
    "type": "java.lang.String"
  }, {
    "name": "created",
    "column": "Created",
    "type": "java.lang.String"
  }, {
    "name": "lastupdated",
    "column": "Last updated",
    "type": "java.lang.String"
  }, {
    "name": "ou",
    "column": "Org unit",
    "type": "java.lang.String"
  }, {
    "name": "te",
    "column": "Tracked entity",
    "type": "java.lang.String"
  }, {
    "name": "zHXD5Ve1Efw",
    "column": "Date of birth type",
    "type": "java.lang.String"
  }, {
    "name": "AMpUYgxuCaE",
    "column": "Address",
    "type": "java.lang.String"
  }],
  "metaData": {
    "names": {
      "cyl5vuJ5ETQ": "Person"
    }
  },
  "width": 7,
  "height": 7,
  "rows": [
    ["yNCtJ6vhRJu", "2013-09-08 21:40:28.0", "2014-01-09 19:39:32.19", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "21 Kenyatta Road"],
    ["fSofnQR6lAU", "2013-09-08 21:40:28.0", "2014-01-09 19:40:19.62", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "56 Upper Road"],
    ["X5wZwS5lgm2", "2013-09-08 21:40:28.0", "2014-01-09 19:40:31.11", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "56 Main Road"],
    ["pCbogmlIXga", "2013-09-08 21:40:28.0", "2014-01-09 19:40:45.02", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "12 Lower Main Road"],
    ["WnUXrY4XBMM", "2013-09-08 21:40:28.0", "2014-01-09 19:41:06.97", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "13 Main Road"],
    ["xLNXbDs9uDF", "2013-09-08 21:40:28.0", "2014-01-09 19:42:25.66", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "14 Mombasa Road"],
    ["foc5zag6gbE", "2013-09-08 21:40:28.0", "2014-01-09 19:42:36.93", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "15 Upper Hill"]
  ]
}

Filtres d'instances d'entités suivies¶

Pour créer, lire, mettre à jour et supprimer des filtres d'instances d'entités suivies, vous pouvez interagir avec la ressource /api/trackedEntityInstanceFilters. Les filtres d'instances d'entités suivies peuvent être partagés et suivent le même modèle de partage que tout autre objet de métadonnées. En utilisant /api/sharing, le paramètre de type sera trackedEntityInstanceFilter.

/api/33/trackedEntityInstanceFilters

Création et mise à jour d'une définition de filtre d'instance d'entité suivie¶

Pour créer et mettre à jour un filtre d'instance d'entité suivie dans le système, vous devez utiliser la ressource trackedEntityInstanceFilters. Les définitions des filtres d'instances d'entités suivies sont utilisées dans l'application Saisie Tracker pour afficher les "listes de tâches" prédéfinies pertinentes sur l'interface utilisateur du Tracker.

Tableau : Charge

Tableau : Définition des critères de requêtes sur les entités

Tableau : Définition des filtres d'événements

Tableau : Définition de l'objet DateFilterPeriod

Tableau : Définition de la période

Requête sur les filtres d'instances d'entités suivie¶

Pour rechercher des filtres d'instances d'entités suivies dans le système, vous pouvez interagir avec la ressource /api/trackedEntityInstanceFilters.

Tableau : Paramètres de requête pour les filtres d'instances d'entités suivies

Gestion des inscriptions¶

Les inscriptions bénéficient d'une prise en charge CRUD complète dans l'API. Avec l'API des instances d'entités suivies, la plupart des opérations nécessaires pour travailler avec les instances d'entités suivies et les programmes sont prises en charge.

/api/33/enrollments

Inscription d'une instance d'entité suivie à un programme¶

Pour inscrire des personnes à un programme, vous devez d'abord obtenir l'identifiant de la personne à partir de la ressource trackedEntityInstances. Ensuite, vous devez obtenir l'identifiant du programme à partir de la ressource programs. Un modèle de charge utile est présenté ci-dessous :

{
  "trackedEntityInstance": "ZRyCnJ1qUXS",
  "orgUnit": "ImspTQPwCqd",
  "program": "S8uo8AlvYMz",
  "enrollmentDate": "2013-09-17",
  "incidentDate": "2013-09-17"
}

Cette charge doit être utilisée dans une requête POST à la ressource des inscriptions identifiée par l'URL suivante :

/api/33/enrollments

Les différents statuts d'une inscription sont les suivants :

• ACTIVE : utilisé lorsque l'entité suivie participe au programme.
• COMPLETED : utilisé lorsque l'entité suivie a terminé sa participation au programme.
• CANCELLED : "Désactivé" dans l'interface web. Il est utilisé lorsque l'entité suivie a annulé sa participation au programme.

Pour annuler ou terminer une inscription, vous pouvez adresser une requête PUT à la ressource enrollments, en indiquant l'identifiant de l'inscription et l'action que vous voulez réaliser. Pour annuler l'inscription d'une entité suivie :

/api/33/enrollments/<enrollment-id>/cancelled

Pour terminer l'inscription d'une instance d'entité suivie, vous pouvez envoyez une requête PUT à l'URL suivante :

/api/33/enrollments/<enrollment-id>/completed

Pour supprimer une inscription, vous pouvez envoyer une requête DELETE à l'URL suivante :

/api/33/enrollments/<enrollment-id>

Requête pour l'instance d'inscription¶

Pour rechercher des inscriptions, vous pouvez interagir avec la ressource /api/enrollments.

/api/33/enrollments

Syntaxe de la requête¶

Tableau : Paramètres de la requête d'inscription

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

Tableau : Modes de sélection des unités d'organisation

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 à l'aide de l'attribut ou. (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 programStartDate ou programEndDate est spécifié, alors program doit également être spécifié.

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

/api/33/enrollments.json?ou=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 :

/api/33/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

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

/api/33/enrollments.json?&ou=O6uvpzGd5pu&program=ur1Edk5Oe2n
  &programStartDate=2013-01-01&programEndDate=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 :

/api/33/enrollments.json?ou=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 :

/api/33/enrollments.json?ouMode=ACCESSIBLE&trackedEntityInstance=tphfdyIiVL6

Par défaut, les inscriptions 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) :

/api/33/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3

Format de la réponse¶

Cette ressource prend en charge les représentations JSON, JSONP, XLS et CSV.

• json (application/json)

• jsonp (application/javascript)

• xml (application/xml)

La réponse en JSON/XML est au format objet et peut ressembler à ce qui suit. Le filtrage des champs est possible, donc si vous voulez un affichage complet, vous pouvez ajouter fields=* à la requête :

{
  "enrollments": [
    {
      "lastUpdated": "2014-03-28T05:27:48.512+0000",
      "trackedEntity": "cyl5vuJ5ETQ",
      "created": "2014-03-28T05:27:48.500+0000",
      "orgUnit": "DiszpKrYNg8",
      "program": "ur1Edk5Oe2n",
      "enrollment": "HLFOK0XThjr",
      "trackedEntityInstance": "qv0j4JBXQX0",
      "followup": false,
      "enrollmentDate": "2013-05-23T05:27:48.490+0000",
      "incidentDate": "2013-05-10T05:27:48.490+0000",
      "status": "ACTIVE"
    }
  ]
}

Événements¶

Cette section traite de l'envoi et de la lecture des événements.

/api/33/events

Les différents statuts d'un événement sont les suivants :

• ACTIVE (actif): Si un événement a le statut ACTIVE, il est possible de modifier les détails de l'événement. Les événements de statut COMPLETED peuvent devenir ACTIVE à nouveau et vice versa.
• COMPLETED (terminé) : Un événement ne prend le statut COMPLETED que lorsqu'un utilisateur clique sur le bouton "Terminer". Si un événement a le statut COMPLETED, ses informations ne peuvent pas être modifiées. Les événements de statut ACTIVE peuvent devenir COMPLETED à nouveau et vice versa.
• SKIPPED (ignoré): Événements programmés qui n'ont plus lieu d'être. Dans l'application Saisie Tracker, un bouton est dédié à ce paramètre.
• SCHEDULE (planifié): Si un événement n'a pas de date d'événement (mais qu'il a une date d'échéance), le statut de l'événement est sauvegardé en tant SCHEDULE.
• OVERDUE (en retard) : Si la date d'échéance d'un événement planifié (sans date d'événement) a expiré, l'événement peut être considéré comme étant en retard.
• VISITED (visité) : (Ce statut est supprimé depuis la version 2.38. Il a migré vers ACTIVE). Dans l'application Saisie Tracker, il est possible d'atteindre le statut VISITED en ajoutant un nouvel événement avec une date d'événement, puis de le quitter avant d'y ajouter des données - l'équipe du Tracker ne remarquera pas qu'un utilisateur a fait usage de ce statut pour une raison quelconque. Le statut VISITED n'est pas visible dans l'interface utilisateur et est traité de la même manière qu'un événement de statut "ACTIVE".

Envoi d'événements¶

DHIS2 prend en charge trois types d'événements : les événements uniques sans enregistrement (également appelés événements anonymes), les événements uniques avec enregistrement et les événements multiples avec enregistrement. L'enregistrement implique que les données sont rattachées à une instance d'entité suivie qui est identifiée à l'aide d'un identifiant.

Pour envoyer des événements à DHIS2, vous devez interagir avec la ressource events. L'approche utilisée pour envoyer des événements est similaire à celle utilisée pour envoyer des valeurs de données agrégées. Vous aurez besoin d'un programme qui peut être recherché à l'aide de la ressource programs, d'une unité d'organisation qui peut être recherchée à l'aide de la ressource organisationUnits, et d'une liste d'identifiants d'éléments de données valides qui peuvent être recherchés à l'aide de la ressource dataElements. Pour les événements avec enregistrement, un identifiant d'instance d'entité suivie est nécessaire. Pour savoir comment l'obtenir, consultez la section sur la ressource trackedEntityInstances. Pour envoyer des événements à des programmes comportant plusieurs étapes, il vous faudra également inclure l'identifiant programStage (étape de programme). Les identifiants des étapes de programme se trouvent dans la ressource programStages.

Voici un exemple simple d'événement unique sans enregistrement au format XML. Dans cet exemple, nous envoyons vers la base de données de démonstration, des événements du programme "Morbidité et mortalité des patients hospitalisés" pour l'établissement "Ngelehun CHC" :

<?xml version="1.0" encoding="utf-8"?>
<event program="eBAyeGv0exc" orgUnit="DiszpKrYNg8"
  eventDate="2013-05-17" status="COMPLETED" storedBy="admin">
  <coordinate latitude="59.8" longitude="10.9" />
  <dataValues>
    <dataValue dataElement="qrur9Dvnyt5" value="22" />
    <dataValue dataElement="oZg33kd9taw" value="Male" />
    <dataValue dataElement="msodh3rEMJa" value="2013-05-18" />
  </dataValues>
</event>

Pour faire des tests, nous pouvons enregistrer la charge XML dans un fichier appelé event.xml et l'envoyer sous la forme d'une requête POST à la ressource "events" de l'API à l'aide de curl et de la commande suivante :

curl -d @event.xml "https://play.dhis2.org/demo/api/33/events"
  -H "Content-Type:application/xml" -u admin:district

La même charge au format JSON se présente comme suit :

{
  "program": "eBAyeGv0exc",
  "orgUnit": "DiszpKrYNg8",
  "eventDate": "2013-05-17",
  "status": "COMPLETED",
  "completedDate": "2013-05-18",
  "storedBy": "admin",
  "coordinate": {
    "latitude": 59.8,
    "longitude": 10.9
  },
  "dataValues": [
    {
      "dataElement": "qrur9Dvnyt5",
      "value": "22"
    },
    {
      "dataElement": "oZg33kd9taw",
      "value": "Male"
    },
    {
      "dataElement": "msodh3rEMJa",
      "value": "2013-05-18"
    }
  ]
}

Pour l'envoyer, vous pouvez l'enregistrer dans un fichier appelé event.json et utiliser curl comme suit :

curl -d @event.json "localhost/api/33/events" -H "Content-Type:application/json"
  -u admin:district

Nous pouvons également envoyer plusieurs événements en même temps. Une charge au format XML pourrait ressembler à ceci :

<?xml version="1.0" encoding="utf-8"?>
<events>
  <event program="eBAyeGv0exc" orgUnit="DiszpKrYNg8"
    eventDate="2013-05-17" status="COMPLETED" storedBy="admin">
    <coordinate latitude="59.8" longitude="10.9" />
    <dataValues>
      <dataValue dataElement="qrur9Dvnyt5" value="22" />
      <dataValue dataElement="oZg33kd9taw" value="Male" />
    </dataValues>
  </event>
  <event program="eBAyeGv0exc" orgUnit="DiszpKrYNg8"
    eventDate="2013-05-17" status="COMPLETED" storedBy="admin">
    <coordinate latitude="59.8" longitude="10.9" />
    <dataValues>
      <dataValue dataElement="qrur9Dvnyt5" value="26" />
      <dataValue dataElement="oZg33kd9taw" value="Female" />
    </dataValues>
  </event>
</events>

Vous recevrez un récapitulatif de l'importation avec la réponse qui peut être inspecté afin d'obtenir des informations sur le résultat de la requête, par exemple le nombre de valeurs qui ont été importées avec succès. La charge au format JSON ressemble à ceci :

{
  "events": [
  {
    "program": "eBAyeGv0exc",
    "orgUnit": "DiszpKrYNg8",
    "eventDate": "2013-05-17",
    "status": "COMPLETED",
    "storedBy": "admin",
    "coordinate": {
      "latitude": "59.8",
      "longitude": "10.9"
    },
    "dataValues": [
      {
        "dataElement": "qrur9Dvnyt5",
        "value": "22"
      },
      {
        "dataElement": "oZg33kd9taw",
        "value": "Male"
      }
    ]
  },
  {
    "program": "eBAyeGv0exc",
    "orgUnit": "DiszpKrYNg8",
    "eventDate": "2013-05-17",
    "status": "COMPLETED",
    "storedBy": "admin",
    "coordinate": {
      "latitude": "59.8",
      "longitude": "10.9"
    },
    "dataValues": [
      {
        "dataElement": "qrur9Dvnyt5",
        "value": "26"
      },
      {
        "dataElement": "oZg33kd9taw",
        "value": "Female"
      }
    ]
  } ]
}

Vous pouvez également utiliser GeoJson pour stocker tout type de géométrie sur votre événement. Voici un exemple de charge utilisant GeoJson et non les anciennes propriétés de latitude et de longitude :

{
  "program": "eBAyeGv0exc",
  "orgUnit": "DiszpKrYNg8",
  "eventDate": "2013-05-17",
  "status": "COMPLETED",
  "storedBy": "admin",
  "geometry": {
    "type": "POINT",
    "coordinates": [59.8, 10.9]
  },
  "dataValues": [
    {
      "dataElement": "qrur9Dvnyt5",
      "value": "22"
    },
    {
      "dataElement": "oZg33kd9taw",
      "value": "Male"
    },
    {
      "dataElement": "msodh3rEMJa",
      "value": "2013-05-18"
    }
  ]
}

Le récapitulatif de l'importation contient également l'identifiant reference de l'événement que vous venez d'envoyer, ainsi qu'un élément href qui indique l'emplacement du serveur de cet événement. Le tableau ci-dessous décrit la signification de chaque élément.

Tableau : Format de la ressource des événements

Correspondance des unités d'organisation (paramètre orgUnit)¶

Par défaut, le paramètre orgUnit correspondra à l'identifiant. Vous pouvez également sélectionner le schéma de correspondance de l'identifiant de l'unité d'organisation en utilisant le paramètre orgUnitIdScheme=SCHEME, où les options sont : ID, UID, UUID, CODE et NAME. Il existe également le schéma ATTRIBUTE:, qui correspond à une valeur d'attribut de métadonnées unique.

Mise à jour des événements¶

Pour mettre à jour un événement existant, le format de la charge reste le même, mais il faudra ajouter l'identifiant à la fin de la chaîne de l'URL à laquelle vous adressez la requête, et la requête doit être de type PUT.

La charge doit contenir tous les attributs, même ceux qui n'ont pas été modifiés. Les attributs qui étaient présents auparavant et qui ne sont plus présents dans la charge actuelle seront supprimés par le système.

Il n'est pas autorisé de mettre à jour un événement déjà supprimé. Il en va de même pour les instances d'entité suivie et les inscriptions.

curl -X PUT -d @updated_event.xml "localhost/api/33/events/ID"
  -H "Content-Type: application/xml" -u admin:district

curl -X PUT -d @updated_event.json "localhost/api/33/events/ID"
  -H "Content-Type: application/json" -u admin:district

Suppression des événements¶

Pour supprimer un événement existant, il suffit d'envoyer une requête DELETE au serveur que vous utilisez, avec une référence d'identifiant, .

curl -X DELETE "localhost/api/33/events/ID" -u admin:district

Affectation d'un utilisateur à un événement¶

Un utilisateur peut être affecté à un événement. Pour ce faire, il suffit d'inclure la propriété appropriée dans la charge lors de la mise à jour ou de la création de l'événement.

  "assignedUser": "<id>"

L'id fait référence à l'identifiant de l'utilisateur. Un seul utilisateur peut être affecté à un événement à la fois.

L'affectation des utilisateurs doit être activée dans la phase de programmation avant que les utilisateurs puissent être affectés à des événements.

Obtenir des événements¶

Pour obtenir un événement existant, vous pouvez envoyer une requête GET comprenant l'identifiant comme ceci :

curl "http://localhost/api/33/events/ID" -H "Content-Type: application/xml" -u admin:district

Interroger et lire des événements¶

Cette section explique comment lire les événements qui ont été stockés dans l'instance DHIS2. Pour pouvoir utiliser les données d'événements de manière plus avancée, veuillez consulter la section consacrée à l'analyse des événements. Le format de sortie du point d'extrémité /api/events correspondra au format utilisé pour lui envoyer des événements (ce format n'est pas pris en charge par l'api d'analyse d'événements). Les formats XML et JSON sont pris en charge. Pour pouvoir les utiliser, il suffit d'ajouter un fichier .json/.xml ou de définir l'en-tête Accept approprié. La requête est paginée par défaut et la taille de la page par défaut est de 50 événements. Le filtrage par champs fonctionne comme avec les métadonnées. Pour l'utiliser, ajoutez le paramètre fields et spécifiez les propriétés que vous voulez, ce qui nous donne fields=program,status.

Tableau : Paramètres de requête de la ressource des événements

Remarque

Si la requête ne contient ni attributeCC ni attributeCos, le serveur renvoie des événements pour toutes les combinaisons d'options d'attribut pour lesquelles l'utilisateur a un accès en lecture.

Exemples¶

Requête sur de tous les événements associés aux subordonnées d'une unité d'organisation donnée :

/api/29/events.json?orgUnit=YuQRtpLP10I&ouMode=CHILDREN

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 :

/api/33/events.json?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS

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

/api/33/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

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 :

/api/33/events.json?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 :

/api/33/events.json?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 :

/api/33/events.json?orgUnit=DiszpKrYNg8
  &program=eBAyeGv0exc&trackedEntityInstance=gfVxE3ALA9m

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 :

/api/33/events.json?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 :

/api/33/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  &trackedEntityInstance=gfVxE3ALA9m&startDate=2014-01-01&endDate=2014-12-31

Requête pour des fichiers associés aux valeurs de données d'événement. Si l'on veut récupérer un fichier image, un paramètre supplémentaire peut être fourni pour récupérer l'image dans différentes options de dimensions. Si aucune dimension n'est fournie, le système renvoie l'image originale. Le paramètre sera ignoré si les fichiers ne sont pas des images, par exemple des fichiers PDF. Les valeurs possibles pour les dimensions sont small(254 x 254), medium(512 x 512), large(1024 x 1024) ou original. Toute valeur autre que celles mentionnées sera écartée et l'image originale sera renvoyée.

/api/33/events/files?eventUid=hcmcWlYkg9u&dataElementUid=C0W4aFuVm4P&dimension=small

Pour récupérer les événements associées à une unité d'organisation et un programme spécifiés, et utiliser Attribute:Gq0oWTf2DtN comme schéma d'identification :

/api/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&idScheme=Attribute:Gq0oWTf2DtN

Pour récupérer les événements associés à l'unité d'organisation et au programme spécifiés, et utiliser l'UID comme schéma d'identification pour les unités d'organisation, le code comme schéma d'identification pour les étapes du programme, et Attribute:Gq0oWTf2DtN comme schéma d'identification pour le reste des métadonnées avec les attributs assignés :

api/events.json?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&idScheme=Attribute:Gq0oWTf2DtN
  &orgUnitIdScheme=UID&programStageIdScheme=Code

Requête pour les grilles d'événements¶

En plus du point d'extrémité des requêtes d'événements ci-dessus, il existe un point d'extrémité pour les requêtes de grilles d'événements où un format de "grille" d'événements plus compact est renvoyé. Vous pouvez le faire en interagissant avec /api/events/query.json|xml|xls|csv.

/api/33/events/query

La plupart des paramètres de requête mentionnés dans la section sur la requête et la lecture d'événements ci-dessus sont valables ici. Toutefois, étant donné que la grille à renvoyer comporte un ensemble spécifique de colonnes qui s'appliquent à toutes les lignes (événements), il est obligatoire de spécifier une étape de programme. Il n'est pas possible de combiner des événements de différents programmes ou étapes de programme dans le renvoi.

Le renvoi d'événements appartenant à une même étape de programme ouvre également la voie à de nouvelles fonctionnalités, par exemple le tri et la recherche d'événements sur la base des valeurs de leurs éléments de données. api/events/query prend en charge ces fonctionnalités. Voici quelques exemples :

Une requête pour obtenir une grille d'événements qui contient uniquement des éléments de données sélectionnés pour une étape de programme :

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  &dataElement=qrur9Dvnyt5,fWIAEtYVEGk,K6uUAvq500H&order=lastUpdated:desc
  &pageSize=50&page=1&totalPages=true

Une requête qui renvoie une grille d'événements qui contient tous les éléments de données d'une étape de programme :

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  &includeAllDataElements=true

Une requête pour filtrer les événements sur la base des valeurs de l'élément de données

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  &filter=qrur9Dvnyt5:GT:20:LT:50

Outre le filtrage, l'exemple ci-dessus illustre également une chose : le fait qu'il n'y a pas d'éléments de données mentionnés à renvoyer dans la grille. Dans ce cas, par défaut, le système ne renvoie que les éléments de données marqués "Afficher dans le rapport" dans la configuration des étapes de programme.

Nous pouvons également étendre la requête ci-dessus pour obtenir une grille triée (par ordre ascendant ou descendant) sur la base des valeurs de l'élément de données

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  &filter=qrur9Dvnyt5:GT:20:LT:50&order=qrur9Dvnyt5:desc

Filtres d'événements¶

Pour créer, lire, mettre à jour et supprimer des filtres d'événements, vous pouvez interagir avec la ressource /api/eventFilters.

/api/33/eventFilters

Création et mise à jour d'une définition de filtre d'événement¶

Pour créer et mettre à jour un filtre d'événement dans le système, vous devez utiliser la ressource eventFilters. La méthode POST est utilisée pour créer et la méthode PUT est utilisée pour la mise à jour. Les définitions des filtres d'événements sont utilisées dans l'application Saisie Tracker pour afficher les "listes de tâches" prédéfinies pertinentes sur l'interface utilisateur du Tracker.

Tableau : Charge de la requête

Tableau : Définition des critères de requêtes d'événements

Tableau : Définition de l'objet DateFilterPeriod

Les modes de sélection des utilisateurs assignés disponibles sont expliqués dans le tableau suivant.

Tableau : Modes de sélection des utilisateurs assignés (attribution d'événements)

Un exemple de charge pouvant être utilisée pour créer/mettre à jour un filtre d'événement est présenté ci-dessous.

{
  "program": "ur1Edk5Oe2n",
  "description": "Simple Filter for TB events",
  "name": "TB events",
  "eventQueryCriteria": {
    "organisationUnit":"DiszpKrYNg8",
    "eventStatus": "COMPLETED",
    "eventDate": {
      "startDate": "2014-05-01",
      "endDate": "2019-03-20",
      "startBuffer": -5,
      "endBuffer": 5,
      "period": "LAST_WEEK",
      "type": "RELATIVE"
    },
    "dataFilters": [{
      "dataItem": "abcDataElementUid",
      "le": "20",
      "ge": "10",
      "lt": "20",
      "gt": "10",
      "in": ["India", "Norway"],
      "like": "abc"
    },
    {
      "dataItem": "dateDataElementUid",
      "dateFilter": {
        "startDate": "2014-05-01",
        "endDate": "2019-03-20",
        "type": "ABSOLUTE"
      }
    },
    {
      "dataItem": "anotherDateDataElementUid",
      "dateFilter": {
        "startBuffer": -5,
        "endBuffer": 5,
        "type": "RELATIVE"
      }
    },
    {
      "dataItem": "yetAnotherDateDataElementUid",
      "dateFilter": {
        "period": "LAST_WEEK",
        "type": "RELATIVE"
      }
    }],
    "programStatus": "ACTIVE"
  }
}

Récupération et suppression des filtres d'événements¶

Un filtre d'événement spécifique peut être récupéré à l'aide de l'API suivante :

GET /api/33/eventFilters/{uid}

Tous les filtres d'événements peuvent être récupérés à l'aide de l'API suivante :

GET /api/33/eventFilters?fields=*

Tous les filtres d'événements pour un programme spécifique peuvent être récupérés à l'aide de l'API suivante :

GET /api/33/eventFilters?filter=program:eq:IpHINAT79UW

Un filtre d'événement peut être supprimé à l'aide de l'API suivante

DELETE /api/33/eventFilters/{uid}

Relations¶

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.

Il existe plusieurs points d'extrémité qui vous permettent de voir, de créer, de supprimer et de mettre à jour les relations. Le plus courant est /api/trackedEntityInstances, où vous pouvez inclure des relations dans la charge pour les créer, les mettre à jour ou les supprimer si vous les omettez - de la même manière que vous travaillez avec les inscriptions et les événements dans le même point d'extrémité. Tous les points d'extrémité du Tracker, c'est-à-dire /api/trackedEntityInstances, /api/enrollments et /api/events listent également leurs relations si une requête est spécifiée dans le filtre de champ.

Toutefois, le point d'extrémité communément utilisé pour les relations est /api/relationships. Il fournit toutes les opérations CRUD normales pour les relations.

Vous pouvez afficher une liste de relations par instance d'entité suivie, inscription ou événement :

GET /api/relationships?[tei={teiUID}|enrollment={enrollmentUID}|event={eventUID}]

Cette requête renverra une liste de toutes les relations que vous pouvez voir. Cela inclut l'instance d'entité suivie, l'inscription ou l'événement que vous avez spécifié. Chaque relation est représentée par le JSON suivant :

{
  "relationshipType": "dDrh5UyCyvQ",
  "relationshipName": "Mother-Child",
  "relationship": "t0HIBrc65Rm",
  "bidirectional": false,
  "from": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "vOxUH373fy5"
    }
  },
  "to": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "pybd813kIWx"
    }
  },
  "created": "2019-04-26T09:30:56.267",
  "lastUpdated": "2019-04-26T09:30:56.267"
}

Vous pouvez également visualiser les relations spécifiées en utilisant le point d'extrémité suivant :

GET /api/relationships/<id>

Pour créer ou mettre à jour une relation, vous pouvez utiliser les points d'extrémité suivants :

POST /api/relationships
PUT /api/relationships

Et utilisez la structure de charge suivante :

{
  "relationshipType": "dDrh5UyCyvQ",
  "from": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "vOxUH373fy5"
    }
  },
  "to": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "pybd813kIWx"
    }
  }
}

Pour supprimer une relation, vous pouvez utiliser ce point d'extrémité :

  DELETE /api/relationships/<id>

Dans nos exemples de charges, nous utilisons une relation entre instances d'entités suivies. C'est pourquoi les propriétés "from" et "to" de nos charges incluent des objets "trackedEntityInstance". Si votre relation inclut d'autres entités, vous pouvez utiliser les propriétés suivantes :

{
  "enrollment": {
    "enrollment": "<id>"
  }
}

{
  "event": {
    "event": "<id>"
  }
}

Une relation peut être supprimée de façon réversible. Dans ce cas, vous pouvez utiliser le paramètre de requête includeDeleted pour voir cette relation.

GET /api/relationships?tei=pybd813kIWx?includeDeleted=true

Stratégies de mise à jour¶

Deux stratégies de mise à jour sont prises en charge pour les trois points d'extrémité du Tracker : l'inscription et la création d'événements. Ceci est utile lorsque vous avez généré un identifiant au niveau du client et que vous n'êtes pas sûr s'il a été créé ou non sur le serveur.

Tableau : Stratégies du Tracker disponibles

Pour modifier ce paramètre, utilisez le paramètre de stratégie :

POST /api/33/trackedEntityInstances?strategy=CREATE_AND_UPDATE

Suppression en bloc dans le Tracker¶

La suppression en bloc d'objets Tracker fonctionne de la même manière que l'ajout et la mise à jour d'objets Tracker. La seule différence est que la stratégie d'importation (importStrategy) est DELETE.

Exemple : Suppression en bloc d'instances d'entités suivies :

{
  "trackedEntityInstances": [
    {
      "trackedEntityInstance": "ID1"
    }, {
      "trackedEntityInstance": "ID2"
    }, {
      "trackedEntityInstance": "ID3"
    }
  ]
}

curl -X POST -d @data.json -H "Content-Type: application/json"
  "http://server/api/33/trackedEntityInstances?strategy=DELETE"

Exemple : Suppression en bloc d'inscriptions :

{
  "enrollments": [
    {
       "enrollment": "ID1"
    }, {
      "enrollment": "ID2"
    }, {
      "enrollment": "ID3"
    }
  ]
}

curl -X POST -d @data.json -H "Content-Type: application/json"
  "http://server/api/33/enrollments?strategy=DELETE"

Exemple : Suppression en bloc d'événements:

{
  "events": [
    {
      "event": "ID1"
    }, {
      "event": "ID2"
    }, {
      "event": "ID3"
    }
  ]
}

curl -X POST -d @data.json -H "Content-Type: application/json"
  "http://server/api/33/events?strategy=DELETE"

Réutilisation d'identifiants et suppression d'éléments via les méthodes POST et PUT¶

Les points d'extrémité du Tracker /trackedEntityInstances, /enrollments, /events prennent en charge les opérations CRUD. Le système garde la trace des identifiants utilisés. Ainsi, un élément qui a été créé puis supprimé (par exemple, un événement ou une inscription) ne peut pas être créé ou mis à jour à nouveau. Si l'on tente de supprimer un élément déjà supprimé, le système renvoie une réponse de succès, car la suppression d'un élément déjà supprimé n'implique aucun changement.

Le système ne permet pas de supprimer un élément via une méthode de mise à jour (PUT) ou de création (POST). Par conséquent, l'attribut deleted est ignoré dans les méthodes PUT et POST, et dans la méthode POST, il est défini par défaut sur false.

Paramètres d'importation¶

Le processus d'importation peut être personnalisé à l'aide d'un ensemble de paramètres d'importation :

Tableau : Paramètres d'importation

Importation / exportation CSV¶

Outre les formats XML et JSON pour l'importation et l'exportation d'événements, le format CSV a été introduit dans DHIS2.17. La prise en charge de ce format s'appuie sur ce qui a été décrit dans la dernière section, nous ne parlerons donc ici que des parties spécifiques au format CSV.

Pour utiliser le format CSV, vous devez soit utiliser le point d'extrémité /api/events.csv ou ajouter content-type : text/csv pour l'importation, et accept :text/csv pour l'exportation, lorsque vous utilisez le point d'extrémité /api/events.

L'ordre des colonnes du fichier CSV qui sont utilisées pour l'exportation et l'importation est le suivant :

Tableau : Colonne CSV

Exemple de 2 événements avec 2 valeurs de données différentes chacun :

EJNxP3WreNP,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,1,,
EJNxP3WreNP,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,2,,
qPEdI1xn7k0,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,3,,
qPEdI1xn7k0,COMPLETED,<pid>,<psid>,<enrollment-id>,<ou>,2016-01-01,2016-01-01,,,<de>,4,,

Stratégie d'importation : SYNC¶

La stratégie d'importation SYNC ne doit être utilisée que par la tâche de synchronisation interne et non pour l'importation régulière. La stratégie SYNC permet aux 3 opérations (CREATE, UPDATE, DELETE) d'être présentes dans la charge au moment moment.

Gestion de la Propriété Tracker¶

Un nouveau concept appelé "Propriété Tracker" est introduit à partir de la version 2.30. Désormais, il n'y aura plus qu'une seule unité d'organisation propriétaire pour une instance d'entité suivie dans le cadre d'un programme. Les programmes configurés avec un niveau d'accès PROTECTED (protégé) ou CLOSED (fermé) respecteront les privilèges de propriété. Seuls les utilisateurs appartenant à l'unité d'organisation propriétaire d'une combinaison entité suivie-programme pourront accéder aux données liées à ce programme pour cette entité suivie.

Annulation de la Propriété Tracker : Briser le verre¶

Il est possible d'annuler temporairement ce privilège de propriété pour un programme configuré avec un niveau d'accès PROTECTED. Tout utilisateur sera en mesure d'obtenir temporairement l'accès aux données liées au programme s'il fournit une raison d'accéder aux données de la combinaison Entité suivie - Programme. Ce fait d'obtenir temporairement l'accès est appelé briser la glace. Actuellement, l'accès temporaire est accordé pour une durée de 3 heures. DHIS2 vérifie l'aspect "briser la glace" ainsi que la raison fournie par l'utilisateur. Il n'est pas possible d'obtenir un accès temporaire à un programme qui a été configuré avec un niveau d'accès CLOSED. Pour briser la glace avec une combinaison Entité suivie - Programme, vous pouvez utiliser la requête POST suivante :

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

Transfert de la propriété Tracker{ #webapi_tracker_ownership_transfer_api }¶

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 propriétaire (ou un utilisateur qui a utilisé la fonction de brise glace) peut transférer la propriété. Pour transférer la propriété d'une combinaison Entité suivie - Programme à une autre unité d'organisation, vous pouvez utiliser la requête "PUT" suivante :

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

Doublons potentiels¶

Les doublons potentiels sont les enregistrements sur les lesquels nous travaillons dans le cadre de la déduplication des données. En raison de la nature de la fonction de déduplication, ce point d'extrémité d'API est quelque peu restreint.

Un doublon potentiel représente une paire d'enregistrements qui sont soupçonnés d'être des doublons.

La charge d'un doublon potentiel se présente comme suit :

{
  "original": "<id>",
  "duplicate": "<id>",
  "status": "OPEN|INVALID|MERGED"
}

Vous pouvez récupérer une liste de doublons potentiels en utilisant le point d'extrémité suivant :

GET /api/potentialDuplicates

Vous pouvez inspecter des enregistrements individuels susceptibles d'être dupliqués :

GET /api/potentialDuplicates/<id>

Pour créer un nouveau doublon potentiel, vous pouvez utiliser ce point d'extrémité :

POST /api/potentialDuplicates

La charge que vous fournissez doit inclure les ID des TEI originales et des TEI dupliquées.

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

Pour mettre à jour un statut de doublon potentiel :

PUT /api/potentialDuplicates/<id>

Fusion des instances d'entités suivies¶

Les instances d'entités suivies peuvent désormais être fusionnées si elles sont compatibles. Pour lancer une fusion, la première étape consiste à définir deux instances d'entités suivies en tant que doublons potentiels. Le point d'extrémité de fusion déplacera les données de l'instance d'entité suivie dupliquée vers l'instance d'entité suivie originale, et supprimera les données restantes de l'instance dupliquée.

Pour fusionner un doublon potentiel ou les deux instances d'entités suivies que le doublon potentiel représente, le point d'extrémité suivant peut être utilisé :

POST /api/potentialDuplicates/<id>/merge

Le point d'extrémité accepte un seul paramètre, "mergeStrategy", qui détermine la stratégie à utiliser lors de la fusion. Avec la stratégie AUTO, le serveur tentera de fusionner les deux entités suivies automatiquement, sans aucune intervention de l'utilisateur. Cette stratégie permet uniquement de fusionner des entités suivies qui n'ont pas de données incompatibles (voir les exemples ci-dessous). L'autre stratégie, MANUAL, exige que l'utilisateur envoie une charge décrivant la manière dont la fusion doit être effectuée. Pour voir des exemples et des règles pour chaque stratégie, consultez leurs sections respectives ci-dessous.

Stratégie de fusion AUTO¶

La fusion automatique évalue la possibilité de fusionner les deux instances d'entités suivies et les fusionne si elles sont jugées fusionnables. La fusion est basée sur l'existence ou non de conflits entre les deux instances d'entités suivies. Les conflits concernent les données qui ne peuvent pas être fusionnées automatiquement. Voici quelques exemples possibles de conflits : - Un même attribut a des valeurs différentes dans chaque instance d'entité suivie - Les deux instances d'entités suivies sont inscrites au même programme - Les instances d'entités suivies sont de différents types

En cas de conflit, un message d'erreur est renvoyé à l'utilisateur.

Si aucun conflit n'est détecté, toutes les données du doublon qui ne se trouvent pas déjà dans l'instance originale seront déplacées vers cette dernière. Il s'agit notamment des valeurs d'attributs, des inscriptions (y compris les événements) et des relations. Une fois la fusion terminée, le doublon est supprimé et le doublon potentiel est marqué MERGED.

Lorsque vous effectuez une requête de fusion automatique comme celle-ci, une charge n'est pas nécessaire et cette partie sera ignorée.

Stratégie de fusion MANUAL¶

La fusion manuelle peut être utilisée lorsque des conflits peuvent être résolus ou lorsque toutes les données ne doivent pas être transférées au cours de la fusion. Par exemple, si un attribut a des valeurs différentes dans les deux instances d'entité suivies, l'utilisateur peut spécifier s'il souhaite conserver la valeur originale ou déplacer la valeur du doublon. Étant donné que, dans le cas d'une fusion manuelle, c'est l'utilisateur lui-même qui configure le transfert des données, des vérifications sont faites : - Il ne peut pas y avoir de relation entre l'originale et le doublon (ceci résulte en une relation d'autoréférencement invalide). - La relation ne peut pas être du même type et concerner le même objet dans les deux instances d'entités suivies (par exemple, entre l'originale et un autre, et entre le doublon et un autre ; il en résulterait une relation dupliquée).

Il existe deux façons d'effectuer une fusion manuelle : Avec et sans charge.

Lorsqu'une requête de fusion manuelle est effectuée sans charge, il est demandé à l'API de fusionner les deux instances d'entités suivies sans déplacer de données. En d'autres termes, nous supprimons simplement le doublon et marquons le doublon potentiel MERGED. Cela peut être valable dans de nombreux cas où l'instance d'entité suivie vient d'être créée, mais qu'elle n'a pas été inscrite, par exemple.

Dans le cas contraire, si une requête de fusion manuelle est effectuée avec une charge, celle-ci indique les données qui doivent être transférées du doublon vers l'original. La charge se présente comme suit :

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

Cette charge contient trois listes, une pour chaque type de données qui peuvent être déplacées. trackedEntityAttributes est une liste d'uids pour les attributs des entités suivies, enrollments est une liste d'uids pour les inscriptions et relationships une liste d'uids pour les relations. Les uids de cette charge doivent faire référence à des données qui existent réellement sur le doublon. Il est impossible d'ajouter de nouvelles données ou de modifier des données à l'aide du point d'extrémité de fusion - il ne sert qu'à déplacer des données.

Informations complémentaires sur la fusion¶

Actuellement, il n'est pas possible de fusionner des instances d'entités suivies qui sont inscrites à un même programme, en raison de la complexité accrue. Une alternative consiste à supprimer manuellement les inscriptions de l'une des instances avant de commencer la fusion.

Toutes les fusions sont basées sur des données déjà conservées dans la base de données ; le service de fusion actuel ne valide donc pas ces données à nouveau. Cela signifie que si des données étaient déjà invalides, elles ne seront pas signalées lors de la fusion. La seule validation effectuée dans le service concerne les relations, tel qu'indiqué dans la section précédente.

Modèle de notification de programme¶

Le Modèle de notification de programme vous permet de créer des modèles de message qui peuvent être envoyés à la suite de différents types d'événements. Les modèles de message et d'objet seront convertis en valeurs réelles et pourront être envoyés à la destination configurée. Chaque modèle de notification de programme sera transformé en objet MessageConversation ou ProgramMessage en fonction du destinataire externe ou interne de la notification (notificationRecipient). Ces objets intermédiaires ne contiendront que le message traduit et le texte de l'objet. Plusieurs paramètres de configuration du Modèle de notification de programme sont essentiels au bon fonctionnement des notifications. Tous ces paramètres sont expliqués dans le tableau ci-dessous.

POST /api/programNotificationTemplates

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

Les champs sont expliqués dans le tableau suivant.

Tableau : Charge du Modèle de notification de programme

NOTE : WEB_HOOK notificationRecipient est utilisé uniquement pour envoyer (POST) des requêtes http à un système externe. Assurez-vous de choisir le canal HTTP lorsque vous utilisez WEB_HOOK.

Récupération et suppression du Modèle de notification de programme¶

La liste des modèles de notification de programme peut être récupérée à l'aide de la méthode GET.

GET /api/programNotificationTemplates

Pour un modèle particulier de notification de programme.

GET /api/33/programNotificationTemplates/{uid}

Pour obtenir une liste filtrée des Modèles de notification de programme

GET /api/programNotificationTemplates/filter?program=<uid>
GET /api/programNotificationTemplates/filter?programStage=<uid>

Le Modèle de notification de programme peut être supprimé à l'aide de la méthode DELETE.

DELETE /api/33/programNotificationTemplates/{uid}

Messages de programme¶

"Message de programme" vous permet d'envoyer des messages à des instances d'entités suivies, à des adresses associées à des unités d'organisation, à des numéros de téléphone et à des adresses électroniques. Vous pouvez envoyer des messages via la ressource messages.

/api/33/messages

Envoi de messages de programme¶

Les messages de programme peuvent être envoyés à l'aide de deux canaux :

• SMS (SMS)

• Adresse électronique (EMAIL)

Les messages de programme peuvent être envoyés à différents destinataires :

• Instance d'entité suivie : Le système recherchera les attributs de type PHONE_NUMBER ou EMAIL (en fonction des canaux spécifiés) et utilisera les valeurs d'attribut correspondantes.

• Unité d'organisation : Le système utilisera le numéro de téléphone ou l'adresse électronique enregistrés pour l'unité d'organisation.

• Liste de numéros de téléphone : Le système utilisera les numéros de téléphone définis.

• Liste d'adresses électroniques : Le système utilisera les adresses électroniques définies.

Vous trouverez ci-dessous un exemple de charge JSON pour l'envoi de messages à l'aide de requêtes POST. Notez que la ressource "message" accepte un objet enveloppeur nommé programMessages, qui peut contenir un nombre quelconque de messages de programme.

POST /api/33/messages

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

Les champs sont expliqués dans le tableau suivant.

Tableau : Charge du message de programme

Voici un exemple minimaliste d'envoi de message par SMS à une instance d'entité suivie :

curl -d @message.json "https://play.dhis2.org/demo/api/33/messages"
  -H "Content-Type:application/json" -u admin:district

{
  "programMessages": [{
    "recipients": {
      "trackedEntityInstance": {
        "id": "PQfMcpmXeFE"
      }
    },
    "programInstance": {
      "id": "JMgRZyeLWOo"
    },
    "deliveryChannels": [
      "SMS"
    ],
    "text": "Please make a visit on Thursday"
  }]
}

Récupération et suppression des messages de programme¶

La liste des messages peut être récupérée à l'aide de la méthode GET.

GET /api/33/messages

Pour obtenir la liste des messages Tracker envoyés, le point d'extrémité ci-dessous peut être utilisé. L'uid de l'instance de programme ou de l'instance d'étape de programme doit être fourni.

GET /api/33/messages/scheduled/sent?programInstance={uid}
GET /api/33/messages/scheduled/sent?programStageInstance={uid}

Pour obtenir la liste de tous les messages planifiés

GET /api/33/messages/scheduled
GET /api/33/messages/scheduled?scheduledAt=2020-12-12

Un message spécifique peut également être récupéré à l'aide de la méthode GET.

GET /api/33/messages/{uid}

Un message peut être supprimé à l'aide de la méthode DELETE.

DELETE /api/33/messages/{uid}

Requête pour des messages de programme¶

L'API des messages de programme prend en charge les requêtes de messages de programme en utilisant des paramètres de requête. Les messages peuvent être filtrés en fonction des paramètres de requête mentionnés ci-dessous. Toutes les requêtes doivent utiliser la méthode GET HTTP pour récupérer les informations.