For the complete DHIS2 documentation index, see llms.txt.

Výměna dat¶

Souhrnná výměna dat¶

Tato část popisuje službu agregované výměny dat a rozhraní API.

Úvod¶

Služba agregované výměny dat nabízí možnost výměny dat mezi instancemi DHIS 2 a případně dalším softwarem, který podporuje formát JSON sady hodnot dat DHIS 2. Umožňuje také výměnu dat v rámci jedné instance DHIS 2, například pro agregaci dat trackeru a uložení výsledku jako souhrnná data.

Služba výměny souhrnných dat je vhodná pro případy použití, jako jsou:

Výměna dat mezi instancí HMIS a instancí datového portálu nebo datového skladu DHIS 2.
Výměna dat mezi instancí sledovače DHIS 2 s jednotlivými daty agregovanou instancí HMIS.
Předvýpočet sledovacích dat s indikátory programu uloženými jako agregované hodnoty dat.
Hlášení dat od národního HMIS globálnímu dárci.

Přehled¶

Služba agregované výměny dat umožňuje výměnu dat mezi zdrojovou instancí DHIS 2 a cílovou instancí DHIS 2. Výměna dat může být externí, pro kterou je cílová instance odlišná/externí než zdrojová instance . Výměna dat může být také interní, pro kterou je cílová instance stejná jako zdrojová instance. Zdroj agregované výměny dat může obsahovat více zdrojových požadavků, přičemž zdrojový požadavek zhruba odpovídá požadavku analytického rozhraní API.

Datová hodnota bude načtena a transformována do formátu data value set a poté odeslána do cílové instance DHIS 2. Služba agregované výměny dat podporuje schémata identifikátorů, aby umožnila flexibilitu při mapování metadat mezi instancemi.

Data budou načtena a agregována ze zdrojové instance pomocí analytického nástroje. To znamená, že v požadavku na zdrojovou instanci lze odkazovat na datové prvky, souhrnné ukazatele, četnost hlášení datových souborů a ukazatele programu. Zdrojový požadavek také obsahuje období, kde jsou podporována pevná i relativní období, a organizační jednotky. Na zdrojový požadavek lze použít libovolný počet filtrů.

Výměna dat může být spuštěna jako plánovaná úloha, kde lze výměnu dat nastavit tak, aby probíhala v určitém intervalu. Výměna dat může být také spuštěna na vyžádání prostřednictvím API.

K vytváření a manipulaci s výměnami souhrnných dat jsou vyžadována oprávnění F_AGGREGATE_DATA_EXCHANGE_PUBLIC_ADD / F_AGGREGATE_DATA_EXCHANGE_PRIVATE_ADD a F_AGGREGATE_DATA_EXCHANGE_DELETE.

Definice agregované výměny dat jsou běžná metadata v DHIS 2, což znamená, že definice lze importovat a exportovat mezi instancemi DHIS 2. Výjimkou jsou přihlašovací údaje (uživatelská jména a přístupové tokeny), které nebudou při exportech metadat vystaveny. Pověření jsou v úložišti šifrována, aby byla zajištěna další vrstva zabezpečení.

The aggregate data exchange service was introduced in version 2.39, which means that the source instance of DHIS 2 must be version 2.39 or later. The target instance of DHIS 2 must be version 2.38 or later.

Ověření¶

Pro výměny dat typu externí musí být zadána základní adresa URL a autentizační pověření pro cílovou instanci DHIS 2. Pro autentizaci je podporována základní autentizace a osobní přístupové tokeny (PAT).

Doporučuje se zadat buď základní ověřování, nebo ověřování PAT. Pokud jsou zadány oba, má přednost ověřování PAT.

Všimněte si, že podpora PAT byla zavedena ve verzi 2.38.1, což znamená, že pro použití ověřování PAT musí být cílová instance DHIS 2 verze 2.38.1 nebo novější.

API¶

Rozhraní API pro agregovanou výměnu dat je popsáno v následující části.

Vytvořte agregovanou výměnu dat¶

POST /api/aggregateDataExchanges

Content-Type: application/json

Příklad interní výměny dat, kde jsou data událostí vypočítána s programovými indikátory a uložena jako agregované hodnoty dat:

{
  "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"
    }
  }
}

Příklad externí datové výměny dat se základním ověřováním a schématem ID kódu, kde jsou data odeslána do externí instance DHIS 2:

{
  "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"
    }
  }
}

Příklad externí datové výměny dat s autentizací PAT a schématem ID code, kde jsou data odeslána do externí instance DHIS 2:

{
  "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"
    }
  }
}

The syntax for the source requests follow the analytics endpoint API syntax. This means that for the dx part, data elements, indicators, data set reporting rates, program data elements and program indicators are supported. Note that for program data elements, the data element must be prefixed with the program identifier. For the pe part, relative periods as well as fixed periods are supported. For the ou part, user org units, org unit levels and org unit groups as well as individual org units are supported. Consult the Analytics chapter > the Dimensions and items and The dx dimension sections for a full explanation.

Odpověď¶

201 Created

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

Update aggregate data exchange¶

PUT /api/aggregateDataExchanges/{id}

Content-Type: application/json

The request payload is identical to the create operation.

Odpověď¶

200 OK

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

Get aggregate data exchange¶

GET /api/aggregateDataExchanges/{id}

Accept: application/json

The retrieval endpoints follow the regular metadata endpoint field filtering and object filtering semantics. JSON is the only supported response format.

Odpověď¶

200 OK

Delete aggregate data exchange¶

DELETE /api/aggregateDataExchanges/{id}

Odpověď¶

204 No Content

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

Run aggregate data exchange¶

An aggregate data exchange can be run directly with a POST request to the following endpoint:

POST /api/aggregateDataExchanges/{id}/exchange

Odpověď¶

200 OK

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

An import summary describing the outcome of the data exchange will be returned, including the number of data values which were imported, updated, deleted and ignored.

Get source data¶

The aggregate data for the source request of an aggregated data exchange can be retrieved in the analytics data format with a GET request to the following endpoint:

GET /api/aggregateDataExchanges/{id}/sourceData

Accept: application/json

Odpověď¶

200 OK

Query parameters¶

Parametr dotazu	Požadované	Popis	Možnosti
outputIdScheme	Ne	Override the output identifier scheme for the data response.	UID \| CODE \| ATTRIBUTE:{ID}

The response payload format is identical with the analytics API endpoint. This endpoint is useful for debugging purposes. Consult the analytics API guide for additional details.

Get source data value sets¶

The aggregate data for the source request of an aggregated data exchange can be retrieved in the data value set format with a GET request to the following endpoint:

GET /api/aggregateDataExchanges/{id}/sourceDataValueSets

Accept: application/json

Odpověď¶

200 OK

Query parameters¶

Parametr dotazu	Požadované	Popis	Možnosti
outputIdScheme	Ne	Override the output identifier scheme for the data response.	UID \| CODE \| ATTRIBUTE:{ID}

The response payload format is identical with the data value sets API endpoint. This endpoint is useful for debugging purposes. Consult the data value sets API guide for additional details.

Data model¶

The aggregate data exchange data model / payload is described in the following section.

Pole	Datový typ	Povinné	Popis
název	Řetězec	Ano	Name of aggregate data exchange. Unique.
zdroj	Objekt	Ano	Source for aggregate data exchange.
source.params	Objekt	Ne	Parameters for source request.
source.params.periodTypes	Array/String	Ne	Allowed period types for overriding periods in source request.
source.requests	Array/Object	Ano	Source requests.
source.requests.name	Řetězec	Ano	Name of source request.
source.requests.visualization	Řetězec	Ne	Identifier of associated visualization object.
source.requests.dx	Array/String	Ano	Identifiers of data elements, indicators, data sets and program indicators for the source request.
source.requests.pe	Array/String	Ano	Identifiers of fixed and relative periods for the source request.
source.requests.ou	Array/String	Ano	Identifiers of organisation units for the source request.
source.requests.filters	Array (Object)	Ne	Filters for the source request.
source.requests.filters.dimension	Řetězec	Ne	Dimension identifier for the filter.
source.requests.filters.items	Array/String	Ne	Item identifiers for the filter.
source.requests.inputIdScheme	Řetězec	Ne	Input ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.requests.outputDataElementIdScheme	Řetězec	Ne	Output data element ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.requests.outputOrgUnitIdScheme	Řetězec	Ne	Output org unit ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.requests.outputIdScheme	Řetězec	Ne	Output general ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.target	Objekt	Ano	Target for aggregate data exchange.
source.target.type	Řetězec	Ano	Type of target, can be `EXTERNAL`, `INTERNAL`.
source.target.api	Objekt	Conditional	Target API information, only mandatory for type `EXTERNAL`.
source.target.api.url	Řetězec	Conditional	Base URL of target DHIS 2 instance, do not include the `/api` part.
source.target.api.accessToken	Řetězec	Conditional	Access token (PAT) for target DHIS 2 instance, used for PAT authentication.
source.target.api.username	Řetězec	Conditional	Username for target DHIS 2 instance, used for basic authentication.
source.target.api.password	Řetězec	Conditional	Password for target DHIS 2 instance, used for basic authentication.
source.target.request	Objekt	Ne	Target request information.
source.target.request.dataElementIdScheme	Řetězec	Ne	Input data element ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.target.request.orgUnitIdScheme	Řetězec	Ne	Input org unit ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.target.request.categoryOptionComboIdScheme	Řetězec	Ne	Input category option combo ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.
source.target.request.idScheme	Řetězec	Ne	Input general ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.

Error handling¶

When running a data exchange by identifier, information about the outcome of the operation will be available in the response payload. The response will contain a list of import summaries, i.e. one import summary per source request. The import summary will indicate any potential conflicts as a result of data retrieval from the source instance and data import in the target instance.

Příklady¶

External data exchange with identifier scheme code¶

This example will demonstrate how to exchange data based on program indicators in the source DHIS 2 instance and data elements in the target instance. The code identifier scheme, which means the data exchange will use the code property on the metadata to reference the data. Using codes is useful when the ID properties don't match across DHIS 2 instances. The example will demonstrate how data can be aggregated in the source instance, including aggregation in time and the unit hierarchy, before being exchanged with the target instance.

The example will exchange data using the DHIS 2 play environment, and refer to the 2.39 version at https://play.dhis2.org/2.39 as the source instance, and the 2.38 version at https://play.dhis2.org/2.38.2.1 as the target instance. Note that the URLs will change over time as new patch versions are released, so make sure to update the target URLs.

Log in to the source instance, navigate to the Maintenance app and observe that three program indicators exist.
BCG doses with code BCG_DOSE
Measles doses with code MEASLES_DOSE
Yellow fever doses with code YELLOW_FEVER_DOSE
Observe that the root org unit is Sierra Leone with code OU_525.
Log in to the target instance and navigate to the Maintenance app. Create three data elements, where the codes match the previously mentioned program indicators:
Name BCG doses and code BCG_DOSE
Name Measles doses and code MEASLES_DOSE
Name Yellow fever doses with code YELLOW_FEVER_DOSE
In the target instance, create a new data set with any name, e.g. Data exchange, select the tree newly created data elements, and assign the data set to the root org unit Sierra Leone.
Observe that the root org unit Sierra Leone has the code OU_525, which is equal to the source instance.
Open an HTTP tool such as Postman and put together the following aggregate data exchange payload in 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"
    }
  }
}

In this payload, observe that for the source request, program indicators are referred to using codes. The inputIdScheme is set to code, which means that the DHIS 2 analytics engine will use the code property to reference metadata, such as program indicators. The outputIdScheme is set to code, which means that the code property will be used to reference metadata in the output. For the target request, the idScheme is also set to code, which means that the code property will be used to reference metadata during the data value import. Note that ID schemes can be specified per entity type, such as dataElementIdScheme and orgUnitIdScheme.
Note that the period is 202201 or January 2022. Note that the period might have to be updated over time.
Run the POST request to create the aggregate data exchange definition. Confirm that the API response status code is 201. Note that the name of the data exchange is unique. Take a note of the ID of the newly created object by looking at response > uid in the response body.
Run the newly created data exchange with a POST request (replace {id} with the ID of the data exchange):
```
POST /api/aggregateDataExchanges/{id}/exchange
```

Confirm that the API response indicates that three data values were successfully imported.

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

In the target instance, navigate to the Data entry app, select org unit Sierra Leone, data set Data exchange and period January 2022. Observe that the exchanged data values are visible in the form.

To summarize, in this example, event data records were aggregated from the facility level to the national level in the org unit hierarchy and from event data to monthly data values using program indicators. The data values were exchanged with a target DHIS 2 instance by using the code property to reference metadata.