Metadata¶

Schémas d'identification¶

Cette section explique le concept de schéma d'identification. Les schémas d'identification sont utilisés pour relier des objets de métadonnées à d'autres métadonnées lors de l'importation et également pour restituer les métadonnées lors des exportations. Tous les schémas ne fonctionnent pas avec tous les appels d'API, et tous les schémas ne peuvent pas être utilisés à la fois pour les entrées et les sorties. Cet aspect est abordé dans les sections où sont expliqués les différents points d'extrémité d'API.

Tous les types d'objets disponibles pour le schéma d'identification sont énumérés ci-dessous. Sont fournis les noms des propriétés à utiliser dans les requêtes :

• idScheme
• dataElementIdScheme (Schéma d'identifiant d'élément de données)
• categoryOptionComboIdScheme (Schéma de l'identifiant de la combinaison d'options de catégorie)
• orgUnitIdScheme (Schéma de l'identifiant de l'unité d'organisation)
• programIdScheme (Schéma d'identification du programme)
• programmeStageIdScheme (Schéma d'identification de l'étape de programme)
• trackedEntityIdScheme (schéma d'identification de l'entité suivie)
• trackedEntityAttributeIdScheme (schéma d'identification de l'attribut d'entité suivie)

Le schéma d'identification général (idScheme) s'applique à tous les types d'objets. Il peut être remplacé par des types d'objets spécifiques.

Le schéma par défaut pour tous les paramètres est UID (identifiants stables de DHIS2). Les schémas d'identification pris en charge sont décrits dans le tableau ci-dessous.

Tableau : Valeurs du schéma

Notez que les schémas d'identification ne constituent pas une fonctionnalité indépendante, mais ils doivent être utilisés en combinaison avec des ressources telles que l'importation de valeurs de données, l'importation de métadonnées et l'importation GeoJson.

Par exemple, pour spécifier CODE comme schéma d'identification général et le remplacer par UID pour le schéma d'identification de l'unité d'organisation, vous pouvez utiliser les requêtes suivantes :

?idScheme=CODE&orgUnitIdScheme=UID

Autre exemple, pour spécifier un attribut pour le schéma d'identification de l'unité d'organisation, un code pour le schéma d'identification de l'élément de données et utiliser le schéma d'identification par défaut UID pour tous les autres objets, vous pouvez utiliser les paramètres suivants :

?orgUnitIdScheme=ATTRIBUTE:j38fk2dKFsG&dataElementIdScheme=CODE

Navigation dans l'API Web¶

Le point d'entrée pour naviguer dans l'API Web est /api. Cette ressource fournit des liens vers toutes les ressources disponibles. Quatre formats de représentation sont systématiquement disponibles pour toutes les ressources : HTML, XML, JSON et JSONP. D'autres formats sont disponibles pour des ressources comme MS Excel, PDF, CSV et PNG. Pour explorer l'API à partir d'un navigateur web, accédez au point d'entrée /api et suivez les liens vers la ressource que vous recherchez, par exemple /api/dataElements. Pour toutes les ressources qui renvoient une liste d'éléments, certains paramètres de requête peuvent être utilisés pour modifier la réponse :

Tableau : Paramètres de requête

Voici un exemple de comment ces paramètres peuvent être utilisés pour obtenir une liste complète de groupes d'éléments de données dans un format de réponse XML :

/api/dataElementGroups.xml?links=false&paging=false

Vous pouvez rechercher des éléments à partir de la propriété "nom" au lieu de renvoyer toute une liste d'éléments à l'aide de la variable de requête query. Dans cet exemple, nous recherchons tous les éléments de données dont le nom contient le mot "anémie" :

/api/dataElements?query=anaemia

Vous pouvez obtenir des pages spécifiques et des tailles de page pour des objets en utilisant la requête suivante :

/api/dataElements.json?page=2&pageSize=20

Vous pouvez désactiver complètement la pagination à l'aide de cette requête :

/api/indicatorGroups.json?paging=false

Pour que le résultat soit ordonné selon une propriété spécifique :

/api/indicators.json?order=shortName:desc

Pour que le résultat soit d'abord ordonné selon la propriété créée "date et heure" (ordre décroissant), puis selon la propriété "nom" (ordre croissant) :

/api/indicators.json?order=created:desc,name:asc

La ressource identifiableObjects vous permet de rechercher tout objet à partir de son identifiant, quel que soit son type :

/api/identifiableObjects/<id>

Traduction¶

DHIS2 propose des traductions pour le contenu de la base de données, notamment les éléments de données, les indicateurs et les programmes. Tous les objets de métadonnées qui figurent dans l'API Web ont des propriétés destinées à être utilisées pour l'affichage et l'interface utilisateur. Il s'agit entre autres de displayName (nom d'affichage), displayShortName (nom d'affichage court), displayDescription (description de l'affichage) et displayFormName (nom du formulaire d'affichage). Ces propriétés sont utilisées pour les éléments de données et les attributs d'entités suivies.

Tableau : Options de traduction

API de traduction¶

Les traductions d'un objet sont rendues comme faisant partie de l'objet lui-même dans le tableau traductions. Le tableau traductions qui figure dans les charges JSON/XML est normalement préfiltré pour vous, ce qui signifie qu'il ne peut pas être utilisé directement pour importer/exporter des traductions (car cela aurait pour effet de remplacer les langues autres que celles des utilisateurs actuellement connectés).

Exemple d'élément de données dont le tableau de traduction est filtré sur la langue de l'utilisateur :

{
  "id": "FTRrcoaog83",
  "displayName": "Accute French",
  "translations": [
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    }
  ]
}

Exemple d'élément de données dont les traductions sont désactivées :

{
  "id": "FTRrcoaog83",
  "displayName": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
  "translations": [
    {
      "property": "FORM_NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "Accute Flaccid Paral"
    },
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "DESCRIPTION",
      "locale": "en_FK",
      "value": "aa"
    }
  ]
}

Notez que même si vous obtenez un résultat non filtré, et que vous utilisez le type de point d'extrémité approprié, c'est-à-dire /api/dataElements, nous n'autorisons pas les mises à jour, car cela pourrait facilement entraîner des erreurs et remplacer les autres langues disponibles.

Pour lire et mettre à jour les traductions, vous pouvez utiliser le point d'extrémité spécial "traductions" pour chaque ressource d'objet. Vous pouvez y accéder en utilisant GET ou PUT sur le point d'extrémité /api/<object-type>/<object-id>/translations approprié.

Par exemple, pour un élément de données dont l'identifiant est FTRrcoaog83, vous pouvez utiliser /api/dataElements/FTRrcoaog83/translations pour obtenir les traductions et les mettre à jour. Les champs disponibles sont property avec les options NOM, NOM_COURT, NOM DU_FORMULAIRE, DESCRIPTION, locale qui prend en charge tout ID de langue valide et la propriété traduite value.

Exemple de propriété NOM pour la langue française :

{
  "property": "NAME",
  "locale": "fr",
  "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
}

Cette charge est ensuite ajoutée à un tableau de traduction et renvoyée au point d'extrémité approprié :

{
  "translations": [
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
    }
  ]
}

Pour un élément de données dont l'ID est FTRrcoaog83, vous pouvez effectuer une requête PUT comme suit : /api/dataElements/FTRrcoaog83/translations. Assurez-vous d'envoyer toutes les traductions disponibles pour cet objet et pas seulement pour une langue (sinon vous risquez de remplacer les langues existantes par d'autres langues).

Le code de statut sera 204 No Content si la valeur de données a été sauvegardée ou mise à jour avec succès, ou 404 Not Found si une erreur de validation s'est produite (par exemple, plus d'un NOM_COURT pour la même langue).

Versions de l'API Web¶

The Web API /api can be used with a DHIS2 version number, example:

/api/42/dataElements

Versions 28-43 are supported. Calling an endpoint with or without a version does not change the behaviour of the API. The behaviour is the same no matter which approach is used. We aim to remove supporting API calls with versions, so please use API calls without the use of a version number.
The support for using versions is due to legacy design, which didn't evolve as originally envisioned.

Filtre sur les objets de métadonnées¶

Pour filtrer les métadonnées, plusieurs opérations de filtrage peuvent être appliquées à la liste de métadonnées renvoyée. Le format du filtre lui-même est simple et suit le modèle propriété:opérateur:valeur, où propriété est la propriété des métadonnées sur lesquelles vous voulez effectuer le filtrage, opérateur est l'opérateur de comparaison que vous voulez utiliser et valeur est la valeur à vérifier (tous les opérateurs ne requièrent pas de valeur).

Veuillez consulter la section schéma pour savoir quelles propriétés sont disponibles. En plus des propriétés listées, les filtres peuvent s'appliquer à des valeurs d'attributs personnalisés où l'ID de l'attribut est utilisé comme nom de propriété.

Le filtrage récursif, c'est-à-dire le filtrage sur des objets associés ou une collection d'objets, est également possible.

Tableau : Opérateurs disponibles

Les opérateurs sont appliqués sous la forme d'une requête logique et. Si vous avez besoin d'une requête ou, vous pouvez consulter le filtre dans et la section ci-dessous. Le mécanisme de filtrage permet la récursivité. Des exemples sont donnés ci-dessous.

Obtenir des éléments de données avec la propriété ID1 ou ID2 :

/api/dataElements?filter=id:eq:ID1&filter=id:eq:ID2

Get data elements, ignoring case, with name property MyDataElement:

/api/dataElements?filter=name:ieq:mydataelement

Obtenir tous les éléments de données qui ont un ensemble de données avec l'identifiant ID1 :

/api/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

Obtenir tous les éléments de données avec l'opérateur d'agrégation somme et le type de valeur int :

/api/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

Vous pouvez effectuer un filtrage à l'intérieur des collections. Par exemple, pour obtenir les éléments de données qui font partie du groupe d'éléments de données * CPN*, vous pouvez utiliser la requête suivante en utilisant la propriété d'identification (id) des groupes d'éléments de données qui lui sont associés :

/api/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

Pour obtenir des éléments de données ayant une valeur d'attribut particulière pour un attribut de métadonnées, un filtre peut être spécifié pour l'ID de l'attribut et la valeur de l'attribut en utilisant la même syntaxe que celle de la requête de collection :

/api/dataElements.json?filter=attributeValues.attribute.id:eq:n2xYlNbsfko&filter=attributeValues.value:eq:AFP

Obtenir les éléments de données pour lesquels une option a été définie :

/api/dataElements?filter=optionSet:!null

Étant donné que tous les opérateurs sont and par défaut, vous ne pouvez pas trouver un élément de données correspondant à plus d'un identifiant. Pour ce faire, vous pouvez utiliser l'opérateur in.

/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

Opérateurs logiques¶

Comme indiqué dans la section précédente, l'opérateur logique par défaut appliqué aux filtres est AND, ce qui signifie que tous les filtres d'objets doivent trouver une correspondance. Cependant, dans certains cas, l'utilisateur peut vouloir utiliser un seul filtre parmi plusieurs (par exemple le champ de l'identifiant et du code). Dans ce cas, il est possible de changer l'opérateur logique racine de AND à OR à l'aide du paramètre rootJunction.

Exemple : Filtrage normal où l'identifiant et le code doivent trouver une correspondance pour que le résultat soit renvoyé.

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

Exemple : Filtrage où l'opérateur logique a été remplacé par "OR", ce qui fait qu'un seul des filtres doit trouver une correspondance pour que le résultat soit renvoyé.

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR

Filtre à jeton identifiable¶

Outre le filtrage spécifique basé sur les propriétés mentionné ci-dessus, nous disposons également d'un filtrage AND basé sur les jetons à travers un ensemble de propriétés : identifiant, code et nom (ainsi que 'nom court' s'il est disponible). Ces propriétés sont généralement appelées identifiables. L'idée est de filtrer les métadonnées dont l'identifiant, le nom, le code ou le nom court contiennent des informations.

Exemple : Filtrage de tous les éléments de données contenant 2^nd dans l'un des éléments suivants : identifiant, nom, code et nom court.

/api/dataElements.json?filter=identifiable:token:2nd

Il est également possible de spécifier plusieurs valeurs de filtrage.

Exemple : Obtenir tous les éléments de données où ANC visit (visite de CPN) se trouve dans l'une des propriétés identifiables. Le système renvoie tous les éléments de données dans lesquels les deux unités lexicales (ANC et visit) se trouvent quelque part dans les propriétés identifiables.

/api/dataElements.json?filter=identifiable:token:ANC visit

Il est également possible de combiner le filtre identifiable avec le filtre basé sur les propriétés et de s'attendre à ce que le paramètre rootJunction soit appliqué.

/api/dataElements.json?filter=identifiable:token:ANC visit&filter=displayName:ilike:tt1

/api/dataElements.json?filter=identifiable:token:ANC visit
  &filter=displayName:ilike:tt1&rootJunction=OR

Filtre de champ de métadonnées¶

Dans de nombreuses situations, les visualisations par défaut des métadonnées peuvent être trop détaillées. Un client peut juste avoir besoin de quelques champs de chaque objet et vouloir supprimer les champs inutiles de la réponse. Pour connaître les champs disponibles pour chaque objet, veuillez consulter la section schéma. En plus des propriétés énumérées, il est possible d'inclure des attributs personnalisés pour les objets de premier niveau en utilisant l'identifiant de l'attribut comme nom de propriété.

Le format inclure/exclure permet une récursivité illimitée. Pour effectuer un filtrage au niveau de la "racine", vous pouvez simplement utiliser le nom du champ, c'est-à-dire ?fields=id,name qui n'affichera que les champs idendifiant et nom pour chaque objet. Pour les objets qui sont soit des collections, soit des objets complexes avec des propriétés indépendantes, vous pouvez utiliser le format ?fields=id,name,dataSets[id,name] qui renverra l'identifiant, le nom de la racine, ainsi que l'identifiant et le nom de chaque ensemble de données sur cet objet. Vous pouvez effectuer une négation à l'aide de l'opérateur d'exclamation, et nous disposons de paramètres prédéfinis pour la sélection des champs. Les formats XML et JSON sont acceptés.

Exemple : Obtenir l'id et le nom à partir de la ressource d'indicateurs :

/api/indicators?fields=id,name

Exemple : Obtenir l'id et le nom des éléments de données, et l'id et le nom des ensembles de données associés :

/api/dataElements?fields=id,name,dataSets[id,name]

Exemple : Obtenir l'id, le nom et la valeur d'un attribut défini par l'utilisateur avec l'ID DnrLSdo4hMl, pour les unités d'organisation :

/api/organisationUnits?fields=id,name,DnrLSdo4hMl

L'attribut est alors inclus en tant que propriété DnrLSdo4hMl de chaque objet correspondant dans la réponse. Il peut être renommé à l'aide du transformateur rename (renommer) tel que présenté dans la section suivante.

Pour exclure un champ de la sortie, vous pouvez utiliser l'opérateur d'exclamation !. Ceci est autorisé à n'importe quel emplacement dans la requête et cette propriété ne sera pas incluse tout simplement car elle pourrait avoir été insérée dans des paramètres prédéfinis.

Quelques paramètres prédéfinis (groupes de champs sélectionnés) sont disponibles et peuvent être appliqués à l'aide de l'opérateur :.

Tableau : Opérateurs de propriété

Tableau : Paramètres prédéfinies des champs

Exemple : Inclure tous les champs des ensembles de données à l'exception des unités d'organisation :

/api/dataSets?fields=:all,!organisationUnits

Exemple : Inclure uniquement l'identifiant, le nom et la collection d'unités d'organisation d'un ensemble de données, mais exclure l'identifiant des unités d'organisation :

/api/dataSets/BfMAe6Itzgt?fields=id,name,organisationUnits[:all,!id]

Exemple : Inclure les propriétés nommables de tous les indicateurs :

/api/indicators.json?fields=:nameable

Transformateurs de champ¶

Les transformations de champs peuvent être utilisées pour transformer des propriétés. La syntaxe est décrite ci-dessous.

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

La propriété id sera renommée i et la propriété name sera renommée n.

Plusieurs transformateurs peuvent être appliqués à une même propriété. Pour ce faire, il suffit de répéter l'opérateur de transformation :

/api/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements)

Les opérateurs de transformation pris en charge sont décrits dans le tableau ci-dessous.

Tableau : Transformateurs disponibles

Exemples¶

Des exemples d'utilisation de transformateurs sont présentés ci-dessous.

Obtenir la taille d'une collection :

/api/dataElements?fields=dataSets~size

Teste si une collection est vide :

/api/dataElements?fields=dataSets~isEmpty

Teste si une collection n'est pas vide :

/api/dataElements?fields=dataSets~isNotEmpty

Renommer les propriétés :

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

Appliquer la pagination à une collection :

/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)

Obtenir un tableau contenant les identifiants des unités d'organisation :

/api/categoryOptions.json?fields=id,organisationUnits~pluck

Obtenir un tableau contenant les noms des unités d'organisation :

/api/categoryOptions.json?fields=id,organisationUnits~pluck[name]

Key the dataElements array by the id field:

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy[id,name,valueType]

Key the dataElements array by the valueType field, since multiple hits this will results in arrays (of data elements):

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy(valueType)[id,name,valueType]

Création, lecture, mise à jour, suppression et validation de métadonnées¶

Toutes les entités de métadonnées dans DHIS2 ont leur propre endpoint API qui prend en charge les opérations CRUD (création, lecture, mise à jour et suppression). Les URL des endpoints suivent le format suivant :

/api/<entityName>

Le nom de l'entité utilise la notation camel case. Par exemple, le endpoint pour les éléments de données est :

/api/dataElements

NOTE: Lors de la mise à jour des objets, toutes les valeurs des propriétés existantes seront écrasées, même si la nouvelle valeur est nulle. Veuillez utiliser l'API de patch JSON si vous souhaitez effectuer une mise à jour partielle d'un objet.

Création et mise à jour des paramètres¶

Les paramètres de requête suivants sont disponibles pour tous les endpoints de métadonnées.

Tableau : Filtres de requête disponibles

Création et mise à jour d'objets¶

Pour créer de nouveaux objets, vous devrez connaître le endpoint, le format du type d'objet et vous assurer que vous disposez des autorisations nécessaires. À titre d'exemple, nous allons créer et mettre à jour une constante. Pour connaître le format, nous pouvons utiliser le nouveau endpoint schema pour obtenir la description du format. Nous allons donc commencer par l'obtention de cette information :

http://<server>/api/schemas/constant.json

À partir de la sortie, vous pouvez voir que les autorités requises pour la création sont F_CONSTANT_ADD, et que les propriétés importantes sont : name et value. En nous basant sur ces informations, nous pouvons créer une charge JSON et la sauvegarder dans un fichier appelé constant.json :

{
  "name": "PI",
  "value": "3.14159265359"
}

Pour avoir le même contenu qu'une charge XML :

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

Nous sommes maintenant prêts à créer la nouvelle constante en envoyant une requête POST au point d'extrémité constantes avec la charge JSON, en utilisant le curl :

curl -d @constant.json "http://server/api/constants" -X POST
  -H "Content-Type: application/json" -u user:password

Exemple concret d'envoi de la constante au serveur de démonstration :

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

Si tout s'est bien passé, vous devriez obtenir le résultat suivant :

{
  "status": "SUCCESS",
  "importCount": {
    "imported": 1,
    "updated": 0,
    "ignored": 0,
    "deleted": 0
  },
  "type": "Constant"
}

Le processus sera exactement le même pour la mise à jour, vous apportez vos modifications à la charge JSON/XML, vous trouvez l'ID de la constante, puis vous envoyez une requête PUT au endpoint en incluant l'ID :

curl -X PUT -d @pi.json -H "Content-Type: application/json"
  -u user:password "http://server/api/constants/ID"

Suppression d'objets¶

La suppression d'objets est très simple. Vous devez connaître l'ID et le endpoint du type d'objet que vous voulez supprimer. Reprenons l'exemple de la dernière section et utilisons une constante. Supposons que l'identifiant soit abc123, tout ce que vous avez à faire est d'envoyer la requête DELETE au endpoint + id :

curl -X DELETE -u user:password "http://server/api/constants/ID"

Une suppression réussie doit renvoyer le statut HTTP 204 (pas de contenu).

Ajout et suppression d'objets dans les collections¶

La ressource des collections vous permet de modifier des collections d'objets.

Ajout ou suppression d'objets uniques{ #webapi_collections_adding_removing_single_objects }¶

Pour ajouter ou supprimer des objets dans une collection d'objets, vous pouvez utiliser le modèle suivant :

/api/{collection-object}/{collection-object-id}/{collection-name}/{object-id}

Vous devez utiliser la méthode POST pour ajouter un objet et la méthode DELETE pour le supprimer. Lorsqu'il existe une relation entre plusieurs objets, vous devez d'abord déterminer quel objet est propriétaire de la relation. Si cet objet n'est pas clairement identifiable, essayez les deux méthodes d'appel pour voir laquelle fonctionne.

Les éléments du modèle sont les suivants :

• objet de collection : Le type d'objets qui possède la collection que vous voulez modifier.

• id de l'objet de collection : L'identifiant de l'objet qui possède la collection que vous voulez modifier.

• nom de la collection : le nom de la collection que vous voulez modifier.

• Identifiant d'objet : L'identifiant de l'objet que vous voulez ajouter ou supprimer de la collection.

Par exemple, pour supprimer un élément de données avec pour identifiant IDB d'un groupe d'éléments de données dont l'identifiant est IDA, vous pouvez effectuer une requête DELETE :

DELETE /api/dataElementGroups/IDA/dataElements/IDB

Pour ajouter une option de catégorie avec pour identifiant IDB à une catégorie dont l'identifiant est IDA, vous pouvez effectuer une requête POST :

POST /api/categories/IDA/categoryOptions/IDB

Ajout ou suppression de plusieurs objets¶

Vous pouvez ajouter ou supprimer plusieurs objets d'une collection dans une même requête, en utilisant la charge suivante :

{
  "identifiableObjects": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ]
}

Cette charge permet d'ajouter, de remplacer ou de supprimer des éléments :

Ajouter des éléments :

POST /api/categories/IDA/categoryOptions

Remplacer des éléments :

PUT /api/categories/IDA/categoryOptions

Supprimer des éléments :

DELETE /api/categories/IDA/categoryOptions

Ajout et suppression d'objets dans une même requête¶

Vous pouvez ajouter et supprimer des objets d'une collection dans une même requête POST, en utilisant l'URL suivante :

POST /api/categories/IDA/categoryOptions

Le format de la charge est le suivant :

{
  "additions": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ],
  "deletions": [{
      "id": "IDD"
    }, {
      "id": "IDE"
    }, {
      "id": "IDF"
    }
  ]
}

Validation des charges¶

DHIS 2 permet de valider des métadonnées à l'échelle du système, ce qui signifie que les opérations de création et de mise à jour sur les points d'extrémité d'API devront être valides avant que les modifications ne soient autorisées. Pour connaître les validations disponibles pour un point d'extrémité spécifique, consultez ce point d'extrémité : /api/schemas. C'est-à-dire que pour connaître les contraintes d'un élément de données, vous devez vous rendre dans /api/schemas/dataElement.

Vous pouvez également valider votre charge manuellement en l'envoyant au endpoint du schéma approprié. Si vous vouliez valider la constante dans la section de création précédente, vous devriez l'envoyer comme ceci :

POST /api/schemas/constant

Voici un exemple simple (sans validation) :

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/schemas/dataElement"

Ce qui donnera le résultat suivant :

[
   {
      "message" : "Required property missing.",
      "property" : "type"
   },
   {
      "property" : "aggregationOperator",
      "message" : "Required property missing."
   },
   {
      "property" : "domainType",
      "message" : "Required property missing."
   },
   {
      "property" : "shortName",
      "message" : "Required property missing."
   }
]

Mises à jour partielles¶

Nos points d'extrémité d'API qui traitent les métadonnées permettent des mises à jour partielles (PATCH) à l'aide du patch JSON [standard] (https://tools.ietf.org/html/rfc6902). La charge décrit essentiellement un ensemble d'opérations que vous voulez appliquer à un objet de métadonnées existant. Pour plus de détails et d'exemples sur le patch JSON, voir jsonpatch.com. Trois opérateurs sont pris en charge : add, remove et replace (ajouter, supprimer et remplacer).

Vous trouverez ci-dessous quelques exemples concernant DHIS2. Notez que toute mise à jour d'une charge doit être considérée comme une opération HTTP PUT, c'est-à-dire que toute modification doit aboutir à une charge de métadonnées PUT valide.

Le importReportMode (mode de rapport d'importation) par défaut pour le patch JSON est ERRORS_NOT_OWNER, ce qui signifie que si vous essayez de mettre à jour une propriété qui n'appartient pas à l'objet traité (par exemple si vous essayez d'ajouter un groupe d'indicateurs directement à un indicateur), vous obtiendrez une erreur.

Conformément à la spécification des patchs JSON, vous devez toujours utiliser le type MIME application/json-patch+json lorsque vous envoyez des patchs.

Exemples¶

Mise à jour du nom et du type de valeur d'un élément de données¶

PATCH /api/dataElements/{id}

[
  {"op": "add", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/valueType", "value": "INTEGER"}
] 

Ajout d'un nouvel élément de données à un groupe d'éléments de données¶

PATCH /api/dataElementGroups/{id}

[
  {"op": "add", "path": "/dataElements/-", "value": {"id": "data-element-id"}}
]

Suppression de toutes les associations d'éléments de données d'un groupe d'éléments de données¶

PATCH /api/dataElementGroups/{id}

[
  {"op": "remove", "path": "/dataElements"}
]

Modification du domaine et du type de valeur d'un élément de données¶

PATCH /api/dataElements/{id}

[
    {"op": "add", "path": "/domainType", "value": "TRACKER"},
    {"op": "add", "path": "/valueType", "value": "INTEGER"}
]

Suppression d'une unité d'organisation spécifique d'un groupe d'unité d'organisation¶

PATCH /api/organisationUnitGroups/{id}

[
  {"op": "remove", "path": "/organisationUnits/1"}
]

Blocage de l'ajout d'un groupe d'éléments de données à élément de données¶

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "add", "path": "/dataElementGroups/-", "value": {"id": "data-element-group-id"}}
]

Blocage de la mise à jour du nom du groupe d'élément =s de données dans l'élément de données¶

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "add", "path": "/dataElementGroups/0", "value": {"name": "new-name"}}
]

Remove collection item by id¶

PATCH /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/organisationUnits", "id": "u6CvKyF0Db5"}
]

Demande de patch avec avec un chemin d'accès invalide¶

Si la propriété path (chemin d'accès) est invalide ou n'existe pas, le service de patchs renvoie une erreur comme dans l'exemple suivant

PATCH /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/test", "id": "u6CvKyF0Db5"}
]

{
    "httpStatus": "Bad Request",
    "httpStatusCode": 400,
    "status": "ERROR",
    "message": "Invalid path /test"
}

Exportation des métadonnées par CSV{ #webapi_metadata_csv_export }¶

Le filtrage des champs fonctionne presque de la même manière pour le CSV (notez que l'utilisation du CSV sur le point d'extrémité /api/metadata n'est pas possible), mais la transformation des champs n'est pas encore prise en charge.

Pour les points d'extrémité qui acceptent le CSV (par exemple nos points d'extrémité de métadonnées /api/dataElements et /api/organisationUnits), vous pouvez soit utiliser l'en-tête Accept avec la valeur text/csv ou utiliser l'extension .csv. Sachez que nous ne prenons pas en charge les objets complexes, seulement les collections d'objets avec identifiant (une liste d'UID sera donc renvoyée).

Exemples¶

Obtenir tous les éléments de données, y compris leurs groupes¶

/api/dataElements.csv?fields=id,displayName,dataElementGroups

Obtenir toutes les unités d'organisation, y compris la géométrie (qui sera ignorée)¶

/api/organisationUnits.csv?fields=id,displayName,organisationUnitGroups,geometry

Exportation de métadonnées¶

Cette section décrit l'API de métadonnées qui est disponible ici : /api/metadata. Les représentations des ressources XML et JSON sont prises en charge.

/api/metadata

Les paramètres les plus courants sont décrits dans le tableau "Paramètres d'exportation" ci-dessous. Vous pouvez également appliquer ceci à tous les types disponibles en utilisant type:fields=<filter> et type:filter=<filter>. Vous pouvez également activer/désactiver l'exportation de certains types à travers ceci : type=true|false.

Exemples d'exportation de métadonnées¶

Exporter toutes les métadonnées. Attention, la réponse peut être très volumineuse en fonction de la configuration des métadonnées :

/api/metadata

Exporter toutes les métadonnées classées par ordre décroissant en prenant en compte la dernière mise à jour :

/api/metadata?defaultOrder=lastUpdated:desc

Exporter uniquement les métadonnées qui contiennent des indicateurs et des groupes d'indicateurs :

/api/metadata?indicators=true&indicatorGroups=true

Exporter l'identifiant et le nom d'affichage de tous les éléments de données, classés par nom d'affichage :

/api/metadata?dataElements:fields=id,name&dataElements:order=displayName:desc

Exporter les éléments de données et les indicateurs dont le nom commence par "ANC" (CPN en français):

/api/metadata?filter=name:^like:ANC&dataElements=true&indicators=true

Exportation de métadonnées avec des dépendances¶

Lorsque vous voulez échanger des métadonnées avec un ensemble de données, un programme, une combinaison de catégories, un tableau de bord, un ensemble d'options ou un groupe d'éléments de données, d'une instance DHIS2 à une autre, six points d'extrémité sont disponibles à cet effet :

/api/dataSets/{id}/metadata.json

/api/programs/{id}/metadata.json

/api/categoryCombos/{id}/metadata.json

/api/dashboards/{id}/metadata.json

/api/optionSets/{id}/metadata.json

/api/dataElementGroups/{id}/metadata.json

Ces éléments exportés peuvent ensuite être importés en utilisant ceci /api/metadata.

Ces endpoints prennent également en charge les paramètres suivants :

Importation de métadonnées¶

Cette section décrit l'API d'importation des métadonnées. Les représentations des ressources XML et JSON sont prises en charge. Les métadonnées peuvent être importées à l'aide d'une requête POST.

/api/metadata

L'importateur vous permet d'importer des charges de métadonnées qui peuvent inclure plusieurs entités et un nombre quelconque d'objets par entité. Les éléments de métadonnées exportés via l'API d'exportation de métadonnées peuvent être importés directement.

Le endpoint de l'importation des métadonnées prend en charge une variété de paramètres, énumérés ci-dessous.

Tableau : Paramètres d'importation

REMARQUE Lors de la mise à jour des objets, toutes les valeurs des propriétés seront écrasées même si les nouvelles valeurs sont null. Veuillez utiliser JSON Patch API si vous voulez effectuer une mise à jour partielle d'un objet.

Voici un exemple de charge d'importation de métadonnées. Vous remarquerez que chaque type d'entité possède sa propre propriété avec un tableau d'objets :

{
  "dataElements": [
    {
      "name": "EPI - IPV 3 doses given",
      "shortName": "EPI - IPV 3 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    },
    {
      "name": "EPI - IPV 4 doses given",
      "shortName": "EPI - IPV 4 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    }
  ],
  "indicators": [
    {
      "name": "EPI - ADS stock used",
      "shortName": "ADS stock used",
      "numerator": "#{LTb8XeeqeqI}+#{Fs28ZQJET6V}-#{A3mHIZd2tPg}",
      "numeratorDescription": "ADS 0.05 ml used",
      "denominator": "1",
      "denominatorDescription": "1",
      "annualized": false,
      "indicatorType": {
        "id": "kHy61PbChXr"
      }
    }
  ]
}

Lors de l'envoi de cette charge au endpoint des métadonnées, la réponse contiendra des informations sur les paramètres utilisés lors de l'importation et un récapitulatif par type d'entité, lequel contiendra le nombre d'objets créés, mis à jour, supprimés et ignorés :

{
  "importParams": {
    "userOverrideMode": "NONE",
    "importMode": "COMMIT",
    "identifier": "UID",
    "preheatMode": "REFERENCE",
    "importStrategy": "CREATE_AND_UPDATE",
    "atomicMode": "ALL",
    "flushMode": "AUTO",
    "skipSharing": false,
    "skipTranslation": false,
    "skipValidation": false,
    "metadataSyncImport": false,
    "firstRowIsHeader": true,
    "username": "UNICEF_admin"
  },
  "status": "OK",
  "typeReports": [
    {
      "klass": "org.hisp.dhis.dataelement.DataElement",
      "stats": {
        "created": 2,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 2
      }
    },
    {
      "klass": "org.hisp.dhis.indicator.Indicator",
      "stats": {
        "created": 1,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 1
      }
    }
  ],
  "stats": {
    "created": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0,
    "total": 3
  }
}

GeoJSON import¶

L'importation GeoJSON est utilisée pour relier les données géométriques aux unités d'organisation.

Pour une importation en masse, il faut un fichier GeoJSON avec une collection d'éléments. Chaque élément de la collection a besoin d'une référence à l'unité d'organisation à laquelle il doit être relié.

Par défaut, la géométrie du fichier est stockée en tant que propriété geometry d'une unité d'organisation. Pour stocker des géométries supplémentaires, des attributs de type GEOJSON peuvent être créés. Lorsque des attributs sont utilisés, toutes les géométries d'un fichier sont stockées pour le même attribut qui est fourni avec un paramètre supplémentaire attributeId.

Importation de données en masse avec GeoJSON¶

Tableau : Paramètres d'importation

Uasge:

POST /api/organisationUnits/geometry

Le corps du message est le fichier GeoJSON. Le type de contenu doit être application/json ou application/geo+json. Le fichier peut être compressé en .zip ou .gzip.

Par exemple, un fichier par défaut dans lequel id est utilisé pour faire référence à l'identifiant d'une unité d'organisation a la structure suivante :

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "O6uvpzGd5pu",
      "geometry": { ... }
    },
    ...
  ]
}

Un fichier dans lequel une propriété d'élément est utilisée pour faire référence au code de l'unité d'organisation devrait avoir la structure suivante :

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "code": "OU1_CODE" },
      "geometry": { ... }
    },
    ...
  ]
}

Une geometry peut également être null pour effacer ou supprimer efficacement la géométrie pour des unités d'organisation spécifiques. Il existe une API spéciale de suppression en masse ; elle est décrite dans la section suivante.

Lorsqu'elle est exécutée de manière synchrone, un rapport d'importation est renvoyé directement. Le code de statut HTTP est toujours OK, le status dans le message indique si toutes les lignes ont été importées avec succès. Les statistiques sur le nombre de lignes importées, contenues dans le rapport donnent des informations supplémentaires :

• imported : nombre d'unités d'organisation qui ont été mises à jour avec succès avec une géométrie qui n'en avait pas pour la propriété mise à jour.
• updated : nombre d'unités d'organisation qui ont été mises à jour avec succès avec une géométrie qui avait déjà une valeur pour la propriété mise à jour.
• ignored : nombre d'unités d'organisation qui n'ont pas été mises à jour
• deleted : nombre d'unités d'organisation qui ont été mises à jour avec succès avec une géométrie vide.

Lorsque l'importation est exécutée de manière asynchrone, la requête renvoie immédiatement le statut OK de même que la réponse de configuration de la tâche qui contient une référence relative au point d'extrémité de la tâche qui permet de suivre le statut de l'importation asynchrone. Voici un exemple :

/api/system/tasks/GEOJSON_IMPORT/{job-id}

Le récapitulatif renvoyé directement pour une exécution synchrone est disponible à l'adresse suivante

/api/system/taskSummaries/GEOJSON_IMPORT/{job-id}

dès que l'importation est terminée.

Suppression de données en masse avec GeoJSON¶

Pour effacer ou désactiver les données geometry pour toutes les unités d'organisation, utilisez :

DELETE /api/organisationUnits/geometry

Pour effacer ou désactiver les données géométriques d'un attribut GEOJSON spécifique pour toutes les unités d'organisation :

DELETE /api/organisationUnits/geometry?attributeId={attr-id}

Le nettoyage se fait toujours de façon synchrone et renvoie un rapport similaire à celui de l'importation en masse. Il ne prend en charge aucun autre paramètre. Aucun essai ne peut être effectué. Pour effectuer un nettoyage en masse, l'utilisateur doit disposer de l'autorité F_PERFORM_MAINTENANCE.

Importation de données uniques avec GeoJSON¶

L'importation unique permet de mettre à jour la géométrie d'une seule unité d'organisation.

POST /api/organisationUnits/{id}/geometry

Le corps du message ne contient que la valeur GeoJSON geometry, par exemple :

{
  "type": "Polygon",
  "coordinates": [...]
}

Suppression de données uniques avec GeoJSON¶

Pour effacer les données GeoJSON de la géométrie d'une seule unité d'organisation, utilisez ceci :

DELETE /api/organisationUnits/{id}/geometry

De même, pour effacer une valeur d'attribut GEOJSON pour une seule unité d'organisation, utilisez ceci :

DELETE /api/organisationUnits/{id}/geometry?attributeId={attr-id}

Le nettoyage se fait toujours de manière synchrone et renvoie un rapport similaire à celui d'une importation simple. Le paramètre dry-run est également pris en charge. L'utilisateur qui effectue l'opération doit disposer de l'autorité qui lui permet de modifier l'unité d'organisation cible.

Schéma¶

Pour effectuer une introspection sur tous les objets DXF 2 disponibles, vous pouvez utiliser une ressource disponible à l'adresse /api/schemas. Pour obtenir des ressources spécifiques, vous pouvez consulter /api/schemas/<type>.

Pour obtenir tous les schémas disponibles au format XML :

GET /api/schemas.xml

Pour obtenir tous les schémas disponibles au format JSON :

GET /api/schemas.json

Pour obtenir le schéma JSON d'une classe spécifique :

GET /api/schemas/dataElement.json

Icônes¶

DHIS2 dispose d'une collection d'icônes qui peuvent être utilisées pour donner un contexte visuel aux métadonnées. Il existe deux types d'icônes : - Icônes par défaut : elles sont préinstallées dans l'application et ne peuvent ni être modifiées, ni être supprimées. - Icônes personnalisées : elles peuvent être créées, mises à jour et supprimées à volonté.

Ces deux types sont accessibles via la ressource "icônes".

GET /api/icons

Ce point d'extrémité renvoie une liste d'informations sur les icônes par défaut et les icônes personnalisées disponibles. Par défaut, la clé, la description, les mots-clés et la href sont inclus dans la réponse. Mais le paramètre "champs" peut être utilisé pour modifier ce comportement.

{
  key: "mosquito_outline",
  description: "Mosquito outline",
  keywords: [
    "malaria",
    "mosquito",
    "dengue"
  ],
  "created": "2024-02-12T09:50:11.794",
  "lastUpdated": "2024-02-12T09:50:11.794",
  href: "<dhis server>/api/icons/mosquito_outline/icon.svg"
}

Il est également possible d'obtenir directement une icône spécifique en la filtrant par sa clé. Dans l'exemple ci-dessous, la clé est mosquito_outline.

GET /api/icons/mosquito_outline

Opérations sur les icônes personnalisées¶

Une liste d'icônes personnalisées peut être récupérée sur la base de quelques paramètres de requête.

GET /api/icons?type=CUSTOM

Paramètres de requête pour la pagination¶

Paramètres de requête pour la mise en ordre{ #request-parameters-for-ordering }¶

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

Les points d'extrémité acceptent un paramètre fields 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 séparés par des virgules. Si rien n'est spécifié, les champs par défaut seront utilisés. Il s'agit de

key,keywords,description,fileResourceUid,createdByUserUid,href (clé, mots-clés, description, uid de la ressource du fichier, uid de la création par l'utilisateur, href)

Vous pouvez télécharger une ressource d'icône personnalisée en fournissant la clé d'icône suivante :

GET /api/icons/{key}/icon

Des icônes personnalisées peuvent être créées, modifiées et supprimées. Pour créer une icône personnalisée, utilisez la ressource ci-dessous.

POST /api/icons

Elle attend une charge contenant la clé de l'icône, la description, la liste des mots-clés et l'identifiant de la ressource du fichier à relier aux données.

{
    "key": "iconKey",
    "description": "description",
    "keywords": ["keyword 1","keyword 2"],
    "fileResourceUid": "ARsqBjfB2cf"
}

Seules les icônes personnalisées peuvent être mises à jour à l'aide de la ressource ci-dessous.

PUT /api/icons

La charge suivante permet de mettre à jour la description et les mots-clés de l'icône.

{
    "key": "iconKey",
    "description": "new description",
    "keywords": ["new keyword 1", "new keyword 2"] 
}

Il est également possible de ne mettre à jour qu'un seul des deux éléments. Cela signifie que si nous voulons mettre à jour la description tout en gardant les mots-clés tels qu'ils sont, nous n'aurons qu'à fournir la clé de l'icône et le champ json de la description. Le même procédé s'applique dans l'autre sens, si nous voulons mettre à jour les mots-clés et laisser la description initiale intacte.

Seules les icônes personnalisées peuvent être supprimées à l'aide de la ressource ci-dessous.

DELETE /api/icons/{icon_key}

Type de rendu¶

Certains types de métadonnées ont une propriété appelée renderType (type de rendu). Cette propriété établit une correspondance entre un appareil et un renderingType. Les applications peuvent utiliser ces informations pour savoir comment l'objet doit être rendu sur un appareil spécifique. Par exemple, le rendu d'un élément de données sur un appareil mobile peut être différent de celui d'un ordinateur de bureau.

Il existe actuellement deux types de rendu :

1. Rendu de type "valeur"

2. Rendu des sections d'étape de programme

Il existe également deux types d'appareils :

1. MOBILE

2. DESKTOP

Le tableau suivant énumère les métadonnées et les types de rendu disponibles. Le rendu de type valeur a des contraintes supplémentaires basées sur la configuration des métadonnées. Elles seront présentées dans un second tableau.

Tableau : Aperçu des métadonnées et des types de restitution

Étant donné que la gestion du rendu par défaut des éléments de données et des attributs d'entités suivies dépend du type de valeur de l'objet, il existe également un type DEFAULT qui permet d'indiquer au client qu'il doit être géré normalement. La section des étapes de programme est définie sur LISTING par défaut.

Tableau : Types de restitution autorisés en fonction des types de valeurs

Vous pouvez également récupérer une référence complète du tableau précédent en utilisant le point d'extrémité suivant :

GET /api/staticConfiguration/renderingOptions

Quelques propriétés supplémentaires peuvent être définies pour le rendu du type de valeur, ce qui est souvent nécessaire lors du rendu de certains types spécifiques :

Tableau : propriétés de l'objet renderType

Le type de rendu peut être défini lors de la création ou de la mise à jour des métadonnées énumérées dans le premier tableau. Voici un exemple de charge pour le type de rendu de la section des étapes de programme :

{
  "renderingType": {
    "type": "MATRIX"
  }
}

Pour les éléments de données et les attributs d'entités suivies :

{
  "renderingType": {
    "type": "SLIDER",
    "min": 0,
    "max": 1000,
    "step": 50,
    "decimalPoints": 0
  }
}

Style d'objet¶

La plupart des métadonnées ont une propriété "style". Cette propriété peut être utilisée par les clients pour représenter l'objet d'une certaine manière. Les propriétés actuellement prises en charge par le style sont les suivantes :

Tableau : Propriétés du style

Actuellement, il n'existe pas de liste officielle ni de bibliothèques d'icônes. Il revient donc au client de les fournir. La liste suivante présente tous les objets qui prennent en charge le style :

• Élément de données

• Option de catégorie d'éléments de données

• Ensemble de données

• Indicateur

• Option

• Programme

• Indicateur du programme

• Section du programme

• Étape du programme

• Section des étapes de programme

• Relation (Tracker)

• Attribut d’entité suivie

• Type d'entité suivie

Lors de la création ou de la mise à jour de l'un de ces objets, vous pouvez inclure la charge suivante pour modifier le style :

{
  "style": {
    "color": "#ffffff",
    "icon": "my-beautiful-icon"
  }
}

Category¶

Merge categories¶

The category merge endpoint allows you to merge a number of categories (sources) into a target category.

Note

Categories can only be merged when:

1. they have identical category options
   
2. source and target categories do not share category combos
   
3. source categories do not share category combos with each other
   

These constraints ensure only duplicate Categories can be merged, and it helps to keep system integrity.

Autorisation¶

The main authority required to perform a category merge is F_CATEGORY_MERGE.

Requête¶

Merge categories with a POST request:

POST /api/categories/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

The merge operation will merge the source categories into the target category. One or many source categories can be specified. Only one target should be specified.

The merge operation will transfer all source category metadata associations to the target category. The following metadata get updated:

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "Category",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "Category merge complete"
        }
    }
}

Failure¶

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source Category must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target Category does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "Category",
            "sourcesDeleted": [],
            "message": "Category merge has errors"
        }
    }
}

Category Option¶

Merge category options¶

The category option merge endpoint allows you to merge a number of category options (sources) into a target category option.

Autorisation¶

The main authority required to perform a category option merge is F_CATEGORY_OPTION_MERGE.
Other authorities required relate to the general sharing and access of category options, F_CATEGORY_OPTION_PUBLIC_ADD and F_CATEGORY_OPTION_DELETE.

Requête¶

Merge category options with a POST request:

POST /api/categoryOptions/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

The merge operation will merge the source category options into the target category option. One or many source category options can be specified. Only one target should be specified.

The merge operation will transfer all source category option metadata associations to the target category option. The following metadata get updated:

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "CategoryOption",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "CategoryOption merge complete"
        }
    }
}

Failure¶

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source CategoryOption must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target CategoryOption does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "CategoryOption",
            "sourcesDeleted": [],
            "message": "CategoryOption merge has errors"
        }
    }
}

Category Option Combo¶

Import Validation¶

CategoryOptionCombos are unique in that they are auto-generated by the system, most of the time (imports are allowed with specific expectations, mentioned below). They are generated based on their category model:
- CategoryOption - Category (has category options) - CategoryCombo (has categories)

There will be a CategoryOptionCombo created for each combination of Category CategoryOption.

Generated CategoryOptionCombo Example¶

• There is 1 CategoryCombo [CC1]
• CC1 has 2 Categories CC1=[C1, C2]
• Each Category has 2 CategoryOptions C1=[CO1, CO2], C2=[CO3, CO4]
• The Generated CategoryOptionCombos from this category model would produce 4 CategoryOptionCombos:
• COC1=[CO1, CO3]
• COC2=[CO1, CO4]
• COC3=[CO2, CO3]
• COC4=[CO2, CO4]

This is important to understand when trying to import CategoryOptionCombos. Validation is performed when importing CategoryOptionCombos to ensure that the provided set of CategoryOptionCombos matches the expected generated set of CategoryOptionCombos. This is to ensure no invalid state/relationships can enter the system, which prevent all sorts of issues (orphaned data, hidden relationships in the DB not exposed in the API etc.).

Note

This validation is performed using the UIDs of the CategoryOptionCombos. No other idScheme is supported.

Merge category option combos¶

The category option combo merge endpoint allows you to merge a number of category options (sources) into a target category option. This can be used to clean up the system, removing duplicates for instance.

Note

Only duplicate category option combos can be merged. There's more info about this in the validation section below.

Autorisation¶

The main authority required to perform a category option combo merge is F_CATEGORY_OPTION_COMBO_MERGE.

Requête¶

Merge category option combos with a POST request:

POST /api/categoryOptionCombos/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "dataMergeStrategy": "DISCARD"
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

The merge operation will merge the source category option combos into the target category option combo. One or many source category option combos can be specified. Only one target should be specified.

The merge operation will transfer all source category option combo metadata associations to the target category option combo.

Note

All source category option combos will always be deleted during a merge. The is because after all source references have been handled, empty category option combos are left. These are not seen as valid by the system.

The following metadata get updated:

Note

The following properties haven been purposely excluded from the merge as these may use references for external systems. If you encounter issues with these fields, they may need to be updated.

Indicator: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo

ProgramIndicator: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo

Validation¶

The following constraints and error codes apply. One of the main validation points is regarding duplicate CategoryOptionCombos. A duplicate CategoryOptionCombo is one which satisfies the criteria: - has the same CategoryCombo - has the same CategoryOptions - has a different UID

Tableau : Contraintes et codes d'erreur

Database constraints¶

There are unique constraints in place that can prevent a successful merge. These constraints are set by DHIS2 in order to maintain a logical domain model.
Below are a list of the known database unique key constraints at the time of writing. For example, you can only have 1 min max data element with the same org unit, data element and category option combo.

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "CategoryOptionCombo",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "CategoryOptionCombo merge complete"
        }
    }
}

Failure¶

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source CategoryOptionCombo must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target CategoryOptionCombo does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "CategoryOptionCombo",
            "sourcesDeleted": [],
            "message": "CategoryOptionCombo merge has errors"
        }
    }
}

A database constraint sample error response:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "ERROR: duplicate key value violates unique constraint \"minmaxdataelement_unique_key\"\n  Detail: Key (sourceid, dataelementid, categoryoptioncomboid)=(193236, 1148617, 167661) already exists."
}

Category Combo¶

Merge category combos¶

The category combo merge endpoint allows you to merge a number of category combos (sources) into a target category combo.

Note

Category combos can only be merged when:

1. source and target category combos have identical categories
   
2. all category option combos belonging to the involved category combos are valid (correct number of options, valid option membership)
   
3. no pre-existing duplicate category option combos exist within the involved category combos
   

These constraints ensure only equivalent category combos can be merged and help maintain system integrity.

Warning

A category combo merge will result in duplicate category option combos. These should be merged immediately after the category combo merge to maintain system integrity. Duplicates can be found using the data integrity check category_option_combos_have_duplicates.

Autorisation¶

The main authority required to perform a category combo merge is F_CATEGORY_COMBO_MERGE.

Requête¶

Merge category combos with a POST request:

POST /api/categoryCombos/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

The merge operation will merge the source category combos into the target category combo. One or many source category combos can be specified. Only one target should be specified.

The merge operation will transfer all source category combo metadata associations to the target category combo. The following metadata get updated:

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "CategoryCombo",
            "sourcesDeleted": [
                "FbLZS3ueWbQ", "dPSWsKeAZNw"
            ],
            "message": "CategoryCombo merge complete. There will be duplicate CategoryOptionCombos as a result of the merge. These should be merged immediately to help keep system integrity. Duplicates can be found using the data integrity check `category_option_combos_have_duplicates`"
        }
    }
}

Failure¶

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source CategoryCombo must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target CategoryCombo does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "CategoryCombo",
            "sourcesDeleted": [],
            "message": "CategoryCombo merge has errors"
        }
    }
}

Éléments de données¶

Merge data elements¶

Caution

Merging DataElements should be carried out with the utmost care. Particular attention should be given to the merging of data values that have data element references involved in the merge. Knowing the potential side effects of a merge should be fully understood before performing the merge. The merging of DataElements has far-reaching effects. The information below will try to help show what's involved in a DataElement merge. A DataElement merge touches all the major parts of the system (metadata, data, tracker, analytics and audit).

System performance may be impacted if the source DataElements are linked to large amounts of Data/Audit records particularly.

The data element merge endpoint allows you to merge a number of data elements (sources) into a target data element.

Autorisation¶

The main authority required to perform a data element merge is F_DATA_ELEMENT_MERGE.
Other authorities required relate to the general sharing and access of data elements, F_DATAELEMENT_PUBLIC_ADD and F_DATAELEMENT_DELETE.

Requête¶

Merge data elements with a POST request:

POST /api/dataElements/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true,
  "dataMergeStrategy": "DISCARD"
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

The merge operation will merge the source data elements into the target data element. One or many source data elements can be specified. Only one target should be specified.

The merge operation will transfer all source data element metadata associations to the target data element. The following metadata get updated:

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Database constraints¶

There are unique constraints in place that can prevent a successful merge. These constraints are set by DHIS2 in order to maintain a logical domain model.
Below are a list of the known database unique key constraints at the time of writing. For example, you can only have 1 data set element with the same dataset and data element.

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "DataElement",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "DataElement merge complete"
        }
    }
}

Failure¶

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source DataElement must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target DataElement does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

Another sample validation error response:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "All source ValueTypes must match target ValueType: `TEXT`. Other ValueTypes found: `NUMBER`",
                    "errorCode": "E1550",
                    "args": []
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

A database constraint sample error response:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "ERROR: duplicate key value violates unique constraint \"minmaxdataelement_unique_key\"\n  Detail: Key (sourceid, dataelementid, categoryoptioncomboid)=(193236, 1148617, 167661) already exists."
}

Indicateurs¶

Cette section décrit les indicateurs et les expressions d'indicateurs.

Indicateurs agrégés¶

Pour récupérer les indicateurs, vous pouvez lancer une requête GET à la ressource des indicateurs comme suit :

/api/indicators

Les indicateurs représentent des expressions qui peuvent être calculées et présentées sous forme de résultat. Les expressions des indicateurs sont divisées en un numérateur et un dénominateur. Les numérateurs et les dénominateurs sont des expressions mathématiques qui peuvent contenir des références à des éléments de données, à d'autres indicateurs, à des constantes et à des groupes d'unités d'organisation. Les variables seront remplacées par des valeurs de données lorsqu'elles seront utilisées, par exemple dans des rapports. Les variables autorisées dans les expressions sont décrites dans le tableau suivant.

Tableau : Variables d'indicateurs

Dans un opérande d'élément de données ou dans un élément de données agrégé, les substitutions suivantes peuvent être effectuées :

La syntaxe ressemble à ceci :

#{<dataelement-id>.<catoptcombo-id>} + C{<constant-id>} + OUG{<orgunitgroup-id>}

Voici un exemple correspondant :

#{P3jJH5Tu5VC.S34ULMcHMca} + C{Gfd3ppDfq8E} + OUG{CXw2yu5fodb}

Pour les variables d'éléments de données, l'identifiant de la combinaison d'options de catégorie peut être omis. La variable va alors représenter le total pour l'élément de données, par exemple pour toutes les combinaisons d'options de catégorie. Exemple :

#{P3jJH5Tu5VC} + 2

Les opérandes des éléments de données peuvent inclure toute combinaison d'options de catégorie et toute combinaison d'options d'attributs. Elles peuvent également utiliser des caractères génériques pour indiquer n'importe quelle valeur :

#{P3jJH5Tu5VC.S34ULMcHMca} + #{P3jJH5Tu5VC.*.j8vBiBqGf6O} + #{P3jJH5Tu5VC.S34ULMcHMca.*}

Exemple utilisant un groupe d'éléments de données :

#{deGroup:oDkJh5Ddh7d} + #{deGroup:GBHN1a1Jddh.j8vBiBqGf6O}

Exemple utilisant une option de catégorie, un groupe d'éléments de données et un groupe d'options de catégorie :

#{P3jJH5Tu5VC.co:FbLZS3ueWbQ} + #{deGroup:GBHN1a1Jddh.coGroup:OK2Nr4wdfrZ.j8vBiBqGf6O}

Exemple utilisant plusieurs groupes d'options de catégories :

#{P3jJH5Tu5VC.coGroup:OK2Nr4wdfrZ&j3C417uW6J7&ddAo6zmIHOk}

Exemple utilisant un élément de données de programme et un attribut de programme :

( D{eBAyeGv0exc.vV9UWAZohSf} * A{IpHINAT79UW.cejWyOfXge6} ) / D{eBAyeGv0exc.GieVkTxp4HH}

Exemple combinant des indicateurs de programme et des indicateurs agrégés :

I{EMOt6Fwhs1n} * 1000 / #{WUg3MYWQ7pt}

Exemple utilisant un taux de déclaration :

R{BfMAe6Itzgt.REPORTING_RATE} * #{P3jJH5Tu5VC.S34ULMcHMca}

Un autre exemple de taux de déclaration qui utilise des rapports sur des ensembles de données et des rapports attendus :

R{BfMAe6Itzgt.ACTUAL_REPORTS} / R{BfMAe6Itzgt.EXPECTED_REPORTS}

Exemple utilisant un indicateur existant :

N{Rigf2d2Zbjp} * #{P3jJH5Tu5VC.S34ULMcHMca}

Les expressions peuvent être constituées de tout type d'expression mathématique valide, à titre d'exemple :

( 2 * #{P3jJH5Tu5VC.S34ULMcHMca} ) / ( #{FQ2o8UBlcrS.S34ULMcHMca} - 200 ) * 25

Indicateurs de programme¶

Pour récupérer les indicateurs de programme, vous pouvez effectuer une requête GET à la ressource des indicateurs de programme, comme suit :

/api/programIndicators

Les indicateurs de programme peuvent contenir des informations collectées dans le cadre d'un programme. Les indicateurs ont une expression qui peut contenir des références à des éléments de données, des attributs, des constantes et des variables de programme. Les variables autorisées dans les expressions sont décrites dans le tableau suivant.

Tableau : Variables des indicateurs de programme

La syntaxe ressemble à ceci :

#{<programstage-id>.<dataelement-id>} + #{<attribute-id>} + V{<varible-id>} + C{<constant-id>}

Voici un exemple correspondant :

#{A03MvHHogjR.a3kGcGDCuk6} + A{OvY4VVhSDeJ} + V{incident_date} + C{bCqvfPR02Im}

Expressions¶

Les expressions sont des formules mathématiques qui peuvent contenir des références à des éléments de données, des constantes et des groupes d'unités d'organisation. Pour valider une expression et en obtenir la description sous forme de texte, vous pouvez adresser une requête GET à la ressource des expressions :

/api/expressions/description?expression=<expression-string>

La réponse suit le format standard des messages web JSON. La propriété statut indique le résultat de la validation et sera "OK" en cas de succès et "ERROR" en cas d'échec. La propriété message sera "Valid" (valide) si la validation réussit, et en cas d'échec, elle fournira une description textuelle de la raison de cet échec. La propriété description fournit une description textuelle de l'expression.

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Valid",
  "description": "Acute Flaccid Paralysis"
}

Fusionner les indicateurs¶

Le point d'extrémité de la fusion des indicateurs vous permet de fusionner des indicateurs (sources) en un seul indicateur cible.

Autorisation¶

Vous devez disposer de l'autorité F_INDICATOR_MERGE pour pouvoir fusionner des indicateurs.

Requête¶

Fusionner des indicateurs à l'aide d'une requête POST :

POST /api/indicators/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

L'opération de fusion permet de fusionner les indicateurs sources dans l'indicateur cible. Un ou plusieurs indicateurs sources peuvent être spécifiés. Un seul indicateur cible doit être spécifiée.

L'opération de fusion transfère toutes les associations de métadonnées de l'indicateur source vers l'indicateur cible. Les métadonnées suivantes sont mises à jour :

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "Indicator",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "Indicator merge complete"
        }
    }
}

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source Indicator must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target Indicator does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "Indicator",
            "sourcesDeleted": [],
            "message": "Indicator merge has errors"
        }
    }
}

Types d'indicateurs¶

Fusionner les types d'indicateurs¶

Le point d'extrémité de la fusion des types d'indicateur vous permet de fusionner des types d'indicateurs en un seul type d'indicateur cible.

Autorisation¶

Vous devez disposer de l'autorité F_INDICATOR_TYPE_MERGE pour pouvoir fusionner des types d'indicateur.

Requête¶

Fusionner des types d'indicateur à l'aide d'une requête POST :

POST /api/indicatorTypes/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

L'opération de fusion permet de fusionner les types d'indicateur source dans le type d'indicateur cible. Un ou plusieurs types d'indicateur source peuvent être spécifiés. Un seul type d'indicateur cible doit être spécifiée.

L'opération de fusion combine toutes les associations de métadonnées de l'indicateur et les types d'indicateur source, et le tout est transféré vers le type d'indicateur cible.

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Réponse¶

Succès¶

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "IndicatorType",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "IndicatorType merge complete"
        }
    }
}

Voici un exemple de réponse après une opération erronée :

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source IndicatorType must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target IndicatorType does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "IndicatorType",
            "sourcesDeleted": [],
            "message": "IndicatorType merge has errors"
        }
    }
}

Les unités d’organisation¶

La ressource organisationUnits suit les conventions standard des autres ressources de métadonnées présents dans DHIS2. Cette ressource prend en charge des paramètres de requête supplémentaires.

Obtenir la liste des unités d'organisation¶

Pour obtenir une liste des unités d'organisation, vous pouvez utiliser la ressource suivante :

/api/33/organisationUnits

Tableau : Paramètres de requête des unités d'organisation

Obtenir une unité d'organisation avec une sous-hiérarchie¶

Pour obtenir une unité d'organisation ainsi que les unités d'organisation présentes dans sa sous-hiérarchie, vous pouvez utiliser la ressource suivante.

/api/33/organisationUnits/{id}

Tableau : Paramètres de l'unité d'organisation

Obtenir des unités d'organisation par option de catégorie{ #webapi_organisation_units_by_category_options }¶

Point d'extrémité conçu pour récupérer les associations entre les options de catégorie et les unités d'organisation. Ce point d'extrémité est le moyen idéal pour récupérer les associations entre les programmes et les unités d'organisation.

/api/33/categoryOptions/orgUnits?categoryOptions={categoryOptionIdA},{categoryOptionIdB}

Les réponses auront le format suivant :

{
  "<categoryOptionIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdC>": []
}

Les options de catégorie accessibles à toutes les unités d'organisation sont renvoyées avec un tableau d'unités d'organisation vide ([]).

Obtenir les unités d'organisation par programme¶

Point d'extrémité conçu pour récupérer les associations entre les programmes et les unités d'organisation. Ce point d'extrémité est le moyen idéal pour récupérer les associations entre les programmes et les unités d'organisation.

/api/33/programs/orgUnits?programs={programIdA},{programIdB}

Les réponses auront le format suivant :

{
  "<programIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdC>": []
}

Les programmes accessibles à toutes les unités d'organisation sont renvoyées avec un tableau d'unités d'organisation vide ([]).

Fractionner des unités d'organisation¶

Le point d'extrémité de fractionnement des unités d'organisation vous permet de fractionner des unités d'organisation en un certain nombre d'unités d'organisation cibles.

Requête¶

Fractionner des unités d'organisation à l'aide d'une requête POST :

POST /api/organisationUnits/split

La charge au format JSON ressemble à ceci :

{
  "source": "rspjJHg4WY1",
  "targets": [
    "HT0w9YLMLyn",
    "rEpnzuNpRKM"
  ],
  "primaryTarget": "HT0w9YLMLyn",
  "deleteSource": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fractionnement des champs de la charge

L'opération de fractionnement consiste à scinder l'unité d'organisation source en unités d'organisation cibles. Il est recommandé de créer de nouvelles unités d'organisation cibles avant de procéder au fractionnement, et de s'assurer au préalable les unités cibles ne contiennent pas de données agrégées. Vous pouvez spécifier un nombre quelconque d'unités d'organisation cibles.

L'opération de fractionnement transfère toutes les associations de métadonnées de l'unité d'organisation source vers les unités d'organisation cibles. Cela inclut les ensembles de données, les programmes, les groupes d'unités d'organisation, les options de catégorie, les utilisateurs, les visualisations, les cartes et les rapports d'événements.

L'opération transfère tous les enregistrements de données de l'unité d'organisation source vers l'unité d'organisation spécifiée comme cible principale ou, si elle n'est pas spécifiée, vers la première unité d'organisation cible spécifiée. Cela inclut les valeurs de données agrégées, les enregistrements relatifs à l'approbation des données, les événements, les entités suivies, etc.

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Merge organisation units¶

Le point d'extrémité de fusion des unités d'organisation vous permet de fusionner des unités d'organisation en une seule unité d'organisation cible.

Autorisation¶

The main authority required to perform an organisation unit merge is F_ORGANISATION_UNIT_MERGE.

Requête¶

Fusionner des unités d'organisation à l'aide d'une requête POST :

POST /api/organisationUnits/merge

La charge au format JSON ressemble à ceci :

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "dataValueMergeStrategy": "LAST_UPDATED",
  "dataApprovalMergeStrategy": "LAST_UPDATED",
  "deleteSources": true
}

Les propriétés JSON sont décrites dans le tableau suivant.

Tableau : Fusion des champs de la charge

L'opération de fusion consiste à combiner des unités d'organisation source pour former une seule unité cible. Il est recommandé de créer une nouvelle unité d'organisation cible avant de procéder à la fusion, et de s'assurer au préalable l'unité cible ne contient pas de données agrégées. Vous pouvez spécifier un nombre quelconque d'unités d'organisation source.

L'opération de fusion transfère toutes les associations de métadonnées des unités d'organisation sources vers l'unité d'organisation cible. Cela inclut les ensembles de données, les programmes, les groupes d'unités d'organisation, les options de catégorie, les utilisateurs, les visualisations, les cartes et les rapports d'événements. L'opération transfère également toutes les données d'événements et de tracker, telles que les événements, les inscriptions, l'historique de la propriété, la propriété des programmes et les entités suivies, vers l'unité d'organisation cible.

La stratégie de fusion des valeurs de données spécifiée définit la manière dont les valeurs de données sont traitées. Pour la stratégie LAST_UPDATED, les valeurs de données de toutes les unités d'organisation sources sont transférées vers l'unité d'organisation cible, et lorsque des valeurs existent pour les mêmes paramètres, c'est la dernière valeur mise à jour ou créée qui sera utilisée. Ceci permet d'éviter la répétition des données. Pour la stratégie DISCARD, les valeurs ne sont pas transférées vers l'unité d'organisation cible, mais elles sont simplement supprimées. La stratégie de fusion de l'approbation des données spécifiée définit la manière dont les enregistrements relatifs à l'approbation des données sont traités, et suit la même logique que les valeurs de données.

Validation¶

Les contraintes et les codes d'erreur suivants s'appliquent.

Tableau : Contraintes et codes d'erreur

Ensembles de données¶

La ressource dataSets suit les conventions standard des autres ressources de métadonnées présents dans DHIS2. Cette ressource prend en charge des paramètres de requête supplémentaires.

/api/33/dataSets

Pour récupérer la version d'un ensemble de données, vous pouvez effectuer une requête GET :

GET /api/33/dataSets/<uid>/version

Pour augmenter (d'une unité) la version d'un ensemble de données, vous pouvez effectuer une requête POST :

POST /api/33/dataSets/<uid>/version

Modèle de notification des ensembles de données¶

La ressource modèles de notification des ensembles de données suit les conventions standard des autres ressources de métadonnées présentes dans DHIS2.

GET /api/33/dataSetNotficationTemplates

Pour récupérer un modèle de notification d'ensemble de données, vous pouvez effectuer une requête GET :

GET /api/33/dataSetNotficationTemplates/<uid>

Pour ajouter un modèle de notification d'ensemble de données, vous pouvez effectuer une requête POST :

POST /api/33/dataSetNotficationTemplates

Pour supprimer un modèle de notification d'ensemble de données, vous pouvez effectuer une requête DELETE :

DELETE /api/33/dataSetNotficationTemplates/<uid>

Ci-dessous, un exemple de charge JSON :

{
  "name": "dataSetNotificationTemplate1",
  "dataSetNotificationTrigger": "DATA_SET_COMPLETION",
  "relativeScheduledDays": 0,
  "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
  "dataSets": [{
    "id": "eZDhcZi6FLP"
  }],
  "deliveryChannels": ["SMS","EMAIL"],
  "subjectTemplate": "V{data_set_name}",
  "messageTemplate": "V{data_set_name}V{registration_period}",
  "sendStrategy": "SINGLE_NOTIFICATION"
}

notificationRecipient peut être l'un des éléments suivants : - USER_GROUP pour les messages internes - ORGANISATION_UNIT_CONTACT pour les messages externes

Niveaux d'unités d'organisation remplis{ #webapi_filled_organisation_unit_levels }¶

La ressource filledOrganisationUnitLevels fournit une liste ordonnée de niveaux d'unités d'organisation, où les niveaux générés sont introduits dans la liste pour remplir les positions pour lesquelles il n'existe pas de niveau.

GET /api/33/filledOrganisationUnitLevels

Pour définir des niveaux d'unité d'organisation, vous pouvez envoyer une requête POST avec une charge JSON et un type de contenu application/json comme ceci :

{
  "organisationUnitLevels": [{
    "name": "National",
    "level": 1,
    "offlineLevels": 3
  }, {
    "name": "District",
    "level": 2
  }, {
    "name": "Chiefdom",
    "level": 3
  }, {
    "name": "Facility",
    "level": 4
  }]
}

Prédicteurs¶

Un prédicteur permet de générer des valeurs de données sur la base d'une expression. Il peut être utilisé, par exemple, pour générer des cibles, des seuils ou des estimations de valeurs.

Pour récupérer les prédicteurs, vous pouvez effectuer une requête GET à la ressource des prédicteurs comme suit :

/api/predictors

Création d'un prédicteur¶

Vous pouvez créer un prédicteur à l'aide d'une requête POST à la ressource des prédicteurs :

POST /api/predictors

Voici un exemple de charge :

{
  "id": "AG10KUJCrRk",
  "name": "Malaria Outbreak Threshold Predictor",
  "shortName": "Malaria Outbreak Predictor",
  "description": "Computes the threshold for potential malaria outbreaks based on the mean plus 1.5x the std dev",
  "output": {
    "id": "nXJJZNVAy0Y"
  },
  "generator": {
    "expression": "AVG(#{r6nrJANOqMw})+1.5*STDDEV(#{r6nrJANOqMw})",
    "description": "Maximum normal malaria case count",
    "missingValueStrategy": "NEVER_SKIP",
    "slidingWindow": false
  },
  "periodType": "Monthly",
  "sequentialSampleCount": 4,
  "sequentialSkipCount": 1,
  "annualSampleCount": 3,
  "organisationUnitLevels": [4]
}

L'élément de sortie fait référence à l'identifiant de l'élément de données pour lequel des valeurs de données prédites doivent être sauvegardées. L'élément générateur fait référence à l'expression qui sera utilisée pour calculer les valeurs prédites.

Expressions du prédicteur¶

Un prédicteur possède toujours une expression génératrice qui décrit le mode de calcul de la valeur prédite. Le prédicteur peut également avoir une expression permettant de tester la fonction de saut, laquelle expression renvoie une valeur booléenne. Lorsque l'expression de test de saut est présente, elle est évaluée dans chacune des périodes échantillonnées afin de déterminer si les valeurs de cette période doivent être ignorées.

Les variables suivantes peuvent être utilisées dans une expression génératrice ou dans une expression de test de saut :

Génération de valeurs prédites¶

Pour exécuter tous les prédicteurs (générer des valeurs prédites), vous pouvez envoyer une requête POST à la ressource d'exécution :

POST /api/predictors/run

Pour exécuter un seul prédicteur, vous pouvez envoyer une requête POST à la ressource d'exécution et préciser le prédicteur :

POST /api/predictors/AG10KUJCrRk/run

Programs¶

To retrieve programs you can make a GET request to the programs resource like this:

/api/programs

Program category mappings¶

Starting in version 2.42, a program may optionally define one of more category mappings. These mappings can be used to add disaggregations to program indicators for the program. A program indicator for this program can choose which mappings to use for the categories in its category combination and/or attribute combination.

This allows program indicator data to be viewed by category and category option such as in the Data Visualizer. It also allows an Aggregate data exchange to generate values from the program indicator that contain a category option combination and/or an attribute option combination.

These category mappings can be generated by the Maintenance (Preview) App or they can be added using the Web API. This section describes the format of the category mappings if you are using the Web API.

A new program has no category mappings. In the Web API this looks like:

"categoryMappings": []

To add category mappings to the program, you can edit this part of the program definition and then import the result back into DHIS2. Here is an example of how the edited field could look:

"categoryMappings": [
  {
    "id": "goor7Li4See",
    "categoryId": "cX5k9anHEHd",
    "mappingName": "standard Gender mapping",
    "optionMappings": [
      {
        "optionId": "apsOixVZlf1",
        "filter": "#{Zj7UnCAulEk.oZg33kd9taw} == 'Female'"
      },
      {
        "optionId": "jRbMi0aBjYn",
        "filter": "#{Zj7UnCAulEk.oZg33kd9taw} == 'Male'"
      }
    ]
  },
  {
    "id": "ESesheeva1i",
    "categoryId": "VPqYge5RB93",
    "mappingName": "standard Outcome mapping",
    "optionMappings": [
      {
        "optionId": "e3oqm527jBS",
        "filter": "#{Zj7UnCAulEk.sAg4Niej9bo} == 'Managed at PHU'"
      },
      {
        "optionId": "rSdQZYDmHJm",
        "filter": "#{Zj7UnCAulEk.sAg4Niej9bo} == 'Referred'"
      }
    ]
  },
  {
    "id": "laiHaid9eit",
    "categoryId": "fkAkrdC7eJF",
    "mappingName": "Referrals Age at event",
    "optionMappings": [
      {
        "optionId": "K4gwuiVvW3z",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{event_date})<5"
      },
      {
        "optionId": "oaFqxkefkPs",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{event_date})>=5"
      }
    ]
  },
  {
    "id": "SeNg0bohFah",
    "categoryId": "fkAkrdC7eJF",
    "mappingName": "Referrals Age at analyitcs period start",
    "optionMappings": [
      {
        "optionId": "K4gwuiVvW3z",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{analytics_period_start})<5"
      },
      {
        "optionId": "oaFqxkefkPs",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{analytics_period_start})>=5"
      }
    ]
  }
]

In this example, the program defines four category mappings that can be used by the program indicators assigned to the program: - A mapping for the Gender category - A mapping for the Outcome category - Two mappings for the Referrals Age category. A program indicator can choose which mapping it wants to use depending on whether it wants to show the age at the event date or the age at the analytics period start.

The categoryMappings fields are:

A program indicator may select which program mappings to use in its categoryMappingIds field. A new program indicator has no category mapping ids. In the Web API this looks like:

"categoryMappingIds": [],

You can replace this with the category mappings that you want the program indicator to use. For example, if the program indicator has selected a category combination that combines Gender and Outcome, this field could be edited to contain the mapping ids for these categories such as defined in the above categoryMappings example:

"categoryMappingIds": [
    "goor7Li4See",
    "ESesheeva1i"
],

Règles de programme¶

Cette section traite de l'envoi et de la lecture des règles de programme et explique leur modèle de données. Les règles de programme permettent de configurer un fonctionnement dynamique au sein des programmes de DHIS2.

Modèle de règles de programme¶

Le modèle de données des règles de programme se compose de variables de règles de programme (programRuleVariables), de règles de programme (programRules) et d'actions de règles de programme (programRuleActions). La règle de programme contient une expression - lorsque cette expression est définie sur "true" (vrai), les actions de règle de programme sous cette expression sont déclenchées. Les variables de règle de programme sont utilisées pour traiter les éléments de données, les valeurs de données des entités suivies et d'autres valeurs de données nécessaires à l'exécution des expressions. Toutes les règles d'un programme partagent la même bibliothèque de variables de règles, et une variable peut être utilisée dans les expressions de plusieurs règles.

Détails sur le modèle de règles de programme¶

Le tableau suivant donne un aperçu détaillé du modèle de règle de programme.

Tableau : Règle de programme

Détails sur le modèle d'actions des règles de programme¶

Le tableau suivant donne un aperçu détaillé du modèle d'actions des règles de programme.

Tableau : Action de règle de programme

Validation des actions des règles de programme¶

Certaines validations ont été ajoutées au modèle des actions des règles de programme dans la version 2.37. L'objectif principal était d'empêcher l'utilisateur de créer des règles de programme erronées afin de maintenir la cohérence de la base de données. Ces validations dépendent du type d'action de la règle de programme. Chaque type d'action a sa propre validation.

Tableau : Validations des actions des règles de programme

En plus des validations ci-dessus, le champ données dans l'action de la règle de programme qui contient normalement une expression peut également être évalué en utilisant le point d'extrémité de l'api ci-dessous.

POST /api/programRuleActions/data/expression/description?programId=<uid>

{
  "condition": "1 + 1"
}

Détails sur le modèle de variables des règles de programme¶

Le tableau suivant donne un aperçu détaillé du modèle de variables des règles de programme.

Tableau : Variable de règles de programme

Création de règles de programme¶

• Pour effectuer des opérations CRUD, vous pouvez utiliser la ressource programRules, disponible dans l'API.

Pour récupérer la liste des règles de programmes, vous pouvez effectuer une requête GET comme suit :

/api/programRules

Pour récupérer une seule règle de programme, vous pouvez effectuer une requête GET comme suit :

/api/programRules/<program_rule_uid>

Pour sauvegarder ou ajouter une seule règle de programme, vous pouvez effectuer une requête POST comme suit :

/api/programRules/<program_rule_uid>

Pour mettre à jour une seule règle de programme, vous pouvez effectuer une requête PUT comme suit :

/api/programRules/<program_rule_uid>

Pour supprimer une seule règle de programme, vous pouvez effectuer une requête DELETE comme suit :

/api/programRules/<program_rule_uid>

Pour récupérer la description de la condition de la règle de programme, vous pouvez effectuer une requête POST en fournissant la chaîne de la condition dans le corps de la requête.

/api/programRules/condition/description?<program_rule_uid>

Formulaires¶

Pour récupérer des informations sur un formulaire (qui correspond à un ensemble de données et à ses sections), vous pouvez interagir avec la ressource form. La réponse du formulaire est accessible en XML et JSON et fournira des informations sur chaque section (groupe) du formulaire ainsi que sur chaque champ de ces sections, y compris les étiquettes et les identifiants. En fournissant des identifiants de période et d'unité d'organisation, la réponse du formulaire sera constituée de valeurs de données.

Tableau : Paramètres de requête du formulaire

Pour récupérer le formulaire d'un ensemble de données, vous pouvez effectuer une requête GET comme suit :

/api/dataSets/<dataset-id>/form.json

Pour récupérer le formulaire pour l'ensemble de données ayant l'identifiant "BfMAe6Itzgt" au format XML :

/api/dataSets/BfMAe6Itzgt/form

Pour récupérer le formulaire en incluant les métadonnées, au format JSON :

/api/dataSets/BfMAe6Itzgt/form.json?metaData=true

Pour récupérer le formulaire rempli avec les valeurs de données d'une période et d'une unité d'organisation spécifiques au format XML :

/api/dataSets/BfMAe6Itzgt/form.xml?ou=DiszpKrYNg8&pe=201401

Cette ressource permet également de créer des formulaires de saisie de données personnalisés, directement pour un ensemble de données. Cela peut se faire à l'aide d'une requête POST ou PUT avec un contenu de type text/html où la charge est le balisage du formulaire personnalisé. En voici l'illustration :

curl -d @form.html "localhost/api/dataSets/BfMAe6Itzgt/form"
  -H "Content-Type:text/html" -u admin:district -X PUT

Documents¶

Les références aux fichiers peuvent être stockées avec la ressource "document".

Tableau : Champs du document

Une requête GET au point d'extrémité des documents renverra tous les documents :

/api/documents

Une requête POST au point d'extrémité des documents créera un nouveau document :

curl -X POST -d @document.json -H "Content-type: application/json"
  "http://dhis.domain/api/documents"

{
  "name": "dhis home",
  "external": true,
  "url": "https://www.dhis2.org"
}

Une requête GET à laquelle est ajouté l'identifiant d'un document renverra des informations sur ce document. Une requête PUT au même point d'extrémité mettra à jour les champs du document :

/api/documents/<documentId>

Ajouter /data à la requête GET renverra le contenu réel du document :

/api/documents/<documentId>/data

Importation de métadonnées en CSV¶

DHIS2 prend en charge l'importation de métadonnées au format CSV, telles que les éléments de données, les unités d'organisation et les règles de validation. Les propriétés des différents objets de métadonnées sont identifiées en fonction de l'ordre ou de l'index des colonnes (voir ci-dessous pour plus de détails). Vous pouvez omettre les propriétés d'objets ou les colonnes non nécessaires, mais puisque l'ordre des colonnes est important, une colonne vide doit être incluse. En d'autres termes, si vous voulez spécifier des propriétés ou des colonnes qui apparaissent tard dans l'ordre des colonnes, mais ne pas spécifier certaines colonnes qui apparaissent tôt dans l'ordre, vous pouvez inclure des colonnes vides pour elles.

La première ligne du fichier CSV est considérée comme un en-tête et est ignorée lors de l'importation. Le caractère virgule doit être utilisé comme séparateur de texte. Le texte qui contient des virgules doit être placé entre guillemets.

Pour télécharger des métadonnées au format CSV, vous pouvez envoyer une requête POST au point d'extrémité des métadonnées :

POST /api/metadata?classKey=CLASS-KEY

Les types d'objets suivants sont pris en charge. Le paramètre de requête classKey (clé class) est obligatoire et se trouve à côté de chaque type d'objet dans le tableau ci-dessous.

Tableau : Types d'objets et clés

Astuce

Si vous utilisez curl, l'option --data-binary doit être utilisée car elle préserve les sauts de ligne et les nouvelles lignes, ce qui est essentiel pour les données CSV.

Par exemple, pour télécharger un fichier d'éléments de données au format CSV avec curl, vous pouvez utiliser la commande suivante :

curl --data-binary @data_elements.csv "http://localhost/api/metadata?classKey=DATA_ELEMENT"
  -H "Content-Type:application/csv" -u admin:district

Les formats des types d'objets actuellement pris en charge pour l'importation en CSV sont répertoriés dans les sections suivantes.

Eléments de données¶

Tableau : Format CSV des éléments de données

Vous trouverez ci-dessous un exemple de fichier CSV pour les éléments de données. La première ligne sera toujours ignorée. Vous pouvez ignorer des colonnes et compter sur les valeurs par défaut utilisées par le système. Vous pouvez également ignorer les colonnes que vous n'utilisez pas

name,uid,code,shortname,description
"Women participated skill development training",,"D0001","Women participated in training"
"Women participated community organizations",,"D0002","Women participated in organizations"

Les unités d’organisation¶

Tableau : Format CSV de l'unité d'organisation