Données¶

Valeurs de données¶

Cette section traite de l'envoi et de la lecture des valeurs de données.

/api/dataValueSets

Envoi de valeurs de données¶

Pour envoyer des valeurs de données, vous pouvez lancer une requête POST à la ressource suivante.

POST /api/dataValueSets

Un cas d'utilisation courant pour l'intégration des systèmes est la nécessité d'envoyer un ensemble de valeurs de données d'un système tiers vers DHIS. Dans cet exemple, nous utiliserons la démonstration DHIS2 sur http://play.dhis2.org/demo. Supposons que nous avons collecté des données basées sur les cas à l'aide d'un simple logiciel client installé sur des téléphones portables pour l'ensemble de données Mortalité <5 ans dans la communauté du Ngelehun CHC (dans la chefferie Badjia, district Bo) pour le mois de janvier 2014. Nous avons maintenant agrégé nos données dans un rapport statistique et nous voulons envoyer ces données à l'instance DHIS2. L'URL de base de l'API de démonstration est http://play.dhis2.org/demo/api. Les liens suivants sont associés à l'URL de base.

La ressource la plus appropriée pour notre objectif d'envoi de valeurs de données est /api/dataValueSets. Un ensemble de valeurs de données représente des données qui ont une relation, généralement parce qu'elles ont été saisies dans le même formulaire. Le format ressemble à ceci :

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="dataSetID"
  completeDate="date" period="period" orgUnit="orgUnitID" attributeOptionCombo="aocID">
  <dataValue dataElement="dataElementID"
    categoryOptionCombo="cocID" value="1" comment="comment1"/>
  <dataValue dataElement="dataElementID"
    categoryOptionCombo="cocID" value="2" comment="comment2"/>
  <dataValue dataElement="dataElementID"
    categoryOptionCombo="cocID" value="3" comment="comment3"/>
</dataValueSet>

JSON est pris en charge dans ce format :

{
  "dataSet": "dataSetID",
  "completeDate": "date",
  "period": "period",
  "orgUnit": "orgUnitID",
  "attributeOptionCombo": "aocID",
  "dataValues": [
    {
      "dataElement": "dataElementID",
      "categoryOptionCombo": "cocID",
      "valeur": "1",
      "commentaire": "comment1"
    },
    {
      "dataElement": "dataElementID",
      "categoryOptionCombo": "cocID",
      "valeur": "2",
      "commentaire": "comment2"
    },
    {
      "dataElement": "dataElementID",
      "categoryOptionCombo": "cocID",
      "valeur": "3",
      "commentaire": "comment3"
    }
  ]
}

CSV est pris en charge dans ce format :

"dataelement","period","orgunit","catoptcombo","attroptcombo","value","strby","lstupd","cmt"
"dataElementID","period","orgUnitID","cocID","aocID","1","username","2015-04-01","comment1"
"dataElementID","period","orgUnitID","cocID","aocID","2","username","2015-04-01","comment2"
"dataElementID","period","orgUnitID","cocID","aocID","3","username","2015-04-01","comment3"

Note

Please refer to the date and period section above for time formats.

Note

Any imported data value which is seen as unchanged will be ignored and the import summary will reflect this. An unchanged data value is classed as one which has the same value for all 3 of these properties: - value - comment - followUp

À partir de l'exemple, nous l'importance d'identifier la période, l'ensemble de données, l'unité d'organisation (établissement) et les éléments de données qui nécessite des rapports.

Pour obtenir l'identifiant de l'ensemble de données, nous adressons une requête à la ressource /api/dataSets. De là, nous trouverons le lien vers l'ensemble de données Mortalité < 5 ans qui nous conduit à /api/dataSets/pBOMPrpg1QX. La ressource de l'ensemble de données Mortalité < 5 ans fournit des liens vers les éléments de données qu'elle abrite. D'ici nous pouvons suivre ces liens et obtenir les identifiants des données éléments. Par souci de concision, nous allons déclarer des données pour seulement trois éléments de données : Rougeole avec l'identifiant f7n9E0hX8qk, Dysenterie avec l'identifiant Ix2HsbDMLea et Choléra avec l'identifiant eY5ehpbEsB7.

Il ne nous reste que l'identifiant de l'organisation unité. L'ensemble de données fournit un lien vers les unités d'organisation qui produisent des rapports dessus. Nous recherchons donc Ngelehun CHC et suivons le lien vers la représentation HTML dans /api/organisationUnits/DiszpKrYNg8, qui nous indique que l'identifiant de cette unité d'organisation est DiszpKrYNg8.

À partir de nos données basées sur les cas, nous supposons que nous avons 12 cas de rougeole, 14 cas de dysenterie et 16 cas de choléra. Nous avons maintenant assez d'informations pour pouvoir composer le message XML de l'ensemble de valeurs des données :

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX"
  completeDate="2014-02-03" period="201401" orgUnit="DiszpKrYNg8">
  <dataValue dataElement="f7n9E0hX8qk" value="12"/>
  <dataValue dataElement="Ix2HsbDMLea" value="14"/>
  <dataValue dataElement="eY5ehpbEsB7" value="16"/>
</dataValueSet>

Au format JSON :

{
  "dataSet": "pBOMPrpg1QX",
  "completeDate": "03/02/2014",
  "période": "201401",
  "orgUnit": "DiszpKrYNg8",
  "dataValues": [
    {
      "dataElement": "f7n9E0hX8qk",
      "valeur": "1"
    },
    {
      "dataElement": "Ix2HsbDMLea",
      "valeur": "2"
    },
    {
      "dataElement": "eY5ehpbEsB7",
      "valeur": "3"
    }
  ]
}

Pour effectuer des tests fonctionnels, nous utiliserons l'outil curl qui permet de transférer facilement des données à l'aide du protocole HTTP. Tout d'abord, nous sauvegardons le contenu XML de l'ensemble de données dans un fichier appelé datavalueset.xml. Dans le répertoire où se trouve ce fichier, nous invoquons ce qui suit à partir de la ligne de commande :

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

Pour envoyer du contenu JSON, vous devez définir l'en-tête "type de contenu" comme suit :

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

La commande enverra une requête à l'API Web de démonstration, définissez application/xml comme type de contenu et authentifiez-vous en utilisant admin/district comme nom d'utilisateur/mot de passe. Si tout se passe bien, le code d'état HTTP 200 OK sera renvoyé. Vous pouvez vérifier la réception des données en ouvrant le module de saisie de données dans DHIS2 et en sélectionnant l'unité d'organisation, l'ensemble de données et la période utilisés dans cet exemple.

L'API suit la sémantique normale pour la gestion des erreurs et les codes d'état HTTP. Si vous fournissez un nom d'utilisateur ou un mot de passe invalide, 401 Non autorisé est renvoyé. Si vous fournissez un type de contenu autre que application/xml, 415 Type de média non pris en charge est renvoyé. Si le contenu XML n'est pas valide selon l'espace de noms DXF, 400 Mauvaise requête est renvoyé. Si vous fournissez un identifiant invalide dans le contenu XML, 409 Conflit est renvoyé avec un message descriptif.

Envoi de données en masse¶

L'exemple précédent nous a montré comment envoyer un ensemble de données associées qui partagent la même période et la même unité d’organisation. L'exemple suivant nous montrera comment envoyer de grandes quantités de données qui ne sont pas nécessairement associés.

Encore une fois, nous interagirons avec la ressource /api/dataValueSets. Cette fois nous n'allons pas spécifier les attributs dataSet et completeDate. De plus, nous allons spécifiez les attributs period et orgUnit comme éléments de données individuelles et non élément d’ensemble de données externes. Cela nous permettra d'envoyer des données pour différentes périodes et unités d'organisation :

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0">
  <dataValue dataElement="f7n9E0hX8qk"
    period="201401" orgUnit="DiszpKrYNg8" value="12"/>
  <dataValue dataElement="f7n9E0hX8qk"
    period="201401" orgUnit="FNnj3jKGS7i" value="14"/>
  <dataValue dataElement="f7n9E0hX8qk"
    period="201402" orgUnit="DiszpKrYNg8" value="16"/>
  <dataValue dataElement="f7n9E0hX8qk"
    period="201402" orgUnit="Jkhdsf8sdf4" value="18"/>
</dataValueSet>

Au format JSON :

{
  "dataValues": [
    {
      "dataElement": "f7n9E0hX8qk",
      "période": "201401",
      "orgUnit": "DiszpKrYNg8",
      "valeur": "12"
    },
    {
      "dataElement": "f7n9E0hX8qk",
      "période": "201401",
      "orgUnit": "FNnj3jKGS7i",
      "valeur": "14"
    },
    {
      "dataElement": "f7n9E0hX8qk",
      "période": "201402",
      "orgUnit": "DiszpKrYNg8",
      "valeur": "16"
    },
    {
      "dataElement": "f7n9E0hX8qk",
      "période": "201402",
      "orgUnit": "Jkhdsf8sdf4",
      "valeur": "18"
    }
  ]
}

Au format CSV :

"dataelement","period","orgunit","categoryoptioncombo","attributeoptioncombo","value"
"f7n9E0hX8qk","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","1"
"Ix2HsbDMLea","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","2"
"eY5ehpbEsB7","201401","DiszpKrYNg8","bRowv6yZOF2","bRowv6yZOF2","3"

Nous effectuons les tests en utilisant "curl" pour envoyer les données au format XML :

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

Notez que lorsque vous utilisez le format CSV, vous devez utiliser l'option de données binaires pour conserver le retour-à-la-ligne dans le fichier CSV :

curl --data-binary @datavalueset.csv "https://play.dhis2.org/demo/24/api/dataValueSets"
  -H "Content-Type:application/csv" -u admin:district

La ressource ensemble de valeurs de données fournit une réponse XML qui est utile lorsque vous voulez vérifier l'impact de votre requête. La première fois que nous envoyons la requête " ensemble de données " ci-dessus, le serveur répondra avec le résumé d'importation suivant :

<importSummary>
  <dataValueCount imported="2" updated="1" ignored="1"/>
  <dataSetComplete>faux</dataSetComplete>
</importSummary>

Ce message nous indique que 3 données ont été importées, 1 donnée a été mise à jour et 0 donnée a été ignorée. La seule mise à jour résulte de l'envoi de cette donnée dans l'exemple précédent. Une donnée sera ignorée si elle fait référence à un élément de données, une période, une unité d'organisation ou un ensemble de données qui n'existent pas. Dans notre cas, cette valeur unique ignorée est due au fait que la dernière donnée faisait référence à une unité d'organisation non valide. L'élément complet de l'ensemble de données affichera la date à laquelle l'ensemble de données a été achevé, ou " faux " si aucun attribut d'élément de données n'a été fourni.

Paramètres d'importation¶

The import process can be customized using a set of import parameters.

Tableau : Paramètres d'importation

Tous les paramètres sont facultatifs et peuvent être fournis en tant que paramètres de requête dans l'URL de la requête comme suit :

/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name
  &dryRun=true&importStrategy=CREER

Ils peuvent également être fournis en tant qu'attributs XML sur l'élément " ensemble de valeurs de données ", tel qu'indiqué ci-dessous. Les attributs XML remplacent les paramètres de la chaîne de requête.

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataElementIdScheme="code"
  orgUnitIdScheme="name" dryRun="true" importStrategy="CREATE">
</dataValueSet>

Notez que le paramètre preheatCache peut avoir un impact considérable sur les performances. Pour les petits fichiers d'importation, maintenir "faux" permettra de gagner en rapidité. Pour les gros fichiers d'importation qui contiennent un grand nombre d'éléments de données et d'unités d'organisation distincts, le définir sur "vrai" permettra de gagner en rapidité en termes d'ordre de grandeur.

Exigences en matière de valeur des données¶

L’importation de valeurs de données prend en charge un ensemble de types de valeurs. Chaque type de valeur a une exigence particulière. Le tableau suivant répertorie les cas extrêmes pour les types valeur.

Tableau : Exigences relatives au type de valeur

Schémas d'identification¶

En ce qui concerne les schémas d'identification, les identifiants utilisés dans les messages XML utilisent par défaut les identifiants d'objets stables de DHIS2 appelés UID. Dans certaines situations d'interopérabilité, il se peut qu'un système externe détermine les identifiants des objets. Dans ce cas, nous pouvons utiliser la propriété code des unités d'organisation et d'autres objets pour définir des identifiants fixes. Lors de l'importation des valeurs de données, nous devons donc référencer la propriété "code" et non la propriété "identifiant" de ces objets de métadonnées. Les schémas d'identification peuvent être spécifiés dans le message XML ainsi que dans la requête en tant que paramètres de requête. Pour les spécifier dans la charge utile XML, vous pouvez procéder comme suit :

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0"
  dataElementIdScheme="CODE" orgUnitIdScheme="UID" idScheme="CODE">
</dataValueSet>

Le tableau des paramètres ci-dessus explique comment les schémas d'identification peuvent être spécifiés comme paramètres de requête. Les règles suivantes déterminent l'ordre de priorité :

• Les schémas d'identification définis dans la charge utile XML ou JSON ont priorité sur les schémas d'identification définis comme paramètres de requête URL.

• Les schémas d'identification spécifiques tels que dataElementIdScheme ou orgUnitIdScheme ont priorité sur le schéma d'identification général.

• Si aucun schéma d'identification explicite n'est défini, le schéma d'identification par défaut est code pour le format ADX et uid pour tous les autres formats.

Les schémas d'identification suivants sont disponibles.

• uid

• code

• nom

• attribut (suivi de l'UID de l'attribut)

L'option d'attribut est spéciale et fait référence aux attributs de métadonnées qui ont été marqués comme uniques. En utilisant cette option, l'attribut doit être immédiatement suivi de l'identifiant de l'attribut, par exemple "attribut : DnrLSdo4hMl".

Importation de valeurs de données asynchrones¶

Les valeurs de données peuvent être envoyées et importées de manière asynchrone à travers un paramètre de requête async défini sur vrai :

/api/dataValueSets?async=vrai

Cela lancera une tâche d'importation asynchrone dont vous pourrez surveiller l'état grâce à l'API de résumés des tâches. La réponse de l'API indique l'identifiant unique de la tâche, du type de tâche et de l'URL que vous pouvez utiliser pour surveiller l’état de l'importation. La réponse ressemblera à ceci :

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Initiated dataValueImport",
  "response": {
    "name": "dataValueImport",
    "id": "YR1UxOUXmzT",
    "created": "2018-08-20T14:17:28.429",
    "jobType": "DATAVALUE_IMPORT",
    "relativeNotifierEndpoint": "/api/system/tasks/DATAVALUE_IMPORT/YR1UxOUXmzT"
  }
}

Veuillez lire la section sur l'état des tâches asynchrones pour en savoir plus.

Format des valeurs de données CSV¶

La section suivante décrit le format CSV utilisé dans DHIS2. La première ligne est supposée être une ligne d'en-tête et sera ignorée lors de l'importation.

Tableau : format CSV de DHIS2

Ci-dessous un exemple de fichier CSV pouvant être importé dans DHIS2 :

"dataelement","period","orgunit","catoptcombo","attroptcombo","value","storedby","timestamp"
"DUSpd8Jq3M7","201202","gP6hn503KUX","Prlt0C1RF0s",,"7","bombali","2010-04-17"
"DUSpd8Jq3M7","201202","gP6hn503KUX","V6L425pT3A0",,"10","bombali","2010-04-17"
"DUSpd8Jq3M7","201202","OjTS752GbZE","V6L425pT3A0",,"9","bombali","2010-04-06"

Génération d'un modèle d'ensemble de valeurs de données¶

Pour générer un modèle d'ensemble de valeurs de données pour un ensemble de données spécifique, vous pouvez utiliser la ressource /api/dataSets/<id>/dataValueSet. les formats de réponse XML et JSON sont pris en charge. Exemple:

/api/dataSets/BfMAe6Itzgt/dataValueSet

Ci-dessous les paramètres que vous pouvez utiliser pour ajuster davantage la sortie :

Tableau : Paramètres de requête de valeurs de données

Lecture des valeurs de données¶

Pour lire les valeurs de données, vous pouvez effectuer une requête GET à la ressource suivante.

GET /api/dataValueSets

Data values can be retrieved in XML, JSON, CSV, and ADX format. Since we want to read data we will use the GET HTTP verb. We will also specify that we are interested in the XML resource representation by including an Accept HTTP header with our request. The following query parameters are available.

Tableau : Paramètres de requête d'ensemble de valeurs de données

Les paramètres suivants provenant de la liste ci-dessus sont requis : - dataSet ou dataElementGroup (pour le format ADX, cela doit être dataSet) - period, (startDate et endDate), lastUpdated, ou lastUpdatedDuration - orgUnit ou orgUnitGroup

Les formats de réponse suivants sont pris en charge :

• xml (application/xml)

• json (application/json)

• csv (application/csv)

• adx (application/adx+xml)

En supposant que nous avons publié les valeurs de données dans DHIS2 conformément à la section précédente intitulée Envoi de valeurs de données, nous pouvons maintenant constituer notre requête pour un ensemble de valeurs de données unique et l'exécuter en utilisant cURL :

curl "https://play.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8"
  -H "Accept:application/xml" -u admin:district

Nous pouvons également utiliser les paramètres de requête "date de début" et "date de fin" pour demander un plus grand nombre de valeurs de données. En d'autres termes, vous pouvez également solliciter des valeurs de données pour plusieurs ensembles de données, unités d'organisation et périodes afin d'exporter de plus grandes quantités de données. Notez que le paramètre de requête "période" est prioritaire sur les paramètres "date de début" et "date de fin". Voici un exemple :

curl "https://play.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt
  &startDate=2013-01-01&endDate=2013-01-31&orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true"
  -H "Accept:application/xml" -u admin:district

Pour récupérer les valeurs de données qui ont été créées ou mises à jour au cours des 10 derniers jours, vous pouvez effectuer la requête suivante :

/api/dataValueSets?dataSet=pBOMPrpg1QX&orgUnit=DiszpKrYNg8&lastUpdatedDuration=10d

La réponse ressemblera à ceci :

<?xml version='1.0' encoding='UTF-8'?>
<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX"
  completeDate="2014-01-02" period="201401" orgUnit="DiszpKrYNg8">
<dataValue dataElement="eY5ehpbEsB7" period="201401" orgUnit="DiszpKrYNg8"
  categoryOptionCombo="bRowv6yZOF2" value="10003"/>
<dataValue dataElement="Ix2HsbDMLea" period="201401" orgUnit="DiszpKrYNg8"
  categoryOptionCombo="bRowv6yZOF2" value="10002"/>
<dataValue dataElement="f7n9E0hX8qk" period="201401" orgUnit="DiszpKrYNg8"
  categoryOptionCombo="bRowv6yZOF2" value="10001"/>
</dataValueSet>

Vous pouvez demander à ce que les données soient rendues au format JSON de la manière suivante :

/api/dataValueSets.json?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8

La réponse ressemblera à ceci :

{
  "dataSet": "pBOMPrpg1QX",
  "completeDate": "2014-02-03",
  "period": "201401",
  "orgUnit": "DiszpKrYNg8",
  "dataValues": [
    {
      "dataElement": "eY5ehpbEsB7",
      "categoryOptionCombo": "bRowv6yZOF2",
      "period": "201401",
      "orgUnit": "DiszpKrYNg8",
      "value": "10003"
    },
    {
      "dataElement": "Ix2HsbDMLea",
      "categoryOptionCombo": "bRowv6yZOF2",
      "period": "201401",
      "orgUnit": "DiszpKrYNg8",
      "value": "10002"
    },
    {
      "dataElement": "f7n9E0hX8qk",
      "categoryOptionCombo": "bRowv6yZOF2",
      "period": "201401",
      "orgUnit": "DiszpKrYNg8",
      "value": "10001"
    }
  ]
}

Notez que les valeurs de données sont mises en corbeille, c'est-à-dire qu'une valeur supprimée a la propriété supprimée définie sur "vrai" et n'est pas supprimée de façon permanente. Ceci est utile lors de l'intégration de plusieurs systèmes afin de signaler les suppressions. Vous pouvez inclure les valeurs supprimées dans la réponse comme suit :

/api/dataValueSets.json?dataSet=pBOMPrpg1QX&period=201401
  &orgUnit=DiszpKrYNg8&includeDeleted=true

Vous pouvez également demander à ce que les données soient rendues au format CSV de la manière suivante :

/api/dataValueSets.csv?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8

La réponse ressemblera à ceci :

dataelement,period,orgunit,catoptcombo,attroptcombo,value,storedby,lastupdated,comment,flwup
f7n9E0hX8qk,201401,DiszpKrYNg8,bRowv6yZOF2,bRowv6yZOF2,12,system,2015-04-05T19:58:12.000,comment1,false
Ix2HsbDMLea,201401,DiszpKrYNg8,bRowv6yZOF2,bRowv6yZOF2,14,system,2015-04-05T19:58:12.000,comment2,false
eY5ehpbEsB7,201401,DiszpKrYNg8,bRowv6yZOF2,bRowv6yZOF2,16,system,2015-04-05T19:58:12.000,comment3,false
FTRrcoaog83,201401,DiszpKrYNg8,bRowv6yZOF2,bRowv6yZOF2,12,system,2014-03-02T21:45:05.519,comment4,false

Request data values in CSV format compressed with gzip:

/api/dataValueSets.csv?dataSet=pBOMPrpg1QX&period=202401&orgUnit=DiszpKrYNg8&compression=gzip

The response will be in compressed CSV format. The content can be uncompressed with the gunzip tool.

Les contraintes suivantes s'appliquent à la ressource Ensembles de valeurs de données :

• Au moins un ensemble de données doit être spécifié.

• Soit au moins une période, soit une date de début et une date de fin doivent être spécifié.

• Au moins une unité d'organisation doit être spécifiée.

• Les unités d'organisation doivent faire partie de la hiérarchie des unités d'organisation de l’utilisateur authentifié.

• La limite ne peut pas être inférieure à zéro.

Envoi, lecture et suppression de valeurs de données individuelles¶

Cet exemple montrera comment envoyer des valeurs de données individuelles à enregistrer dans une requête. Ceci peut être réalisé par l'envoi d'une requête POST à la ressource dataValues :

POST /api/dataValues

Les paramètres de requête suivants sont pris en charge pour cette ressource :

Tableau : Paramètres de requête de valeurs de données

Si l'un des identifiants fournis n'est pas valide, si la valeur de données ou le commentaire n'est pas valide ou si les données sont verrouillées, la réponse contiendra le code d'état 409 Conflit et un message texte descriptif. Si l'opération conduit à une valeur enregistrée ou mise à jour, 200 OK sera renvoyé. Ci-après, un exemple de requête :

curl "https://play.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu
  &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12"
  -X POST -u admin:district

Cette ressource permet également une syntaxe spéciale pour associer la valeur à une combinaison d'options d'attribut. Pour ce faire, il suffit d'envoyer l'identifiant de la combinaison de catégories d'attribut, ainsi que les identifiants des options de catégories d'attribut que la valeur représente au sein de la combinaison. La combinaison de catégories est spécifiée avec le paramètre cc, tandis que les options de catégorie sont spécifiées sous la forme d'une chaîne de caractères séparés par des points-virgules avec le paramètre cp. Il faut s'assurer que les options de catégorie font toutes partie de la combinaison de catégories. Voici un exemple :

curl "https://play.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&ou=DiszpKrYNg8
  &pe=201308&cc=dzjKKQq0cSO&cp=wbrDrL2aYEc;btOyqprQ9e8&value=26"
  -X POST -u admin:district

Vous pouvez récupérer une valeur de données avec une requête en utilisant la méthode GET. Les paramètres de valeur, de commentaire et de suivi ne sont pas applicables ici :

curl "https://play.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu
  &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s"
  -u admin:district

Vous pouvez supprimer une valeur de données avec une requête en utilisant la méthode DELETE.

Envoi de valeurs de données individuelles sous forme de charge utile¶

Vous pouvez envoyer des valeurs de données individuelles sous forme de charge utile JSON en utilisant la ressource suivante avec Content-Type : application/json.

POST /api/dataValues

La ressource créera une nouvelle valeur de données ou mettra à jour une valeur de données si elle existe déjà. Le format de charge utile JSON est défini ci-dessous.

{
  "dataElement": "fbfJHSPpUQD",
  "categoryOptionCombo": "PT59n8BQbqM",
  "period": "202201",
  "orgUnit": "DiszpKrYNg8",
  "value": "10",
  "comment": "OK"
}

Le point d'extrémité prend en charge la spécification de combinaisons d’options d’attribut dans une structure imbriquée.

{
  "dataElement": "BOSZApCrBni",
  "categoryOptionCombo": "TkDhg29x18A",
  "attribute": {
    "combo": "O4VaNks6tta",
    "options": [
      "C6nZpLKjEJr", "i4Nbp8S2G6A"
    ]
  },
  "dataSet": "lyLU2wR22tC",
  "period": "202201",
  "orgUnit": "DiszpKrYNg8",
  "value": "15",
  "comment": "Good"
}

Le code d'état sera 201 Créé si la valeur de données a été enregistrée ou mise à jour avec succès, ou 409 Conflit en cas d'erreur de validation.

Utilisation des valeurs de données de fichiers¶

Lorsqu'il s'agit de valeurs de données dont l'élément de données est de type fichier, la méthode décrite ci-dessus ne s'applique plus. Ces valeurs de données sont spéciales dans la mesure où le contenu de la valeur est une référence UID à un objet Ressource de fichier et non une constante autonome. Ces valeurs de données se comportent comme les autres valeurs de données qui stockent du contenu textuel, mais elles doivent être traitées différemment afin de produire des entrées et des sorties pertinentes.

Il existe deux méthodes pour stocker les valeurs de données des ressources de fichiers.

• Téléchargez le fichier sur le point d'extrémité /api/dataValues/file tel que décrit dans la section des ressources de fichiers. Cela fonctionne avec les versions 2.36 et supérieures.

• Si vous écrivez un code qui doit être compatible avec les versions DHIS2 inférieures à la 2.36, alors le processus est le suivant :

• Téléchargez le fichier sur le point d'extrémité /api/fileResources tel que décrit dans la section des ressources de fichiers.

• Récupérez la propriété id de la ressource de fichier renvoyée.

• Stockez l'identifiant récupéré avec la propriété valeur de la valeur de données et en utilisant l'une des méthodes décrites ci-dessus.

Seules les relations un à un entre les valeurs de données et les ressources de fichiers sont autorisées. Cette règle est appliquée en interne, de sorte que l'enregistrement de l'identifiant d'une ressource de fichier dans plusieurs valeurs de données ne soit pas possible et entraîne une erreur. La suppression de la valeur de données entraîne la suppression de la ressource de fichier référencée. La suppression directe des ressources de fichiers n'est pas possible.

La valeur de données peut maintenant être récupérée normalement, mais c'est l'UID de la ressource du fichier qui sera renvoyé. Afin de récupérer le vrai contenu (c'est-à-dire le fichier stocké dans la ressource associée à la valeur de données), vous devez effectuer une requête GET à /api/dataValues/files en reproduisant les paramètres de la valeur de données elle-même. Le point d'extrémité /api/dataValues/files ne prend en charge que les requêtes GET.

Il convient de noter qu'en raison du fonctionnement asynchrone du mécanisme de stockage sous-jacent, le contenu du fichier peut ne pas être immédiatement téléchargeable à partir du point d'extrémité /api/dataValues/files. Ceci est particulièrement valable pour les fichiers volumineux qui peuvent nécessiter des téléchargements en arrière-plan vers un entrepôt de fichiers externe (en fonction de la configuration du système). Récupérer les métadonnées de la ressource du fichier à partir du point d'extrémité /api/fileResources/<id> permet de vérifier le storageStatus (état du stockage) du contenu avant d'essayer de le télécharger.

Format de données ADX¶

Depuis la version 2.20, nous prenons en charge une norme internationale d'échange de données agrégées appelée ADX. ADX est développé et maintenu par le comité Quality, Research and Public Health (Qualité, Recherche et Santé Publique) de l'IHE (Integrating the HealthCare Enterprise). La page wiki décrivant les activités du comité QRPH se trouve à l'adresse wiki.ihe.net. ADX fait toujours l'objet d'un développement actif et a maintenant été publié pour une implémentation à titre expérimental. Notez qu'actuellement, c'est la fonctionnalité de lecture et d'écriture des données formatées ADX qui est implémentée dans DHIS2, c'est-à-dire ce qui est décrit comme acteurs Consommateur de Contenu et Producteur de Contenu dans le profil ADX.

La structure d'un message de données ADX est assez similaire à celle des données DXF 2 décrites précédemment et que vous connaissez probablement. Il existe quelques différences importantes. Nous les décrirons à l'aide d'un petit exemple :

<adx xmlns="urn:ihe:qrph:adx:2015" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:ihe:qrph:adx:2015 ../schema/adx_loose.xsd"
  exported="2015-02-08T19:30:00Z">
  <group orgUnit="OU_559" period="2015-06-01/P1M"
    completeDate="2015-07-01" dataSet="(TB/HIV)VCCT">
    <dataValue dataElement="VCCT_0" GENDER="FMLE" HIV_AGE="AGE0-14" value="32"/>
    <dataValue dataElement="VCCT_1" GENDER="FMLE" HIV_AGE="AGE0-14" value="20"/>
    <dataValue dataElement="VCCT_2" GENDER="FMLE" HIV_AGE="AGE0-14" value="10"/>
    <dataValue dataElement="PLHIV_TB_0" GENDER="FMLE" HIV_AGE="AGE0-14" value="10"/>
    <dataValue dataElement="PLHIV_TB_1" GENDER="FMLE" HIV_AGE="AGE0-14" value="10"/>

    <dataValue dataElement="VCCT_0" GENDER="MLE" HIV_AGE="AGE0-14" value="32"/>
    <dataValue dataElement="VCCT_1" GENDER="MLE" HIV_AGE="AGE0-14" value="20"/>
    <dataValue dataElement="VCCT_2" GENDER="MLE" HIV_AGE="AGE0-14" value="10"/>
    <dataValue dataElement="PLHIV_TB_0" GENDER="MLE" HIV_AGE="AGE0-14" value="10"/>
    <dataValue dataElement="PLHIV_TB_1" GENDER="MLE" HIV_AGE="AGE0-14" value="10"/>

    <dataValue dataElement="VCCT_0" GENDER="FMLE" HIV_AGE="AGE15-24" value="32"/>
    <dataValue dataElement="VCCT_1" GENDER="FMLE" HIV_AGE="AGE15-24" value="20"/>
    <dataValue dataElement="VCCT_2" GENDER="FMLE" HIV_AGE="AGE15-24" value="10"/>
    <dataValue dataElement="PLHIV_TB_0" GENDER="FMLE" HIV_AGE="AGE15-24" value="10"/>
    <dataValue dataElement="PLHIV_TB_1" GENDER="FMLE" HIV_AGE="AGE15-24" value="10"/>

    <dataValue dataElement="VCCT_0" GENDER="MLE" HIV_AGE="AGE15-24" value="32"/>
    <dataValue dataElement="VCCT_1" GENDER="MLE" HIV_AGE="AGE15-24" value="20"/>
    <dataValue dataElement="VCCT_2" GENDER="MLE" HIV_AGE="AGE15-24" value="10"/>
    <dataValue dataElement="PLHIV_TB_0" GENDER="MLE" HIV_AGE="AGE15-24" value="10"/>
    <dataValue dataElement="PLHIV_TB_1" GENDER="MLE" HIV_AGE="AGE15-24" value="10"/>
  </group>
</adx>

L'élément racine ADX¶

L'élément racine ADX n'a qu'un seul attribut obligatoire, qui est l'horodatage exporté. Comme d'autres éléments ADX, le schéma est extensible dans le sens où il ne restreint pas les attributs spécifiques d'applications supplémentaires.

L'élément de groupe ADX¶

Contrairement à dxf2, ADX exige que les valeurs de données soient regroupées par unité d'organisation, période et ensemble de données. L'exemple ci-dessus montre un rapport de données pour l'ensemble de données "( TB/VIH) VCCT" de la base de données de démonstration en ligne. Cet exemple utilise des codes comme identifiants et non des uids dhis2. Le code est la forme d'identifiant recommandée lors de l'utilisation d'ADX.

Les attributs d'unité d'organisation, de période et d'ensemble de données sont obligatoires dans ADX. L'élément de groupe peut contenir des attributs supplémentaires. Dans notre implémentation de DHIS2, tout attribut supplémentaire est simplement transmis à l'importateur sous-jacent. Cela signifie que tous les attributs qui ont actuellement une signification dans dxf2 (comme completeDate dans l'exemple ci-dessus) peuvent continuer à être utilisés dans ADX et seront traités de la même manière.

Une différence importante entre ADX et dxf2 réside dans la manière dont les périodes sont encodées. ADX utilise strictement la norme ISO8601 et encode la période de déclaration sous la forme (date|heure) / (durée). Dans l'exemple ci-dessus, la période est donc une période d'un mois (P1M) qui commence le 01-06-2015. Il s'agit donc des données de juin 2015. La notation est un peu plus longue, mais elle est très souple et nous permet de prendre en charge tous les types de période existants dans DHIS2.

Définitions des périodes ADX¶

Les périodes commencent par la date à laquelle la durée commence, suivie d'un "/" et de la notation de la durée, comme indiqué dans le tableau. Le tableau suivant détaille tous les types de période dans DHIS2 et la manière dont ils sont représentés en ADX, ainsi que des exemples.

Tableau : Périodes ADX

Valeurs de données ADX¶

L'élément "valeur de données" dans ADX est très similaire à son équivalent dans DXF. Les attributs obligatoires sont élément de données et valeur. Les attributs unité d'organisation et période n'apparaissent pas dans l'élément "valeur de données" car ils sont requis au niveau groupe.

La différence la plus significative est la manière dont la désagrégation est représentée. DXF utilise la combinaison d'options de catégorie pour représenter la désagrégation des données. Dans ADX, les désagrégations (par exemple GROUPE_D'ÂGE et SEXE) sont exprimées explicitement en tant qu'attributs. Si vous utilisez code comme schéma d'identification pour catégorie, vous devez attribuer un code à toutes les catégories utilisées pour les éléments de données de l'ensemble de données et, de plus, ce code doit pouvoir être utilisé en tant qu'attribut XML. La contrainte concernant un nom d'attribut XML est décrite dans la norme XML du W3C. En pratique, cela signifie qu'il n'y a pas d'espaces, pas de caractères non alphanumériques autres que "_" et que le nom ne peut pas commencer par une lettre. L'exemple ci-dessus montre des exemples de "bons" codes de catégorie ("GENRE" et "ÂGE_VIH"). Les mêmes restrictions s'appliquent si vous utilisez nom ou attribut comme schémas d'identification.

Dans ADX, seuls les identifiants de catégorie sont utilisés comme attributs XML ; les identifiants d'autres types de métadonnées ne doivent pas être utilisés comme attributs XML. Notez que cette syntaxe n'est pas appliquée par DHIS2 lorsque vous attribuez des noms, des codes ou des attributs DHIS2, mais vous obtiendrez un message d'erreur avec une explication si vous essayez d'importer des données ADX et que les identifiants de catégorie ne sont pas attribués ou ne conviennent pas.

Les principaux avantages de l’utilisation de dimensions explicites de données désagrégées sont les suivants :

• Le système qui produit les données n'a pas besoin d'être synchronisé avec la combinaison d'options de catégorie dans DHIS2.

• Le producteur et le consommateur peuvent faire correspondre leurs codes à une source tierce qui fait autorité, telle qu'un service de terminologie. Notez que dans l'exemple ci-dessus, les codes de genre et de groupe d'âge utilisent des listes de codes de l'Observatoire mondial de la santé de l'OMS.

Cette fonction peut être très utile, par exemple pour produire des données désagrégées à partir d'un système de DME, mais il peut arriver qu'un mapping de combinaison d'options de catégorie soit plus facile ou plus souhaitable. L'implémentation d'ADX dans DHIS2 permettra de vérifier l'existence d'un attribut de combinaison d'options de catégorie et, s'il existe, de l'utiliser au lieu des attributs de dimension ventilés. De même, un attribut de combinaison d'options d'attributs sur l'élément groupe sera traité de la même manière que les attributs existants. Sinon, la combinaison d'options d'attributs peut être utilisée comme catégories ventilées, comme pour la valeur de données.

Dans l'exemple simple ci-dessus, tous les éléments de données de l'ensemble de données ont la même dimensionnalité (combinaison de catégories), ce qui rend les données parfaitement rectangulaires. Les ensembles de données peuvent contenir des éléments de données ayant des combinaisons de catégories différentes, ce qui donne un message de données ADX décalé vers la droite (c'est-à-dire que les valeurs des différents éléments de données peuvent avoir des nombres de catégories différents).

Importation de données ADX¶

DHIS2 expose un point d'extrémité pour les données POST ADX à /api/dataValueSets en utilisant application/xml+adx comme type de contenu. Ainsi, par exemple, la commande curl suivante peut être utilisée pour POST (envoyer) les données de l'exemple ci-dessus au serveur de démonstration DHIS2 :

curl -u admin:district -X POST -H "Content-Type: application/adx+xml"
  -d @data.xml "https://play.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=code"

Notez que les paramètres de requête sont les mêmes que ceux utilisés avec les données DXF. Le point d'extrémité ADX doit interpréter tous les paramètres DXF existants avec la même sémantique que DXF.

Exportation de données ADX¶

DHIS2 expose un point d'extrémité pour les ensembles de données GET ADX dans /api/dataValueSets en utilisant application/xml+adx comme type de contenu. Ainsi, par exemple, la commande curl suivante peut être utilisée pour récupérer les données ADX :

curl -u admin:district -H "Accept: application/adx+xml"
 "https://play.dhis2.org/demo/api/dataValueSets?dataValueSets?orgUnit=M_CLINIC&dataSet=MALARIA&period=201501"

Notez que les paramètres de requête sont les mêmes que ceux utilisés avec les données DXF. Une différence importante est que les identifiants d'ensemble de données et d'unité d'organisation peuvent être soit des uids, soit des codes.

Suivi¶

Cette section traite du marquage des données pour le suivi.

Suivi de la valeur de données¶

Le point d'extrémité du suivi des valeurs de données permet de marquer les valeurs de données pour le suivi.

PUT /api/36/dataValues/followup

La charge utile au format JSON ressemble à ceci :

{
  "dataElement": "s46m5MS0hxu",
  "period": "202005",
  "orgUnit": "DiszpKrYNg8",
  "categoryOptionCombo": "psbwp3CQEhs",
  "attributeOptionCombo": "HllvX50cXC0",
  "followup": true
}

Les champs combinaison d'options de catégorie et combinaison d'options d'attributs sont facultatifs. Une charge utile JSON minimale ressemble à ceci :

{
  "dataElement": "s46m5MS0hxu",
  "period": "202005",
  "orgUnit": "DiszpKrYNg8",
  "followup": false
}

Le champ suivi doit être défini sur vrai pour marquer une valeur de données pour le suivi, et sur faux pour retirer le marquage.

Le code d'état de la réponse sera 200 OK si l'opération réussit, et 409 Conflit en cas d'erreur avec la requête.

Pour mettre à jour plusieurs valeurs de données à la fois pour le suivi :

PUT /api/dataValues/followups

avec la charge utile JSON :

{
  "values": [
    {
      "dataElement": "s46m5MS0hxu",
      "period": "202005",
      "orgUnit": "DiszpKrYNg8",
      "categoryOptionCombo": "psbwp3CQEhs",
      "attributeOptionCombo": "HllvX50cXC0",
      "followup": true
    }
  ]
}

Chaque élément de cette mise à jour comporte les mêmes champs et exigences que le point d'extrémité de la mise à jour unique.

La mise à jour groupée renvoie également 200 OK en cas de succès ou 409 Conflit en cas d'erreurs dans la requête.