Aperçu

L'API Web est un composant qui permet aux systèmes externes d'accéder aux données stockées dans une instance DHIS2 et de les manipuler. Plus précisément, elle fournit une interface programmatique à un large éventail de données exposées et de méthodes de service pour des applications telles que des clients logiciels tiers, des portails web et des modules DHIS2 internes.

Introduction

L'API Web adhère à de nombreux principes du style architectural REST. Pour n'en citer que certains, importants :

1. Les éléments fondamentaux sont appelés ressources. Une ressource peut être tout ce qui est exposé sur le web, d'un document à un processus d'entreprise - tout ce avec quoi un client peut vouloir interagir. Les aspects informatifs d'une ressource peuvent être récupérés ou échangés par le biais de représentations de la ressource. Une représentation est une vue de l'état d'une ressource à un moment donné. Par exemple, la ressource visualisations dans DHIS2 représente des visualisations de données agrégées pour un certain ensemble de paramètres. Cette ressource peut être récupérée dans divers formats de représentation, notamment JSON et CSV.
2. Toutes les ressources peuvent être identifiées de manière unique par un URI (également appelé URL). Toutes les ressources ont une représentation par défaut. Vous pouvez indiquer que vous êtes intéressé par une représentation spécifique en fournissant un en-tête HTTP Accept, une extension de fichier ou un paramètre de requête format. Ainsi, pour récupérer une représentation CSV d'une réponse de données analytiques, vous pouvez fournir un en-tête Accept : application/csv ou ajouter .csv ou ?format=csv à l'URL de votre requête.
3. Les interactions avec l'API nécessitent l'utilisation correcte des méthodes ou verbes HTTP. Cela implique que pour une ressource, vous devez émettre une requête GET lorsque vous souhaitez la récupérer, une requête POST lorsque vous souhaitez en créer une, une requête PUT lorsque vous souhaitez la mettre à jour et une requête DELETE lorsque vous souhaitez la supprimer.

Authentification

L'API Web DHIS2 prend en charge trois protocoles d'authentification :

• L'authentification de base
• Les jetons d'accès personnels (PAT)
• OAuth 2

Verify and get information about the currently authenticated user by making a GET request to the following endpoint.

GET /api/me

Get the list of authorities for the currently authenticatd user.

GET /api/me/authorization

Check whether the currently authenticated user has the given authority.

GET /api/me/authorization/{authority}

For example, to check whether the user has the F_CONSTANT_ADD authority.

GET /api/me/authorization/F_CONSTANT_ADD

The response will be either true or false in JSON format.

Authentification de base

L'API Web DHIS2 prend en charge l'authentification de base. L'authentification de base est une technique qui permet aux clients d'envoyer des informations d'identification par HTTP à un serveur web. Techniquement parlant, le nom d'utilisateur est suivi de deux points et le mot de passe, encodé en Base64, est préfixé par Basic et fourni en tant que valeur de l'en-tête HTTP Authorization (autorisation). De manière plus formelle, il s'agit de :

Authorization: Basic base64encode(nom d'utilisateur:mot de passe)

La plupart des environnements de développement compatibles avec les réseaux prennent en charge l'authentification de base, comme Apache HttpClient et Spring RestTemplate. Il est important de noter que ce schéma d'authentification n'offre aucune sécurité puisque le nom d'utilisateur et le mot de passe sont envoyés en texte clair et peuvent être facilement observés par un pirate. L'utilisation de Basic n'est recommandée que si le serveur utilise SSL/TLS (HTTPS) pour crypter la communication avec les clients. Ceci est un impératif, afin de garantir des interactions sécurisées avec l'API Web.

Authentification à deux facteurs

DHIS2 prend en charge l'authentification à deux facteurs. Cette fonction peut être activée pour chaque utilisateur. Lorsque cette option est activée, les utilisateurs sont invités à saisir un code 2FA lorsqu'ils se connectent. Pour en savoir plus sur l'authentification à deux facteurs, cliquez [ici] (https://www.google.com/landing/2step/).

Jeton d'accès personnel

Les jetons d'accès personnels (PAT) sont une alternative à l'utilisation de mots de passe lors de l'authentification au système DHIS2 lorsque l'on utilise l'API.

Les jetons d'accès personnel peuvent être une alternative plus sécurisée à l'authentification de base HTTP et devraient être votre choix privilégié lorsque vous créez une nouvelle application, un script, etc.

L'authentification de base HTTP est considérée comme non sécurisée car, entre autres, elle envoie votre nom d'utilisateur et votre mot de passe de façon indiscrète. Il est possible qu'elle soit abandonnée dans les versions futures de DHIS2 ou qu'elle devienne facultative, ce qui signifie que l'authentification de base devra être explicitement activée dans la configuration.

Problèmes de sécurité majeurs !

Vos jetons d'accès personnel hériteront automatiquement de toutes les permissions et autorisations dont dispose votre utilisateur. Il est donc extrêmement important de limiter l'accès que vous accordez à votre jeton en fonction de l'utilisation que vous comptez en faire, voir Configurer votre jeton.

Si vous souhaitez que le jeton n'ait accès qu'à une partie restreinte et spécifique du serveur, il est plutôt recommandé de créer un nouvel utilisateur spécial auquel vous n'attribuerez que les rôles et autorisations auxquels vous souhaitez qu'il ait accès.

Création d'un jeton

Pour créer un nouveau PAT, vous avez deux possibilités : * A. Créez un jeton dans l'interface utilisateur de la page de profil de votre compte. * B. Créer un jeton via l'API.

A. Creating a token on the account page

Connectez-vous avec votre nom d'utilisateur et votre mot de passe, allez sur votre page de profil (cliquez en haut à droite, et choisissez « Modifier le profil » dans le menu déroulant). Sur votre page de profil, choisissez « Jetons d'accès personnels » dans le menu à gauche. Vous devriez maintenant être sur la page « Gérer les jetons d'accès personnels » et voir le texte : « Vous n'avez pas de jetons d'accès personnels actifs ». Cliquez sur « Générer un nouveau jeton » pour créer un nouveau jeton. Une fenêtre contextuelle « Générer un nouveau jeton » s'affiche et vous propose deux choix :

1. Server/script context

"Ce type est utilisé pour les intégrations et les scripts qui ne seront pas accessibles par un navigateur".

Si vous prévoyez d'utiliser le jeton dans une application, un script ou autre, ce type de jeton devrait être votre choix.

2. Browser context

"Ce type d'application est utilisé pour les applications, telles que les portails publics, auxquelles on accède à l'aide d'un navigateur web".

Si vous devez créer un lien vers DHIS2 sur une page web, ou par exemple l'intégrer dans une iframe, c'est probablement le type de jeton qu'il vous faut.

Configuration de votre jeton

Après avoir choisi le type de jeton que vous désirez, vous pouvez configurer différentes contraintes d'accès à votre jeton. Par contrainte, nous entendons la manière de limiter et de restreindre l'utilisation de votre jeton. Cela peut être d'une importance cruciale si vous envisagez d'utiliser le jeton dans un environnement public, par exemple sur un tableau de bord public d'un autre site, intégré dans une iframe. Étant donné que les jetons ont toujours les mêmes accès/autorisations que ceux dont dispose actuellement votre utilisateur, il convient d'être particulièrement vigilant si vous avez l'intention de les utiliser dans un environnement que vous ne contrôlez pas à 100 %.

NB : Si quelqu'un d'autre met la main sur votre jeton, il peut faire tout ce que votre utilisateur est capable de faire. Il n'est pas possible de faire la distinction entre les actions effectuées à l'aide du jeton et les autres actions effectuées par votre utilisateur.

Important : Il est fortement conseillé de créer un utilisateur distinct et unique ayant uniquement les rôles/autorisations si vous envisagez d'utiliser les jetons PAT dans un environnement non sécurisé et/ou public, par exemple, sur un PC ou un serveur que vous ne contrôlez pas à 100 %, ou « intégré » dans une page web sur un autre serveur.

Constraint types

• Temps d'expiration
• Adresses UP autorisées
• Méthodes HTTP autorisées
• Référents HTTP autorisés

Temps d'expiration

La durée d'expiration définit simplement la durée pendant laquelle vous souhaitez que votre jeton soit utilisable, le délai par défaut étant de 30 jours. Passé ce délai, le jeton renverra simplement un message 401 (non autorisé). Vous pouvez définir le délai d'expiration que vous souhaitez, mais il est fortement conseillé de définir un délai d'expiration raisonnable pour votre cas d'utilisation.

IP addresses

Il s'agit d'une liste d'adresses IP séparées par des virgules, à partir desquelles vous souhaitez limiter la provenance des requêtes de jetons.

Important: La validation de l'adresse IP repose sur l'en-tête X-Transféré-À, qui peut être usurpé. Pour des raisons de sécurité, assurez-vous qu'un équilibreur de charge ou un proxy inverse écrase cet en-tête.

HTTP methods

Une liste de méthodes HTTP séparées par des virgules que vous souhaitez que votre jeton puisse utiliser. Si vous n'avez besoin de votre jeton que pour consulter des données, et non pour les modifier ou les supprimer, la sélection de la méthode GET HTTP est judicieuse.

HTTP referrers

Le référent HTTP est un en-tête ajouté à la requête lorsque vous cliquez sur un lien, il indique le site/la page sur lequel/laquelle vous étiez lorsque vous avez cliqué sur le lien. Pour en savoir plus sur l'en-tête du référent HTTP, cliquez sur le lien suivant : https://en.wikipedia.org/wiki/HTTP_referer

Cela peut servir à limiter l'utilisation d'un jeton « public » intégré à une autre page sur un autre site. S'assurer que l'en-tête du référent correspond au nom d'hôte du site d'où le jeton doit provenir peut éviter l'utilisation abusive du jeton, par exemple si quelqu'un le publie sur un forum public.

Important Ceci n'est pas une fonctionnalité de sécurité. L'en-tête référence peut être facilement usurpé. Ce paramètre est destiné à dissuader les développeurs tiers non autorisés à se connecter aux instances d'accès public.

Saving a token

Lorsque vous avez fini de configurer votre jeton, vous pouvez l'enregistrer en cliquant sur le bouton « Générer un nouveau jeton » en bas à droite de la fenêtre contextuelle. Le jeton sera alors sauvegardé et une clé secrète sera générée sur le serveur. La nouvelle clé secrète sera affichée en bas de la liste des jetons PAT sur fond vert, et le texte « Jeton nouvellement créé ». La clé du jeton secret ressemble à ceci :

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Creating a token with the API

Example of how to create a new Personal Access Token using the API:

POST /api/apiToken
Content-Type: application/json
Authorization: Basic admin district

{}

Il renverra une réponse contenant un jeton similaire à celui-ci :

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "response": {
     "responseType": "ApiTokenCreationResponse",
     "key": "d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092",
     "uid": "jJYrtIVP7qU",
     "klass": "org.hisp.dhis.security.apikey.ApiToken",
     "errorReports": []
  }
}

Note: The token key will only be shown once here in this response. You need to copy and save this is in a secure place for use later!

Le jeton lui-même se compose de trois parties : 1. Préfixe : (d2pat_) indique de quel type de jeton il s'agit. 2. Octets aléatoires codés en Base64: (5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ) 3. Somme de contrôle CRC32 : (1151814092) la partie de la somme de contrôle est complétée par 0 de sorte qu'elle conserve toujours une longueur de dix caractères.

Configure token with the API

Pour modifier l'une des contraintes de votre jeton, vous pouvez envoyer la requête API HTTP suivante.

Note: Only the constraints are possible to modify after the token has been created.

PUT /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: Basic admin district

{
  "version": 1,
  "type": "PERSONAL_ACCESS_TOKEN",
  "expire": 163465349603200,
  "attributes": [
      {
        "type": "IpAllowedList",
        "allowedIps": ["192.168.0.1"]
      },
      {
        "type": "MethodAllowedList",
        "allowedMethods": ["GET"]
      }
  ]
}

Using a Personal Access Token

To issue a request with your newly created token, use the Authorization header accordingly. The authorization header format is:

Autorisation : ApiToken [YOUR_SECRET_API_TOKEN_KEY]

Par exemple :

GET /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Deleting a Personal Access Token

Vous pouvez supprimer vos PAT soit dans l'interface utilisateur de votre page de profil où vous les avez créés, soit via l'API comme ceci :

DELETE /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

OAuth2

DHIS2 prend en charge le protocole d'authentification OAuth2. OAuth2 est une norme ouverte d'autorisation qui permet aux clients tiers de se connecter au nom d'un utilisateur DHIS2 et d'obtenir un bearer token (jeton porteur) réutilisable pour les requêtes ultérieures à l'API Web. DHIS2 ne prend pas en charge les rôles OAuth2 à granularité fine, mais fournit aux applications un accès basé sur les rôles d'utilisateur de DHIS2.

Chaque client pour lequel vous voulez autoriser l'authentification OAuth 2 doit être enregistré dans DHIS2. Pour ajouter un nouveau client OAuth2, allez dans Applications > Paramètres > Clients OAuth2 dans l'interface utilisateur, cliquez sur Ajouter nouveau et entrez le nom du client souhaité et les types d'autorisations.

Create a Client

Un client OAuth2 peut être ajouté via l'API Web. Par exemple, nous pouvons envoyer une charge comme celle-ci :

{
  "name": "OAuth2 Demo Client",
  "cid": "demo",
  "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
  "grantTypes": [
    "password",
    "refresh_token",
    "authorization_code"
  ],
  "redirectUris": [
    "http://www.example.org"
  ]
}

La charge utile peut être envoyée avec la commande suivante :

SERVER="https://play.dhis2.org/dev"
curl -X POST -H "Content-Type: application/json" -d @client.json
  -u admin:district "$SERVER/api/oAuth2Clients"

This client will be used as the basis for the next grant type examples.

Type d'autorisation "Mot de passe"

Le type d'autorisation le plus simple est le type mot de passe. Ce type d'autorisation est similaire à l'authentification de base en ce sens qu'il exige du client qu'il recueille le nom d'utilisateur et le mot de passe de l'utilisateur. Prenons l'exemple de notre serveur de démonstration :

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d grant_type=password -d username=admin -d password=district

Vous obtiendrez une réponse similaire à ceci :

{
  "expires_in": 43175,
  "scope": "ALL",
  "access_token": "07fc551c-806c-41a4-9a8c-10658bd15435",
  "refresh_token": "a4e4de45-4743-481d-9345-2cfe34732fcc",
  "token_type": "bearer"
}

Pour l'instant, nous allons nous concentrer sur le access_token, qui sera utilisé comme jeton d'authentification (porteur). À titre d'exemple, nous allons obtenir tous les éléments de données en utilisant notre jeton :

SERVER="https://play.dhis2.org/dev"
curl -H "Authorization: Bearer 07fc551c-806c-41a4-9a8c-10658bd15435" "$SERVER/api/33/dataElements.json"

Type d'autorisation "rafraîchir_jeton"{ #webapi_refresh_token }

En général, les jetons d'accès ont une validité limitée. Vous pouvez jeter un coup d'œil à la propriété expires_in (expire dans) de la réponse dans l'exemple précédent pour comprendre quand un jeton expire. Pour obtenir un nouveau access_token (jeton d'accès), vous pouvez visiter le serveur et utiliser refresh_token (rafraîchir le jeton) qui vous permet d'obtenir un jeton mis à jour sans avoir besoin de demander les informations d'identification de l'utilisateur une fois de plus.

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"
REFRESH_TOKEN="a4e4de45-4743-481d-9345-2cfe34732fcc"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d "grant_type=refresh_token" -d "refresh_token=$REFRESH_TOKEN"

La réponse sera exactement la même que lorsque vous obtenez un jeton au départ.

Type d'autorisation "code_d'autorisation"

Le type "code autorisé" est l'approche recommandée si vous ne voulez pas stocker les informations d'identification de l'utilisateur en externe. Elle permet à DHIS2 de collecter le nom d'utilisateur et le mot de passe directement auprès de l'utilisateur au lieu que le client les collecte et s'authentifie ensuite au nom de l'utilisateur. Notez que cette approche utilise la partie redirectUris de la charge du client.

Étape 1 : Visitez l'URL suivante à l'aide d'un navigateur web. Si vous avez plus d'un URI de redirection, vous pouvez ajouter &redirect_uri=http://www.example.org à l'URL :

SERVER="https://play.dhis2.org/dev"
$SERVER/uaa/oauth/authorize?client_id=demo&response_type=code

Étape 2 : Une fois que l'utilisateur s'est connecté avec succès et a accepté votre accès client, il sera redirigé vers votre uri de redirection comme suit :

http://www.example.org/?code=XYZ

Étape 3 : Cette étape est similaire à celle du type d'autorisation "mot de passe". En utilisant le code fourni, nous allons maintenant demander un jeton d'accès :

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -u demo:$SECRET -H "Accept: application/json" $SERVER/uaa/oauth/token
-d "grant_type=authorization_code" -d "code=XYZ"

Messages d'erreur et d'information

L'API Web utilise un format cohérent pour tous les messages d'erreur, d'avertissement et d'information :

{
  "httpStatus": "Forbidden",
  "message": "Vous n'avez pas la permission de lire ce type d'objet.",
  "httpStatusCode": 403,
  "status": "ERROR"
}

Le message indique que l'utilisateur a essayé d'accéder à une ressource à laquelle je n'ai pas accès. Il utilise le code de statut http 403, le message de statut http interdit et un message descriptif.

Tableau : Propriétés de WebMessage

Format de la date et de la période

Dans l'API Web, nous faisons référence à des dates et à des périodes. Le format de la date est le suivant :

yyyy-MM-dd

For example, if you want to express March 20, 2014, you must use 2014-03-20.

Le format de la période est décrit dans le tableau suivant (également disponible dans le endpoint de l'API /api/periodTypes)

Tableau : Format de la période

Périodes relatives

In some parts of the API, like for the analytics resource, you can utilize relative periods in addition to fixed periods (defined above). The relative periods are relative to the current date and allow e.g. for creating dynamic reports. The available relative period values are described in the table below.

It is possible retrieve the ISO representations of these relative periods by making a GET request to the /api/relativePeriods/{RELATIVE_PERIOD_KEYWORD}

The endpoint supports the following parameters: - startDate: Represents the start date to calculate the relative period from. Format: yyyy-MM-dd. Default is today if not provided. - financialYearStart: Should be one of FINANCIAL_YEAR_FEBRUARY, FINANCIAL_YEAR_APRIL, FINANCIAL_YEAR_JULY, FINANCIAL_YEAR_AUGUST, FINANCIAL_YEAR_SEPTEMBER, FINANCIAL_YEAR_OCTOBER. Default is FINANCIAL_YEAR_OCTOBER if not provided.

As an example, to get the ISO representation of the relative period LAST_3_MONTHS from the date 2021-08-15, you can issue the following request: GET /api/relativePeriods/LAST_3_MONTHS?startDate=2021-08-15

The response in this case would be:

{
[
"202105",
"202106",
"202107"
]
}

Périodes de dates personnalisées

Les ressources analytiques query supportent des paramètres supplémentaires pour exprimer des périodes.

La dimension pe par défaut sera utilisée :

• eventDate pour /analytics/events/query
• enrollmentDate pour /analytics/enrollments/query

Il est possible d'ajouter des conditions sur un ou plusieurs champs de date et de les combiner.

Utilisation de périodes de dates personnalisées

Dans les ressources prenant en charge des périodes de dates personnalisées, il existe des paramètres de requête supplémentaires qui seront combinés pour exprimer des conditions sur la dimension temporelle.

Conditions can be expressed in the following format:

/api/analytics/events/query/...?...&eventDate=2021&...

Il est possible de combiner plusieurs champs temporels dans la même requête :

/api/analytics/events/query/...?...&eventDate=2021&incidentDate=202102&...

Toutes ces conditions peuvent être combinées avec la dimension pe :

/api/analytics/events/query/...?...&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&...

Les formats pris en charge sont décrits dans la section « Format de date et de période » ci-dessus. Un format supplémentaire est fourni pour exprimer un intervalle de dates : aaaaMMjj_aaaaMMjj et aaaa-MM-jj_aaaa-MM-jj.

Dans l'exemple ci-dessous, le point d'extrémité renvoie les événements prévus entre 20210101 et 20210104 :

/api/analytics/events/query/...?...&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&scheduledDate=20210101_20210104&...

Autorités

All available system authorities can be listed with identifiers and names using the following endpoint.

GET /api/authorities

Il renvoie le format suivant :

{
  "systemAuthorities": [
    {
      "id": "ALL",
      "name": "ALL"
    },
    {
      "id": "F_ACCEPT_DATA_LOWER_LEVELS",
      "name": "Accept data at lower levels"
    }
  ]
}

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 des importations et également pour envoyer 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
• categoryOptionComboIdScheme
• orgUnitIdScheme
• programIdScheme
• programStageIdScheme
• trackedEntityIdScheme
• trackedEntityAttributeIdScheme

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 DHIS2 permanents). 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 endpoint 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 endpoint spécial des traductions pour chaque ressource d'objet. Vous pouvez y accéder en utilisant GET ou PUT sur le endpoint /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 endpoint 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"
      }
    ]
  }
]