Validation de données¶

Validation¶

Pour générer un résumé de validation des données, vous pouvez interagir avec la ressource de validation. La ressource "ensemble de données" est optimisée pour les clients chargés de la saisie des données et de la validation d'un ensemble de données ou d'un formulaire. Elle est accessible de la manière suivante :

GET /api/33/validation/dataSet/QX4ZTUbOt3a.json?pe=201501&ou=DiszpKrYNg8

En plus de la validation des règles basées sur un ensemble de données, il existe deux méthodes supplémentaires de validation : validation personnalisée et validation programmée.

La première variable de chemin d'accès est un identifiant qui fait référence à l'ensemble de données à valider. Les représentations XML et JSON des ressources sont prises en charge. La réponse contient les violations des règles de validation. Cette fonction sera étendue à d'autres types de validation dans les versions à venir.

Pour récupérer les règles de validation relatives à un ensemble de données spécifique, c'est-à-dire les règles de validation avec des formules où tous les éléments de données font partie de l'ensemble de données en question, vous pouvez effectuer une requête GET à la ressource validationRules de la manière suivante :

GET /api/validationRules?dataSet=<dataset-id>

Les règles de validation ont un côté gauche et un côté droit, dont la validité est comparée en fonction d'un opérateur. Les valeurs valides de l'opérateur sont indiquées dans le tableau ci-dessous.

Tableau : Opérateurs

Les expressions du côté gauche et du côté droit sont des expressions mathématiques qui peuvent contenir des références à des éléments de données et à des combinaisons d'options de catégorie au format suivant :

${<dataelement-id>.<catoptcombo-id>}

Les expressions du côté gauche et du côté droit ont une stratégie de valeur manquante. Cette stratégie indique comment le système doit traiter les valeurs de données manquantes pour les références d'éléments de données ou de combinaisons d'options de catégorie dans la formule, en déterminant si la règle de validation doit être vérifiée ou ignorée. Les stratégies de valeurs manquantes valides sont présentées dans le tableau ci-dessous.

Tableau : Stratégies de valeur manquante

Résultats de la validation¶

Les résultats de validation sont les résultats des violations constatées lors d'une analyse de validation. Si vous choisissez "conserver les résultats" lorsque vous lancez ou programmez une analyse de validation, toutes les violations constatées seront stockées dans la base de données. Lorsqu'un résultat est stocké dans la base de données, il est utilisé à trois fins :

1. Générer des analyses basées sur les résultats stockés.

2. Les résultats qui n'ont pas généré de notification le feront, une fois.

3. Garder la trace des résultats qui ont généré ou non une notification.

4. Ignorer les règles déjà vérifiées lors de l'analyse de validation.

Cela signifie que si vous ne conservez pas vos résultats, vous ne pourrez pas générer d'analyses pour les résultats de validation. Si cette option est sélectionnée, les résultats généreront des notifications à chaque fois qu'il y en aura et l'analyse de validation pourrait être plus lente.

Résultats de la validation de la requête¶

Les résultats de validation conservés peuvent être consultés au point d'extrémité suivant :

GET /api/33/validationResults

Vous pouvez également inspecter un résultat individuel à l'aide de l'identifiant du résultat de validation dans ce endpoint :

GET /api/33/validationResults/<id>

Les résultats de validation peuvent également être filtrés par les propriétés suivantes :

• Unité d'organisation : ou=<UID>
• Règle de validation : vr=<UID>
• Période : pe=<ISO-expression>

Chacune des propriétés de filtre ci-dessus peut apparaître plusieurs fois, par exemple :

GET /api/36/validationResults?ou=jNb63DIHuwU&ou=RzgSFJ9E46G

Si plusieurs valeurs pour le même filtre sont combinées avec OR, les résultats devront correspondre à l'une des valeurs données.

Si plusieurs propriétés de filtre sont utilisées et qu'elles sont combinées avec AND, les résultats devront correspondre à l'une des valeurs de chacune des propriétés.

Pour le filtre de période, les résultats doivent se superposer à l'une des périodes spécifiées.

De plus, les résultats de validation peuvent également être filtrés en fonction de leur date de création :

GET /api/36/validationResults?createdDate=<date>

Ce filtre peut être combiné avec n’importe quel autre filtre.

Déclencher des notifications de résultats de validation¶

Les résultats de la validation sont envoyés aux utilisateurs concernés une fois par jour. Ils peuvent également être déclenchés manuellement pour être exécutés sur demande, via le point d'extrémité de l'API suivant :

POST /api/33/validation/sendNotifications

Seuls les résultats non envoyés sont envoyés via ce endpoint.

Supprimer les résultats de validation¶

Les résultats de validation peuvent être supprimés manuellement en utilisant l'ID,

DELETE /api/36/validationResults/<id>

ou les filtres

DELETE /api/36/validationResults?<filters>

Les paramètres de filtre pris en charge sont :

• ou=<UID> pour faire correspondre tous les résultats de validation d'une unité d'organisation. Plusieurs unités utilisent 'OU' lorsque le paramètre est fourni plus d'une fois
• vr=<UID> pour faire correspondre tous les résultats de validation d'une règle de validation. Plusieurs règles utilisent 'OU' lorsque le paramètre est fourni plus d'une fois
• pe=<ISO-expression> pour faire correspondre tous les résultats de validation liés à une période qui se superpose à la période spécifiée
• created=<ISO-expression> pour faire correspondre tous les résultats de validation créés au cours de la période fournie
• notificationSent=<boolean> pour faire correspondre uniquement les résultats de validation pour lesquels une notification a été ou n'a pas été envoyée

If filters are combined, all conditions have to be true (AND logic).

Quelques exemples:

Pour supprimer tous les résultats de validation liés à l'unité d'organisation avec l'UID NqwvaQC1ni4 pour le premier trimestre (Q1) 2020, utilisez :

DELETE /api/36/validationResults?ou=NqwvaQC1ni4&pe=2020Q1

Pour supprimer tous les résultats de validation créés au cours de la semaine 1 de 2019 et pour lesquels une notification a été envoyée, utilisez :

DELETE /api/36/validationResults?created=2019W1&notificationSent=true

Toute opération de suppression nécessitera l'autorité Effectuer des tâches de maintenance.

Détection des valeurs atypiques¶

Le point d'extrémité de détection des valeurs atypiques permet de détecter les valeurs atypiques parmi les valeurs de données agrégées.

GET /api/36/outlierDetection

Ce endpoint prend en charge deux algorithmes pour détecter les valeurs atypiques :

• Z-score : Le z-score est défini comme l'écart absolu entre le score et la moyenne divisé par l'écart type. Un paramètre de seuil faisant référence au nombre d'écarts types par rapport à la moyenne doit être spécifié avec l'algorithme z-score pour définir les limites supérieure et inférieure de ce qui est considéré comme une valeur atypique.
• Z-score modifié : Identique au z-score, à la différence qu'il utilise la médiane au lieu de la moyenne comme mesure de la tendance centrale. Les paramètres sont les mêmes que pour le Z-score.
• Min-max: Min-max data element values refers to custom boundaries which can be inserted in DHIS2 based on data element, org unit and category option combination.

Les valeurs atypiques seront classées selon leur importance, par défaut selon l'écart absolu par rapport à la moyenne, avec la valeur la plus importante en premier. Ceci permet d'identifier rapidement les valeurs atypiques qui ont le plus grand impact sur la qualité et l’analyse des données.

Paramètres de requête{ #request-query-parameters }¶

Les paramètres de requête suivants sont pris en charge.

[*] Vous devez spécifier soit des ensembles de données avec le paramètre ds, qui intégrera tous les éléments de données dans les ensembles de données, ou spécifier des éléments de données avec le paramètre de.

Au moins un ensemble de données ou élément de données, une date de début et une date de fin, et au moins une unité d'organisation doivent être définis.

Les paramètres startDate et endDate sont obligatoires et font référence à l'intervalle de temps dans lequel vous voulez détecter les valeurs atypiques. Les paramètres dataStartDate et dataEndDate sont facultatifs et font référence à l'intervalle de temps à utiliser pour les données lors du calcul de la moyenne et de l'écart type. Ils sont utilisés pour calculer éventuellement le z-score.

Utilisation et exemples¶

Obtenez les valeurs atypiques à l'aide de l'algorithme z-score par défaut :

GET /api/36/outlierDetection?ds=BfMAe6Itzgt&ds=QX4ZTUbOt3a
  &ou=O6uvpzGd5pu&ou=fdc6uOvgoji&startDate=2020-01-01&endDate=2020-12-31

Pour obtenir des valeurs atypiques à l'aide d'un algorithme et d'un seuil spécifiques :

GET /api/36/outlierDetection?ds=BfMAe6Itzgt&ds=QX4ZTUbOt3a
  &ou=O6uvpzGd5pu&startDate=2020-01-01&endDate=2020-12-31
  &algorithm=Z_SCORE&threshold=2.5

Pour obtenir les valeurs atypiques classées par z-score :

GET /api/36/outlierDetection?ds=BfMAe6Itzgt
  &ou=O6uvpzGd5pu&startDate=2020-01-01&endDate=2020-12-31
  &orderBy=Z_SCORE

Pour obtenir les 10 principales valeurs atypiques :

GET /api/36/outlierDetection?ds=BfMAe6Itzgt
  &ou=O6uvpzGd5pu&startDate=2020-01-01&endDate=2020-12-31
  &maxResults=10

Obtenez des valeurs atypiques avec un intervalle défini pour les données à utiliser lors du calcul de la moyenne et de l'écart type :

GET /api/36/outlierDetection?ds=BfMAe6Itzgt
  &ou=O6uvpzGd5pu&startDate=2020-01-01&endDate=2020-12-31
  &dataStartDate=2018-01-01&dataEndDate=2020-12-31

Pour obtenir les valeurs atypiques à l'aide de l'algorithme min-max :

GET /api/36/outlierDetection?ds=BfMAe6Itzgt&ds=QX4ZTUbOt3a
  &ou=O6uvpzGd5pu&ou=fdc6uOvgoji&startDate=2020-01-01&endDate=2020-12-31
  &algorithm=MIN_MAX

Format de réponse¶

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

La réponse contient les champs suivants :

Les champs mean, stdDev et z-score ne sont présents que lorsque algorithm est Z_SCORE.

La réponse ressemblera à ceci. La section metadata contient des métadonnées de requête et de réponse. La section outlierValues contient les valeurs atypiques.

{
  "metadata": {
    "algorithm": "Z_SCORE",
    "threshold": 2.5,
    "orderBy": "MEAN_ABS_DEV",
    "maxResults": 10,
    "count": 10
  },
  "outlierValues": [
    {
      "de": "rbkr8PL0rwM",
      "deName": "Iron Folate given at ANC 3rd",
      "pe": "202011",
      "ou": "Pae8DR7VmcL",
      "ouName": "MCH (Kakua) Static",
      "coc": "pq2XI5kz2BY",
      "cocName": "Fixed",
      "aoc": "HllvX50cXC0",
      "aocName": "default",
      "value": 9000.0,
      "mean": 1524.5555,
      "stdDev": 2654.4661,
      "absDev": 7475.4444,
      "zScore": 2.8161,
      "lowerBound": -5111.6097,
      "upperBound": 8160.7208,
      "followUp": false
    },
    {
      "de": "rbkr8PL0rwM",
      "deName": "Iron Folate given at ANC 3rd",
      "pe": "202010",
      "ou": "vELbGdEphPd",
      "ouName": "Jimmi CHC",
      "coc": "pq2XI5kz2BY",
      "cocName": "Fixed",
      "aoc": "HllvX50cXC0",
      "aocName": "default",
      "value": 8764.0,
      "mean": 1448.0833,
      "stdDev": 2502.3031,
      "absDev": 7315.9166,
      "zScore": 2.9236,
      "lowerBound": -4807.6745,
      "upperBound": 7703.8412,
      "followUp": false
    }
  ]
}

Contraintes et validation¶

Les contraintes suivantes s'appliquent lors de la validation de la requête. Chaque erreur de validation a un code d'erreur correspondant.

Analyse des données¶

Plusieurs ressources permettant d'effectuer des analyses de données et de détecter les problèmes de qualité et de validation des données sont fournies.

Remarque : Ce endpoint est obsolète et sera supprimé dans la version 2.38. Utilisez plutôt le endpoint outlierAnalysis.

Analyse des règles de validation¶

Pour exécuter des règles de validation et extraire les violations :

GET /api/dataAnalysis/validationRules

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

Tableau : Paramètres de requête d'analyse des règles de validation

| Paramètre de requête | Description | Option | Obligatoire | Par défaut | |---|---|---|---| | vrg | Groupe de règles de validation | Identifiant | false | If omitted, all validation rule groups will be used | | ou | Unité d’organisation | Identifiant |true | | | startDate | Start date for the time span | Date (aaaa-MM-jj) | false | Aujourd'hui | | endDate | End date for the time span | Date (aaaa-MM-jj) | false | Aujourd'hui | | conserver | S'il faut conserver les violations dans le système | false | true | false | false | | notification | S'il faut envoyer des notifications sur les violations | false | true | false | false | | maxResults | Max limit for the output | Integer, greater than zero. Maximum as specified by system setting keyDataQualityMaxLimit| false | 500 |

Sample POST body request:

{
    "startDate":"2024-01-01",
    "endDate":"2025-04-10",
    "ou":"ImspTQPwCqd",
    "notification":false,
    "persist":false,
    "vrg":"UP1lctvalPn",
    "maxResults": 500
}

Sample output:
```json
[{
    "validationRuleId": "kgh54Xb9LSE",
    "validationRuleDescription": "Malaria outbreak",
    "organisationUnitId": "DiszpKrYNg8",
    "organisationUnitDisplayName": "Ngelehun CHC",
    "organisationUnitPath": "/ImspTQPwCqd/O6uvpzGd5pu/YuQRtpLP10I/DiszpKrYNg8",
    "organisationUnitAncestorNames": "Sierra Leone / Bo / Badjia / ",
    "periodId": "201901",
    "periodDisplayName": "January 2019",
    "attributeOptionComboId": "HllvX50cXC0",
    "attributeOptionComboDisplayName": "default",
    "importance": "MEDIUM",
    "leftSideValue": 10.0,
    "operator": ">",
    "rightSideValue": 14.0
}, {
    "validationRuleId": "ZoG4yXZi3c3",
    "validationRuleDescription": "ANC 2 cannot be higher than ANC 1",
    "organisationUnitId": "DiszpKrYNg8",
    "organisationUnitDisplayName": "Ngelehun CHC",
    "organisationUnitPath": "/ImspTQPwCqd/O6uvpzGd5pu/YuQRtpLP10I/DiszpKrYNg8",
    "organisationUnitAncestorNames": "Sierra Leone / Bo / Badjia / ",
    "periodId": "201901",
    "periodDisplayName": "January 2019",
    "attributeOptionComboId": "HllvX50cXC0",
    "attributeOptionComboDisplayName": "default",
    "importance": "MEDIUM",
    "leftSideValue": 22.0,
    "operator": "<=",
    "rightSideValue": 19.0
}]

Analyse des valeurs atypiques sur la base de l'écart type¶

Pour identifier les valeurs atypiques parmi les données en fonction des écarts types de la valeur moyenne :

GET /api/dataAnalysis/stdDevOutlier

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

Tableau : Paramètres de requête d'analyse des valeurs atypiques de l'écart type

Analyse des valeurs atypique sur la base des valeurs minimales/maximales¶

Pour identifier les valeurs atypiques sur la base des valeurs minimales et maximales :

GET /api/dataAnalysis/minMaxOutlier

Les paramètres de requête pris en charge équivalent à la ressource analyse des valeurs atypiques en fonction de l'écart type décrite ci-dessus.

Follow-up data analysis¶

Pour identifier les données marquées pour le suivi :

GET /api/dataAnalysis/followup

Au moins un ensemble de données ou élément de données, une date ou période de début et de fin, et au moins une unité d'organisation doivent être définis.

Les paramètres de requête suivants sont pris en charge.

[*] Vous devez spécifier soit des ensembles de données avec le paramètre ds, qui intégrera tous les éléments de données dans les ensembles de données, ou spécifier des éléments de données avec le paramètre de. De même, Date de début et date de fin ou période doivent être spécifiés.

Les paramètres Date de début et Date de fin font référence à l'intervalle de temps au cours duquel vous voulez détecter les valeurs atypiques. Si une période pe est fournie à la place, le début et la fin de l'intervalle sont également ceux de la période.

Si aucune combinaison d'options coc n'est fournie, tous les éléments de données de type valeur numérique seront pris en compte.

Intégrité des données¶

Les fonctionnalités d'intégrité des données du module d'administration des données sont disponibles via l'API web. Cette section décrit comment exécuter le processus d'intégrité des données et récupérer les résultats. Les informations spécifiques concernant chaque contrôle sont décrites dans le manuel de l'utilisateur.

Liste des contrôles d'intégrité des données disponibles¶

Une description des contrôles disponibles est renvoyée après qu'une requête soit envoyé à :

GET /api/dataIntegrity

[
    {
        "name": "data_elements_without_groups",
        "displayName": "Data elements lacking groups",
        "section": "Data Elements",
        "severity": "WARNING",
        "description": "Lists all data elements that have no data element groups",
        "issuesIdType": "dataElements",
        "isSlow": false
    }
]

L'élément name (nom) parmi les éléments de contrôle renvoyés est l'identifiant utilisé par le paramètre contrôles pour déclarer les contrôles à exécuter.

Remarque

Chaque contrôle indiquera si la saisie dans le champ isSlow (est lent) peut nécessiter beaucoup de temps et de ressources. Les utilisateurs doivent être prudents lorsqu'ils exécutent ces contrôles sur les systèmes de production car cela pourrait entraîner une baisse de performance du système. Ces contrôles peuvent être exécutés individuellement, mais seulement sur requête expresse.

Les contrôles sont regroupés sémantiquement par l'élément section et classés dans l'un des quatre niveaux de sévérité :

Les contrôles disponibles peuvent être filtrés à l'aide du paramètre contrôles.

GET /api/dataIntegrity?checks=<pattern1>,<pattern2>

Un ou plusieurs noms ou modèles exacts utilisant * comme caractère générique peuvent être fournis.

Des résultats supplémentaires peuvent être filtrés à l'aide d'un paramètre section.

GET /api/dataIntegrity?section=Categories

Le filtre section renverra toutes les correspondances exactes qui ont la section spécifiée.

Furthermore, to filter (select) only checks marked as isSlow use slow=true,

GET /api/dataIntegrity?slow=true

or to filter (select) only checks that are not performed via database query (programmed checks) use programmatic=true:

GET /api/dataIntegrity?programmatic=true

The slow, programmatic and section filters can be combined in which case all conditions must be met.

Production de résumés sur l'intégrité des données¶

Depuis la version 2.38, les contrôles d'intégrité des données ont deux niveaux de spécificité :

• un niveau résumé qui donne un aperçu du nombre de problèmes
• un niveau détails qui fournit une liste de problèmes indiquant des violations individuelles de l'intégrité des données.

Pour lancer une analyse qui résume les contrôles exécutés :

POST /api/dataIntegrity/summary?checks=<name1>,<name2>

Cela déclenche l'exécution du ou des contrôle(s) de manière asynchrone. Les résultats des contrôles individuels seront renvoyés dans le cache de l'application dès que le contrôle sera terminé.

Alternativement, la liste des contrôles peut également être fournie comme le CORPS de la requête POST. Cela peut être utile si la liste devient trop longue pour être utilisée dans l'URL.

Pour récupérer le résumé sur l'intégrité des données du ou des contrôle(s) déclenchés, utilisez :

GET /api/dataIntegrity/summary?checks=<name1>,<name2>

Lorsque le paramètre contrôles est omis, tous les contrôles seront récupérées depuis le cache du serveur.

La réponse est une "carte" des résultats de contrôle, un pour chaque contrôle déjà terminé. Ces informations sont mises en cache pendant une heure ou jusqu'à ce que le contrôle soit exécuté à nouveau.

Pour attendre que le résumé soit disponible dans le cache, un timeout (délai d'attente) en millisecondes peut être ajouté :

GET /api/dataIntegrity/summary?checks=<name1>,<name2>&timeout=500

Une réponse de résumé pourrait ressembler à ceci :

{
  "<name1>": {
    "name": "<name1>",
    "displayName": "<displayName1>",
    "startTime": "2023-01-11T06:12:56.436",
    "finishedTime": "2023-01-11T06:12:57.021",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "count": 12,
    "percentage": 2.3
  },
  "<name2>": {
    "name": "<name2>",
    "displayName": "<displayName2>",
    "startTime": "2023-01-11T06:12:57.345",
    "finishedTime": "2023-01-11T06:12:58.007",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "count": 4,
    "percentage": 5.1
  }
}

Chaque réponse de résumé contient le nom, la section, la sévérité, la description et éventuellement une introduction et une recommandation. Chaque résumé contient le nombre de problèmes trouvés dans le champ nombre. Si possible, un champ optionnel pourcentage fournit le pourcentage d'objets présentant des problèmes d'intégrité des données par rapport à l'ensemble des objets du même type. Le champ Heure de début indique le moment où le contrôle a été initié. Le champ Heure de fin permet de calculer la durée nécessaire à l'exécution du contrôle.

Si une analyse de contrôle échoue en raison d'une erreur de programmation ou d'une incohérence imprévue des données, le résumé et les détails comporteront un champ erreur qui décrit l'erreur qui s'est produite. Le nombre de contrôles qui ont échoué sera fixé à -1. Aucun pourcentage ne sera renvoyé dans ce cas.

{
  "<name1>": {
    "name": "<name1>",
    "displayName": "<displayName1>",
    "finishedTime": "2022-02-15 14:55",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "error": "what has happened",
    "issues": []
  }
}

Remarque

Chaque contrôle de métadonnée est exécuté de manière asynchrone sur le serveur. Les résultats seront restitués dès que chaque contrôle sera terminé. Le moyen le plus sûr de vous assurer que vous avez récupéré le dernier ensemble de résultats demandé est de comparer l'horodatage de la requête avec finishedTime (heure de fin) dans la réponse.

Pour obtenir une liste des noms des contrôles actuellement effectués par l'utilisation du serveur :

GET /api/dataIntegrity/summary/running

Pour obtenir une liste des noms des contrôles pour lesquels les résultats sont disponibles, utilisez :

GET /api/dataIntegrity/summary/completed

Retrieving completed checks as Prometheus metrics¶

Metadata integrity checks which are present in the cache, can be retrieved in the Prometheus metrics format by making a request to : GET /api/dataIntegrity/metrics

The response should return a plain text format in the Prometheus plain text exposition format. Several metrics are available for each data integrity check. - Count: A count of the number of issues identified by the metadata check. - Percentage: When available, provides a percentage of the objects which have been identified by the check relative to a baseline. For instance, if check "Organisation units with trailing spaces" has a percent of 2.13, the percentage is calculated by dividing the number of organisation units with trailing spaces by the total number of organisation units. Note that this percentage may not be available for all metadata integrity checks. - Duration: Number of milliseconds that the check took to execute the last time it was run.

An example of the output of this endpoint is provided below:

# HELP dhis_data_integrity_check_count Data integrity check counts { #help-dhis_data_integrity_check_count-data-integrity-check-counts } 
# TYPE dhis_data_integrity_check_count gauge { #type-dhis_data_integrity_check_count-gauge } 
dhis_data_integrity_check_count{check="orgunits_invalid_geometry"} 1
dhis_data_integrity_check_count{check="user_groups_scarce"} 0
dhis_data_integrity_check_count{check="indicator_no_analysis"} 13
# HELP dhis_data_integrity_check_percentage Data integrity check percentages { #help-dhis_data_integrity_check_percentage-data-integrity-check-percentages } 
# TYPE dhis_data_integrity_check_percentage gauge { #type-dhis_data_integrity_check_percentage-gauge } 
dhis_data_integrity_check_percentage{check="orgunits_invalid_geometry"} 0.13054830287206268
dhis_data_integrity_check_percentage{check="user_groups_scarce"} 0.0
dhis_data_integrity_check_percentage{check="indicator_no_analysis"} 16.0
# HELP dhis_data_integrity_check_duration Data integrity check durations { #help-dhis_data_integrity_check_duration-data-integrity-check-durations } 
# TYPE dhis_data_integrity_check_duration gauge { #type-dhis_data_integrity_check_duration-gauge } 
dhis_data_integrity_check_duration{check="orgunits_invalid_geometry"} 11
dhis_data_integrity_check_duration{check="user_groups_scarce"} 1
dhis_data_integrity_check_duration{check="indicator_no_analysis"} 0

Data integrity checks which are not currently in the cache will not be returned by this endpoint. A request would need to be made to the /summary endpoint to trigger the checks to be run or alternatively through a scheduled job.

Production de détails sur l'intégrité des données¶

Pour lancer une sélection de contrôles de détails, déclenchez-les d'abord à l'aide d'une requête POST :

POST /api/dataIntegrity/details?checks=<name1>,<name2>

Tout comme avec le résumé, la liste des contrôles peut également être fournie en tant que corps de la requête POST.

Récupérez ensuite les résultats du cache en utilisant :

GET /api/dataIntegrity/details?checks=<name1>,<name2>&timeout=500

Lorsque le paramètre contrôles n'est pas fourni, tous les contrôles qui n'ont pas été marqués isSlow (est lent) seront programmés pour être exécutés sur le serveur.

Si vous omettez l'élément timeout (délai d'attente), la requête n'attendra que les résultats soient trouvés dans le cache, au contraire vous ne recevrez pas le résultat du contrôle demandé.

La réponse /détails renvoie une carte similaire à celle du résumé, mais ne contient pas de nombre ou de pourcentage. En lieu et place, une liste de problèmes est renvoyée.

{
  "<name1>": {
    "name": "<name1>",
    "displayName": "<displayName1>",
    "startTime": "2023-01-11T06:12:56.436",
    "finishedTime": "2023-01-11T06:12:57.021",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "issuesIdType": "<object-type-plural>",
    "isSlow": false,
    "issues": [{
      "id": "<id-or-other-identifier>",
      "name": "<name-of-the-id-obj>",
      "comment": "optional plain text description or hint of the issue",
      "refs": ["<id1>", "<id2>"]
    }]
  },
  "<name2>": {
    "name": "<name2>",
    "displayName": "<displayName2>",
    "startTime": "2023-01-11T06:12:57.345",
    "finishedTime": "2023-01-11T06:12:58.007",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "issuesIdType": "<object-type-plural>",
    "isSlow": false,
    "issues": []
  }
}

Les champs commentaire et références sont optionnels pour chaque problème. Un commentaire peut donner plus de précisions sur le contexte ou la raison pour laquelle ce problème est considéré comme un problème d'intégrité des données. La liste références peut également fournir les identifiants d'autres objets qui ont contribué à la violation. Le champ Heure de fin indique le moment où le contrôle a fini d'être traité sur le serveur. Le cache stocke le résultat de chaque contrôle terminé pendant une heure.

Tip

Un ensemble de contrôles peut également être spécifié à l'aide de wild-cards (caractères génériques). Pour inclure tous les contrôles avec élément dans le nom, utilisez contrôles=*élément*. Tout comme avec les noms complets, ces motifs peuvent être utilisés dans une liste de caractères séparés par des virgules et être combinés avec les noms complets. Les doublons seront éliminés. Un contrôle peut également être spécifié par son code. Un code est constitué des premières lettres de chaque mot du nom en majuscules. Par exemple, orgunits_invalid_geometry a le code OIG.

Tout comme avec le résumé, il est possible d'obtenir les noms des contrôles de détails en cours d'exécution et de ceux déjà effectués avec la requête suivante :

GET /api/dataIntegrity/details/running
GET /api/dataIntegrity/details/completed

Custom Data Integrity Checks¶

Users of DHIS2 can now create and supply their own Data Integrity Checks. This can be useful if users want to avail of this functionality and extend upon the supplied set of core data integrity checks.

Tip

Users are also encouraged to share their custom checks with others by opening a pull request in the dhis2-core repository containing their .yaml file(s). Please select platform-backend as reviewer to put the PR on our radar early on. The team will take care of checking and linking the check correctly, so it becomes part of the provided suite of checks with the next release.

An example of a custom check could be for determining if certain users are members of specific user groups. This type of check would be very specific to an implementation, and not generally applicable across all installs. These types of metadata checks can be used to extend the default checks which are included with DHIS2.

Custom checks can be implemented by satisfying the following requirements, each of which we will go into detail: - Supplying your own list of custom data integrity checks in a list file named custom-data-integrity-checks.yaml in your DHIS2_HOME directory - Having a directory named custom-data-integrity-checks in your DHIS2_HOME directory - Supplying your valid custom data integrity check yaml files

Custom Data Integrity Check List File¶

DHIS2 will only try to load data integrity files when they are needed. e.g. when making a call to view all data integrity checks:

GET /api/dataIntegrity

DHIS2 will look for a file named custom-data-integrity-checks.yaml in your DHIS2_HOME directory when loading data integrity files. If you are not using custom checks and the file is not present, a warning log like this will be present:

08:29:57.729  WARN o.h.d.d.DataIntegrityYamlReader: Failed to load data integrity check from YAML. Error message `{DHIS2_HOME}/custom-data-integrity-checks.yaml (No such file or directory)

If you are implementing custom data integrity checks then this file must be present. To see what the core data integrity checks file looks like as an example, check out this file.

The custom-data-integrity-checks.yaml file should list all of your custom data integrity checks. As an example, it could look something like this:

checks:
  - categories/my_custom_check.yaml
  - users/my_user_group_check.yaml
  - base_check.yaml

Check names in this file can be preceded with a directory name for logical grouping. From the 3 example checks listed above, the directory structure should look like this:

├── DHIS2_HOME
│   ├── dhis.conf
│   ├── custom-data-integrity-checks.yaml
│   ├── custom-data-integrity-checks
│   │   ├── categories
│   │   │   ├── my_custom_check.yaml
│   │   ├── users
│   │   │   ├── my_user_group_check.yaml
│   │   ├── base_check.yaml

Name and Code constraints¶

Each data integrity check name and code must be unique. If there are any clashes then the violating custom check will not be loaded.

Note

System data integrity checks are always loaded first. Any name or code clashes resulting from custom checks will not affect these core system checks.

An example data integrity check yaml file is located here for reference. Note the name property.

The data integrity code is calculated dynamically by using the first letter of each word in the name. Some examples:

If there is a name clash, a warning log like this will be present:

09:48:43.138  WARN o.h.d.d.DefaultDataIntegrityService: Data Integrity Check `my_custom_check` not added as a check with that name already exists

If there is a code clash, a warning log like this will be present:

09:48:43.138  WARN o.h.d.d.DefaultDataIntegrityService: Data Integrity Check `my_custom_check` not added as a check with the code `MCC` already exists

Data Integrity Check Schema¶

A data integrity check file must comply with this JSON schema. If a check does not comply with the schema then a warning like this will be present:

09:48:43.136  WARN o.h.d.d.DataIntegrityYamlReader: JsonSchema validation errors found for Data Integrity Check `categories/my_custom_check.yaml`. Errors: [$.name: is missing but it is required]

Any schema violations must be fixed before that check can be loaded and used.

If a data integrity check file contains invalid yaml then a warning log like this could be present:

10:30:37.858  WARN o.h.d.d.DataIntegrityYamlReader: JsonSchema validation errors found for Data Integrity Check `my_custom_check.yaml`. Errors: [$: string found, object expected]

To view and use the custom checks please refer to the main Data Integrity section

Note

It is recommended to follow any naming and format conventions seen in the provided examples above when implementing your own custom checks to help avoid any issues

Data Integrity File¶

Details of the data integrity check yaml file, taken from the JSON schema file

Example custom data integrity check¶

An example of a custom check could be for determining if users have an email. Emails are useful to be able to communicate with users and sent them notifications, as well as password recovery. So, in some instllations of DHIS2, it could be a policy that all users should have emails. An example of this type of custom check is shown below.

---
name: users_should_have_emails
description: Users should have emails.
section: Users
section_order: 6
summary_sql: >-
  WITH users_no_email as (
  SELECT uid,username from
  userinfo where email IS NULL)
  SELECT COUNT(*) as value,
  100*COUNT(*) / NULLIF( ( select COUNT(*) from userinfo), 0) as percent
  from users_no_email;
details_sql: >-
  WITH users_no_email as (
  SELECT uid,username from
  userinfo where email IS NULL)
  SELECT uid,username as from users_no_email;
severity: WARNING
introduction: >
  Users should have defined emails. This is important for password recovery and to be able
  to send notifications to users.
recommendation: >
  Make sure that all users have defined emails.
details_id_type: users

More examples of different types of metadata integrity checks can be found in the DHIS2 source code here.

Complete data set registrations¶

Cette section traite de l'enregistrement d'ensembles de données complétés en tant qu'ensembles de données. Un enregistrement marque un ensemble de données comme étant complètement capturé.

Completing data sets¶

Cette section explique comment enregistrer des ensembles de données comme étant complets. Cela s'obtient en interagissant avec la ressource completeDataSetRegistrations (Enregistrements d'ensembles de données complets):

GET /api/33/completeDataSetRegistrations

Le point d'extrémité utilise la méthode POST pour enregistrer les ensembles de données complets. De façon pratique, ce point d'extrémité est très similaire à celui de dataValueSets (ensembles de valeurs de données), avec la possibilité d'importer des enregistrements complets en bloc.

L'importation de charges utiles au format XML et JSON est prise en charge. Le format de base de cette charge utile, donné en XML dans cet exemple, ressemble à ceci :

<completeDataSetRegistrations xmlns="http://dhis2.org/schema/dxf/2.0">
  <completeDataSetRegistration period="200810" dataSet="eZDhcZi6FLP"
    organisationUnit="qhqAxPSTUXp" attributeOptionCombo="bRowv6yZOF2" storedBy="imported"/>
  <completeDataSetRegistration period="200811" dataSet="eZDhcZi6FLP"
    organisationUnit="qhqAxPSTUXp" attributeOptionCombo="bRowv6yZOF2" storedBy="imported"/>
</completeDataSetRegistrations>

L'attribut storedBy (stocké par) est facultatif (car il peut être retiré de l'objet d'enregistrement complet). Vous pouvez également définir la propriété date (heure de l'enregistrement) en tant qu'attribut. Si l'heure n'est pas définie, l'heure actuelle sera utilisée.

Le processus d'importation prend en charge les paramètres de requête suivants :

Tableau : Paramètres de requête d'enregistrement d'ensembles de données complets

Les éléments idScheme (schéma de l'identifiant), dataSetIdScheme (schéma de l'identifiant de l'ensemble de données), orgUnitIdScheme (schéma de l'identifiant de l'unité d'organisation), attributeOptionComboIdScheme (schéma de l'identifiant de la combinaison d'options d'attribut), dryRun (essai) et strategy (stratégie) (notez la dénomination différente du paramètre importStrategy (stratégie d'importation)) peuvent également être définis dans le cadre de la charge utile. Avec XML, ce sont des attributs ; avec JSON, ce sont des éléments du nœud completeDataSetRegistrations (enregistrements des ensembles de données complets).

Par exemple :

<completeDataSetRegistrations xmlns="http://dhis2.org/schema/dxf/2.0"
      orgUnitIdScheme="CODE">
    <completeDataSetRegistration period="200810" dataSet="eZDhcZi6FLP"
    organisationUnit="OU_559" attributeOptionCombo="bRowv6yZOF2" storedBy="imported"/>
</completeDataSetRegistrations>

Si le paramètre URL et la charge utile définissent un schéma, la charge utile est prioritaire.

Lecture des enregistrements d'ensembles de données terminés¶

Cette section explique comment récupérer les enregistrements d'ensembles de données terminés. Nous utiliserons la ressource completeDataSetRegistrations. Les paramètres de requête à utiliser sont les suivants :

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

Les paramètres période, date de début, date de fin, créé et durée de création fournissent plusieurs façons de définir la dimension temporelle de la requête, donc un seul peut être utilisé. Par exemple, cela n'a pas de sens de définir à la fois la date de début/fin et les périodes.

Voici donc un exemple de requête :

GET /api/33/completeDataSetRegistrations?dataSet=pBOMPrpg1QX
  &startDate=2014-01-01&endDate=2014-01-31&orgUnit=YuQRtpLP10I
  &orgUnit=vWbkYPRmKyS&children=true

Vous pouvez obtenir la réponse au format xml et json. Vous pouvez indiquer le format de réponse que vous préférez via l'en-tête HTTP Accepter comme dans l'exemple ci-dessus. Pour xml, utilisez application/xml ; pour json, utilisez application/json.

Annuler la finalisation des ensembles de données¶

Cette section explique comment annuler l'enregistrement de la complétude d'un ensemble de données. Pour annuler la finalisation d'un ensemble de données, vous interagirez avec la ressource completeDataSetRegistrations :

GET /api/33/completeDataSetRegistrations

Cette ressource prend en charge la fonction DELETE pour annuler l'inscription. Les paramètres de requête suivants sont pris en charge :

Tableau : Paramètres de requête d'enregistrement d'ensembles de données complets