Échange de données¶

Échange de données agrégées¶

Cette section décrit le service d'échange de données agrégées et l'API.

Introduction¶

Le service d'échange de données agrégées permet d'échanger des données entre des instances de DHIS 2, et éventuellement d'autres logiciels qui prennent en charge le format JSON de l'ensemble des valeurs de données de DHIS 2. Il permet également l'échange de données au sein d'une seule instance de DHIS 2, par exemple pour l'agrégation de données de suivi et l'enregistrement du résultat en tant que données agrégées.

Le service d'échange de données agrégées est adapté à des cas d'utilisation tels que :

• L'échange de données entre une instance HMIS et un portail de données ou une instance d'entrepôt de données de DHIS 2.
• L'échange de données entre une instance de suivi DHIS 2 contenant des données individuelles et une instance HMIS agrégée.
• Le calcul préalable des données de suivi avec les indicateurs de programme sauvegardés en tant que valeurs de données agrégées.
• La déclaration des données d'un HMIS national à un bailleur de fonds mondial.

Présentation¶

Le service d'échange de données agrégées permet l'échange de données entre une instance source du DHIS 2 et une instance cible du DHIS 2. Un échange de données peut être externe, c'est-à-dire que l'instance cible est différente/externe à l'instance source. Un échange de données peut également être interne, l'instance cible étant la même que l'instance source. La source d'échange de données agrégées peut contenir plusieurs requêtes de source, une requête de source correspondant à peu près à une requête d'API analytique.

La valeur des données sera récupérée et transformée dans le format ensemble de valeurs de données, puis transmise à l'instance cible de DHIS 2. Le service d'échange de données agrégées prend en charge les systèmes d'identification pour permettre une certaine souplesse dans le mapping des métadonnées entre les instances.

Les données seront récupérées et agrégées à partir de l'instance source à l'aide du moteur d'analyse. Cela implique que les éléments de données, les indicateurs agrégés, les taux de déclaration des ensembles de données et les indicateurs de programme peuvent être référencés dans la requête adressée à l'instance source. Une demande de source contient également des périodes, où les périodes fixes et relatives sont prises en charge, et des unités d'organisation. Un nombre quelconque de filtres peut être appliqué à une requête source.

Un échange de données peut être exécuté en tant que tâche planifiée, c'est-à-dire que l'échange de données peut être programmé pour être exécuté à un intervalle spécifique. Un échange de données peut également être exécuté sur demande via l'API.

Pour créer et manipuler des échanges de données agrégées, les autorités F_AGGREGATE_DATA_EXCHANGE_PUBLIC_ADD / F_AGGREGATE_DATA_EXCHANGE_PRIVATE_ADD et F_AGGREGATE_DATA_EXCHANGE_DELETE sont nécessaires.

Les définitions d'échange de données agrégées sont des métadonnées normales dans DHIS 2, ce qui signifie que les définitions peuvent être importées et exportées entre les instances de DHIS 2, à l'exception des informations d'identification (noms d'utilisateur et jetons d'accès) qui ne seront pas exposées dans les exportations de métadonnées. Les informations d'identification sont cryptées lors du stockage afin de fournir une couche de sécurité supplémentaire.

Le service d'échange de données agrégées a été introduit dans la version 2.39, ce qui signifie que l'instance source de DHIS 2 doit être la version 2.39 ou ultérieure. L'instance cible du DHIS 2 doit être la version 2.38 ou ultérieure.

Authentification¶

Pour les échanges de données de type externe, l'URL de base et les informations d'authentification de l'instance DHIS 2 cible doivent être spécifiées. Pour l'authentification, l'authentification de base et les jetons d'accès personnels (PAT) sont pris en charge.

Il est recommandé de spécifier soit l'authentification de base, soit l'authentification PAT. Si les deux sont spécifiées, l'authentification PAT est prioritaire.

Notez que la prise en charge de PAT a été introduite dans la version 2.38.1, ce qui signifie que pour utiliser l'authentification PAT, l'instance DHIS 2 cible doit être la version 2.38.1 ou une version ultérieure.

Partage¶

Like other metadata objects, fine-grained security can be associated with aggregate data exchanges. Each exchange can be shared with individual users and/or user groups to control which users have access to the specific exchange. External data exchanges contain authentication details of users on the target system, thus great care should be taken to ensure that only authorized users have access to actually submit data which results from the exchange.

The following table summarizes how sharing can be used with aggregate data exchanges.

API¶

L'API d'échange de données agrégées est abordée dans la section qui suit.

Créer un échange de données agrégées¶

POST /api/aggregateDataExchanges

Type de contenu : application/json

Exemple de charge utile d'échange de données internes, où les données d'événement sont calculées avec les indicateurs de programme et sauvegardées en tant que valeurs de données agrégées :

{
  "name": "Internal data exchange",
  "source": {
    "params": {
      "periodTypes": [
        "MONTHLY",
        "QUARTERLY"
      ]
    },
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "filters": [
          {
            "dimension": "Bpx0589u8y0",
            "items": [
              "oRVt7g429ZO",
              "MAs88nJc9nL"
            ]
          }
        ],
        "inputIdScheme": "UID",
        "outputDataElementIdScheme": "UID",
        "outputOrgUnitIdScheme": "UID",
        "outputIdScheme": "UID"
      }
    ]
  },
  "target": {
    "type": "INTERNAL",
    "request": {
      "dataElementIdScheme": "UID",
      "orgUnitIdScheme": "UID",
      "categoryOptionComboIdScheme": "UID",
      "idScheme": "UID"
    }
  }
}

Exemple de charge utile d'échange de données externes avec authentification de base et schéma d'identification code, où les données sont transmises à une instance DHIS 2 externe :

{
  "name": "External data exchange with basic authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

Exemple de charge utile d'échange de données externes avec authentification PAT et schéma d'identification code, où les données sont transmises à une instance DHIS 2 externe :

{
  "name": "External data exchange with PAT authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "accessToken": "d2pat_XIrqgAGjW935LLPuSP2hXSZwpTxTW2pg3580716988"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

La syntaxe des demandes de source suit la syntaxe de l'API du point d'extrémité de l'analyse. Cela signifie que pour la partie dx, les éléments de données, les indicateurs, les taux de déclaration des ensembles de données, les éléments de données de programme et les indicateurs de programme sont pris en charge. Notez que pour les éléments de données de programme, l'élément de données doit être préfixé avec l'identifiant du programme. Pour la partie pe, les périodes relatives ainsi que les périodes fixes sont prises en charge. Pour la partie ou, les unités d'organisation d'utilisateurs, les niveaux d'unités d'organisation et les groupes d'unités d'organisation ainsi que les unités d'organisation individuelles sont pris en charge. Pour une explication complète, veuillez consulter le chapitre Analytiques > les sections Dimensions et éléments et La dimension dx.

Réponse¶

201 Créés

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "response": {
    "responseType": "ObjectReport",
    "uid": "pG4bBTMiCqO",
    "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange",
    "errorReports": []
  }
}

Mettre à jour l'échange de données agrégées¶

PUT /api/aggregateDataExchanges/{id}

Type de contenu : application/json

Le contenu de la requête est identique à celui de l'opération de création.

Réponse¶

200 OK

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "response": {
    "responseType": "ObjectReport",
    "uid": "pG4bBTMiCqO",
    "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange",
    "errorReports": []
  }
}

Obtenir l'échange de données agrégées¶

GET /api/aggregateDataExchanges/{id}

Accepter: application/json

Les points d'extrémité de récupération suivent la sémantique habituelle de filtrage des champs et des objets des points d'extrémité de métadonnées. JSON est le seul format de réponse pris en charge.

Réponse¶

200 OK

Supprimer l'échange de données agrégées¶

DELETE /api/aggregateDataExchanges/{id}

Réponse¶

204 No Content

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "response": {
    "responseType": "ObjectReport",
    "uid": "pG4bBTMiCqO",
    "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange",
    "errorReports": []
  }
}

Exécuter l'échange de données agrégées¶

Un échange de données agrégées peut être exécuté directement à l'aide d'une requête POST au point d'extrémité suivant :

POST /api/aggregateDataExchanges/{id}/exchange

Réponse¶

200 OK

{
  "responseType": "ImportSummaries",
  "status": "SUCCESS",
  "imported": 36,
  "updated": 0,
  "deleted": 0,
  "ignored": 0,
  "importSummaries": ["<import summaries here>"]
}

Un résumé d'importation décrivant le résultat de l'échange de données sera renvoyé, y compris le nombre de valeurs de données qui ont été importées, mises à jour, supprimées et ignorées.

Obtenir les données sources¶

Les données agrégées pour la requête source d'un échange de données agrégées peuvent être récupérées dans le format de données analytiques avec une requête GET au point d'extrémité suivant :

GET /api/aggregateDataExchanges/{id}/sourceData

Accept: application/json

Réponse¶

200 OK

Paramètres de la requête¶

Le format de la charge utile de la réponse est identique à celui du point d'extrémité de l'API d'analyse. Ce point final est utile à des fins de débogage. Veuillez consulter le guide de l'API d'analyse pour plus de détails.

Obtenir les ensembles de valeurs des données sources¶

Les données agrégées pour la requête source d'un échange de données agrégées peuvent être récupérées dans le format de l'ensemble de valeurs de données avec une requête GET au point d'extrémité suivant :

GET /api/aggregateDataExchanges/{id}/sourceDataValueSets

Accept: application/json

Réponse¶

200 OK

Paramètres de la requête¶

Le format de la charge utile de la réponse est identique à celui du point d'extrémité de l'API relatif aux ensembles de valeurs de données. Ce point d'extrémité est utile à des fins de débogage. Veuillez consulter le guide de l'API sur les ensembles de valeurs de données pour plus d'informations.

Modèle de données¶

Le modèle de données d'échange de données agrégées / charge utile est décrit dans la section qui suit.

Gerer les erreurs¶

Lors de l'exécution d'un échange de données par identifiant, des informations sur le résultat de l'opération seront disponibles dans la charge utile de la réponse. La réponse contiendra une liste de résumés d'importation, c'est-à-dire un résumé d'importation par requête source. Le résumé d'importation indiquera tout conflit potentiel résultant de l'extraction des données de l'instance source et de l'importation des données dans l'instance cible.

Exemples¶

Échange de données externes avec le code du schéma d'identification¶

Cet exemple montre comment échanger des données basées sur des indicateurs de programme dans l'instance source de DHIS 2 et des éléments de données dans l'instance cible. Le schéma d'identification code signifie que l'échange de données utilisera la propriété code des métadonnées pour référencer les données. L'utilisation de codes est utile lorsque les propriétés de l'identifiant ne correspondent pas d'une instance DHIS 2 à l'autre. L'exemple montre comment les données peuvent être agrégées dans l'instance source, y compris l'agrégation dans le temps et la hiérarchie des unités, avant d'être échangées avec l'instance cible.

L'exemple échangera des données en utilisant l'environnement de jeu DHIS 2, et se référera à la version 2.39 à https://play.dhis2.org/2.39 comme instance source, et à la version 2.38 à https://play.dhis2.org/2.38.2.1 comme instance cible. Notez que les URL changeront au fil du temps, à mesure que de nouvelles versions de correctifs seront publiées, donc assurez-vous de mettre à jour les URL cibles.

• Connectez-vous à l'instance source, naviguez jusqu'à l'application Maintenance et vérifiez l'existence de trois indicateurs de programme.

• doses de BCG avec le code BCG_DOSE

• _Doses de rougeole_avec le code MEASLES_DOSE

• doses de fièvre jaune avec le code YELLOW_FEVER_DOSE

• Observez que l'unité d'org racine est Sierra Leone avec le code OU_525.

• Connectez-vous à l'instance cible et accédez à l'application Maintenance. Créez trois éléments de données, dont les codes correspondent aux indicateurs de programme mentionnés précédemment :

• Nom doses de BCG et le code BCG_DOSE

• Nom_doses de rougeole_ et le code MEASLES_DOSE

• Nom doses de fièvre jaune avec le code YELLOW_FEVER_DOSE

• Dans l'instance cible, créez un nouvel ensemble de données avec un nom quelconque, par exemple Échange de données, sélectionnez les trois éléments de données nouvellement créés et affectez l'ensemble de données à l'unité d'organisation principale Sierra Leone.

• Notons que l'unité d'organisation racine Sierra Leone a le code OU_525, qui est égal à l'instance source.

• Ouvrez un outil HTTP tel que Postman et créez la charge utile d'échange de données agrégées suivante en JSON.

  POST /api/aggregateDataExchanges
  

Content-Type: application/json

{
  "name": "Immunization doses program indicators to data elements",
  "source": {
    "requests": [
      {
        "name": "Immunization doses",
        "dx": [
          "BCG_DOSE",
          "MEASLES_DOSE",
          "YELLOW_FEVER_DOSE"
        ],
        "pe": [
          "202201"
        ],
        "ou": [
          "OU_525"
        ],
        "inputIdScheme": "code",
        "outputIdScheme": "code"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
      "url": "https://play.dhis2.org/2.38.2.1",
      "username": "admin",
      "password": "district"
    },
    "request": {
      "idScheme": "code"
    }
  }
}

• Dans cette charge utile, on remarque que pour la requête source, les indicateurs de programme sont référencés à l'aide de codes. Le paramètre inputIdScheme est fixé à code, ce qui signifie que le moteur d'analyse de DHIS 2 utilisera la propriété code pour référencer les métadonnées, telles que les indicateurs de programme. Le paramètre outputIdScheme est fixé à code, ce qui signifie que la propriété code sera utilisée pour référencer les métadonnées dans la sortie. Pour la requête cible, le idScheme est également fixé à code, ce qui signifie que la propriété code sera utilisée pour référencer les métadonnées lors de l'importation de la valeur des données. Notez que les schémas d'identification peuvent être spécifiés par type d'entité, comme dataElementIdScheme et orgUnitIdScheme.

• Notez que la période est 202201 ou janvier 2022. Il se peut que la période soit mise à jour au fil du temps.

• Exécutez la requête POST pour créer la définition d'échange de données agrégées. Confirmez que le code d'état de la réponse de l'API est 201. Notez que le nom de l'échange de données est unique. Notez l'ID de l'objet nouvellement créé en regardant response > uid dans le corps de la réponse.

• Exécutez l'échange de données nouvellement créé avec une requête POST (remplacez {id} par l'ID de l'échange de données) :

  POST /api/aggregateDataExchanges/{id}/exchange
  

• Confirmez que la réponse de l'API indique que trois valeurs de données ont été importées avec succès.

  {
    "responseType": "ImportSummaries",
    "status": "SUCCESS",
    "imported": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0
  }
  

• Dans l'instance cible, naviguez jusqu'à l'application Saisie de données, sélectionnez l'unité d'organisation Sierra Leone, l'ensemble de données Échange de données et la période Janvier 2022. On observe que les valeurs des données échangées sont visibles dans le formulaire.

En résumé, dans cet exemple, les enregistrements de données d'événements ont été agrégés du niveau de l'établissement au niveau national, dans la hiérarchie des unités d'organisation, et des données d'événements aux données mensuelles à l'aide d'indicateurs de programme. Les données ont été échangées avec une instance DHIS 2 cible en utilisant la propriété code pour référencer les métadonnées.