Metadata¶

Schémata identifikátorů¶

This section provides an explanation of the identifier scheme concept. Identifier schemes are used to map metadata objects to other metadata during import, and to render metadata as part of exports. Note that not all schemes work for all API calls, and not all schemes can be used for both input and output. This is outlined in the sections explaining the various API endpoints.

Úplná sada dostupných typů objektů schématu identifikátorů je uvedena níže s použitím názvu vlastnosti pro použití v dotazech:

• idScheme

• dataElementIdScheme

• categoryOptionComboIdScheme

• orgUnitIdScheme

• programIdScheme

• programStageIdScheme

• trackedEntityIdScheme

• trackedEntityAttributeIdScheme

The general idScheme applies to all types of objects. It can be overridden by specific object types.

The default scheme for all parameters is UID (stable DHIS2 identifiers). The supported identifier schemes are described in the table below.

Tabulka: Hodnoty schématu

Note that identifier schemes is not an independent feature but needs to be used in combination with resources such as data value import, metadata import and GeoJson import.

Například pro zadání CODE jako obecného schématu ID a přepsání pomocí UID pro schéma ID organizační jednotky můžete použít tyto parametry dotazu:

?idScheme=CODE&orgUnitIdScheme=UID

As another example, to specify an attribute for the organisation unit id scheme, code for the data element id scheme and use the default UID id scheme for all other objects you can use these parameters:

?orgUnitIdScheme=ATTRIBUTE:j38fk2dKFsG&dataElementIdScheme=CODE

Procházení webového API¶

The entry point for browsing the Web API is /api. This resource provides links to all available resources. Four resource representation formats are consistently available for all resources: HTML, XML, JSON, and JSONP. Some resources will have other formats available, like MS Excel, PDF, CSV, and PNG. To explore the API from a web browser, navigate to the /api entry point and follow the links to your desired resource, for instance /api/dataElements. For all resources which return a list of elements certain query parameters can be used to modify the response:

Tabulka: Parametry databázového dotazu

Příkladem použití těchto parametrů k získání úplného seznamu skupin datových prvků ve formátu odpovědi XML je:

/api/dataElementGroups.xml?links=false&paging=false

You can query for elements on the name property instead of returning a full list of elements using the query query variable. In this example we query for all data elements with the word "anaemia" in the name:

/api/dataElements?query=anaemia

Můžete získat konkrétní stránky a velikosti stránek takových objektů:

/api/dataElements.json?page=2&pageSize=20

Stránkování můžete zcela deaktivovat takto:

/api/indicatorGroups.json?paging=false

Chcete-li řadit výsledek na základě konkrétní vlastnosti:

/api/indicators.json?order=shortName:desc

You can find an object based on its ID across all object types through the identifiableObjects resource:

/api/identifiableObjects/<id>

Překlad¶

DHIS2 supports translations of database content, such as data elements, indicators, and programs. All metadata objects in the Web API have properties meant to be used for display / UI purposes, which include displayName, displayShortName, displayDescription and displayFormName (for data elements and tracked entity attributes).

Tabulka: Možnosti překladu

Překladové API¶

The translations for an object is rendered as part of the object itself in the translations array. Note that the translations array in the JSON/XML payloads is normally pre-filtered for you, which means they can not directly be used to import/export translations (as that would normally overwrite locales other than current users).

Příklad datového prvku s překladovým polem filtrovaným na národní prostředí uživatele:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute French",
  "translations": [
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    }
  ]
}

Příklad datového prvku s vypnutými překlady:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
  "translations": [
    {
      "property": "FORM_NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "Accute Flaccid Paral"
    },
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "DESCRIPTION",
      "locale": "en_FK",
      "value": "aa"
    }
  ]
}

Note that even if you get the unfiltered result, and are using the appropriate type endpoint i..e /api/dataElements we do not allow updates, as it would be too easy to make mistakes and overwrite the other available locales.

To read and update translations you can use the special translations endpoint for each object resource. These can be accessed by GET or PUT on the appropriate /api/<object-type>/<object-id>/translations endpoint.

As an example, for a data element with identifier FTRrcoaog83, you could use /api/dataElements/FTRrcoaog83/translations to get and update translations. The fields available are property with options NAME, SHORT_NAME, FORM_NAME, DESCRIPTION, locale which supports any valid locale ID and the translated property value.

Příklad vlastnosti NAME pro francouzské národní prostředí:

{
  "property": "NAME",
  "locale": "fr",
  "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
}

This payload would then be added to a translation array, and sent back to the appropriate endpoint:

{
  "translations": [
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
    }
  ]
}

For a data element with ID FTRrcoaog83 you can PUT this to /api/dataElements/FTRrcoaog83/translations. Make sure to send all translations for the specific object and not just for a single locale (if not you will potentially overwrite existing locales for other locales).

Stavový kód bude 204 No Content , pokud byla hodnota dat úspěšně uložena nebo aktualizována, nebo 404 Not Found , pokud došlo k chybě ověření (např. více než jeden SHORT_NAME pro stejné locale).

Verze webového rozhraní API¶

Webové rozhraní API je verzováno od verze DHIS 2.25. Verzování API se řídí číslováním hlavních verzí DHIS2. Příklad: verze API pro DHIS 2.33 je 33.

You can access a specific API version by including the version number after the /api component, as an example like this:

/api/33/dataElements

If you omit the version part of the URL, the system will use the current API version. As an example, for DHIS 2.25, when omitting the API part, the system will use API version 25. When developing API clients it is recommended to use explicit API versions (rather than omitting the API version), as this will protect the client from unforeseen API changes.

The last three API versions will be supported. As an example, DHIS version 2.27 will support API version 27, 26 and 25.

Note that the metadata model is not versioned and that you might experience changes e.g. in associations between objects. These changes will be documented in the DHIS2 major version release notes.

Filtr objektů metadat¶

To filter the metadata there are several filter operations that can be applied to the returned list of metadata. The format of the filter itself is straight-forward and follows the pattern property:operator:value, where property is the property on the metadata you want to filter on, operator is the comparison operator you want to perform and value is the value to check against (not all operators require value).

Please see the schema section to discover which properties are available. In addition to the listed properties filters can apply to custom attribute values by using the attribute's ID as property name.

Recursive filtering, ie. filtering on associated objects or collection of objects, is supported as well.

Tabulka: Dostupné operátory

Operators will be applied as logical and query. If you need a or query, you can have a look at the in filter and the section below. The filtering mechanism allows for recursion. See below for some examples.

Získejte datové prvky s ID vlastností ID1 nebo ID2:

/api/dataElements?filter=id:eq:ID1&filter=id:eq:ID2

Získejte všechny datové prvky, které mají datovou sadu s ID ID1:

/api/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

Get all data elements with aggregation operator sum and value type int:

/api/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

You can do filtering within collections, e.g. to get data elements which are members of the ANC data element group you can use the following query using the id property of the associated data element groups:

/api/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

To get data elements with a particular attribute value for a metadata attribute, a filter for the attribute ID and the attribute value can be specified using the same collection query syntax:

/api/dataElements.json?filter=attributeValues.attribute.id:eq:n2xYlNbsfko&filter=attributeValues.value:eq:AFP

Get data elements which have any option set:

/api/dataElements?filter=optionSet:!null

Since all operators are and by default, you can't find a data element matching more than one id, for that purpose you can use the in operator.

/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

Logické operátory¶

As mentioned in the section before, the default logical operator applied to the filters is AND which means that all object filters must be matched. There are however cases where you want to match on one of several filters (maybe id and code field) and in those cases, it is possible to switch the root logical operator from AND to OR using the rootJunction parameter.

Example: Normal filtering where both id and code must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

Example: Filtering where the logical operator has been switched to OR and now only one of the filters must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR

Filtr identifikovatelných tokenů¶

In addition to the specific property based filtering mentioned above, we also have token based AND filtering across a set of properties: id, code, and name (also shortName if available). These properties are commonly referred to as identifiable. The idea is to filter metadata whose id, name, code or short name containing something.

Example: Filter all data elements containing 2^nd in any of the following: id,name,code, shortName

/api/dataElements.json?filter=identifiable:token:2nd

Je také možné zadat více hodnot filtrování.

Příklad: Získejte všechny datové prvky, kde se ANC visit nachází v kterékoli z identifikovatelných vlastností. Systém vrací všechny datové prvky, kde se oba tokeny (ANC a návštěva) nacházejí kdekoli v identifikovatelných vlastnostech.

/api/dataElements.json?filter=identifiable:token:ANC visit

It is also possible to combine the identifiable filter with property-based filter and expect the rootJunction to be applied.

/api/dataElements.json?filter=identifiable:token:ANC visit&filter=displayName:ilike:tt1

/api/dataElements.json?filter=identifiable:token:ANC visit
  &filter=displayName:ilike:tt1&rootJunction=OR

Indexable only filter for tracked entity attributes¶

For tracked entity attributes, there is a special filter in addition to the previous mentioned filtering capabilities. Some of the tracked entity attributes are candidates for creating a trigram index for better lookup performance. Using the indexableOnly parameter set to true, the results can be filtered to include only the attributes that are trigram indexable.

Example: Get all tracked entity attributes that are indexable.

/api/trackedEntityAttributtes.json?indexableOnly=true

Additional filters along with the indexableOnly parameter can be specified.

Example: Get all tracked entity attributes where ANC is found in any of the name property. The system returns the tracked entity attributes where the name matches the provided keyword as well as if the attribute is indexable.

/api/trackedEntityAttributtes.json?filter=name:like:ANC&indexableOnly=true

Filtr pole metadat¶

In many situations, the default views of the metadata can be too verbose. A client might only need a few fields from each object and want to remove unnecessary fields from the response. To discover which fields are available for each object please see the schema section. In addition to the listed properties custom attributes can be included for top level objects by using the attribute's ID as property name.

The format for include/exclude allows for infinite recursion. To filter at the "root" level you can just use the name of the field, i.e. ?fields=id,name which would only display the id and name fields for every object. For objects that are either collections or complex objects with properties on their own, you can use the format ?fields=id,name,dataSets[id,name] which would return id, name of the root, and the id and name of every data set on that object. Negation can be done with the exclamation operator, and we have a set of presets of field select. Both XML and JSON formats are supported.

Příklad: Získejte id aname ve zdroji indikátorů:

/api/indicators?fields=id,name

Example: Get id and name from data elements, and id and name from the associated data sets:

/api/dataElements?fields=id,name,dataSets[id,name]

Example: Get id, name and the value of a user defined attribute with ID DnrLSdo4hMl for organisation units:

/api/organisationUnits?fields=id,name,DnrLSdo4hMl

The attribute is then included as property DnrLSdo4hMl of each matching object in the response. This can be renamed using the rename transformer as shown in the next section.

To exclude a field from the output you can use the exclamation ! operator. This is allowed anywhere in the query and will simply not include that property as it might have been inserted in some of the presets.

A few presets (selected fields groups) are available and can be applied using the : operator.

Tabulka: operátory vlastností

Tabulka: Předvolby pole

Příklad: Zahrňte všechna pole z datových sad kromě organizačních jednotek:

/api/dataSets?fields=:all,!organisationUnits

Příklad: Zahrnout pouze ID, název a kolekci organizačních jednotek z datové sady, ale ID z organizačních jednotek vyloučit:

/api/dataSets/BfMAe6Itzgt?fields=id,name,organisationUnits[:all,!id]

Příklad: Zahrňte pojmenovatelné vlastnosti ze všech indikátorů:

/api/indicators.json?fields=:nameable

Transformátory polí¶

Transformace pole lze použít k transformaci vlastností. Syntaxe je popsána níže.

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

This will rename the id property to i and name property to n.

Na jednu vlastnost lze použít více transformátorů opakováním operátoru transformátoru:

/api/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements)

Podporované transformátory jsou popsány v tabulce níže.

Tabulka: Dostupné transformátory

Příklady¶

Příklady použití transformátoru jsou uvedeny níže.

Získejte velikost sbírky:

/api/dataElements?fields=dataSets~size

Otestujte, zda je kolekce prázdná:

/api/dataElements?fields=dataSets~isEmpty

Otestujte, zda kolekce není prázdná:

/api/dataElements?fields=dataSets~isNotEmpty

Přejmenovat vlastnosti:

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

Použít stránkování na kolekci:

/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)

Získejte pole s ID organizačních jednotek:

/api/categoryOptions.json?fields=id,organisationUnits~pluck

Získejte pole s názvy organizačních jednotek:

/api/categoryOptions.json?fields=id,organisationUnits~pluck[name]

Zadejte pole dataElements do pole id:

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy[id,name,valueType]

Zadejte pole dataElements pomocí pole valueType, protože vícenásobné požadavky budou mít za následek pole (datových prvků):

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy(valueType)[id,name,valueType]

Vytváření, čtení, aktualizace, mazání, ověřování metadat¶

All metadata entities in DHIS2 have their own API endpoint which supports CRUD operations (create, read, update and delete). The endpoint URLs follows this format:

/api/<entityName>

The entityName uses the camel-case notation. As an example, the endpoint for data elements is:

/api/dataElements

Vytvořit / aktualizovat parametry¶

Následující parametry dotazu na dotaz jsou k dispozici ve všech koncových bodech metadat.

Tabulka: Dostupné filtry dotazů

Vytváření a aktualizace objektů¶

For creating new objects you will need to know the endpoint, the type format, and make sure that you have the required authorities. As an example, we will create and update a constant. To figure out the format, we can use the new schema endpoint for getting format description. So we will start with getting that info:

http://<server>/api/schemas/constant.json

From the output, you can see that the required authorities for create are F_CONSTANT_ADD, and the important properties are: name and value. From this, we can create a JSON payload and save it as a file called constant.json:

{
  "name": "PI",
  "value": "3.14159265359"
}

Stejný obsah jako datový obsah XML:

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

We are now ready to create the new constant by sending a POST request to the constants endpoint with the JSON payload using curl:

curl -d @constant.json "http://server/api/constants" -X POST
  -H "Content-Type: application/json" -u user:password

Konkrétní příklad zveřejnění konstanty na demo serveru:

curl -d @constant.json "https://play.dhis2.org/api/constants" -X POST
  -H "Content-Type: application/json" -u admin:district

Pokud vše proběhlo dobře, měli byste vidět výstup podobný:

{
  "status": "SUCCESS",
  "importCount": {
    "imported": 1,
    "updated": 0,
    "ignored": 0,
    "deleted": 0
  },
  "type": "Constant"
}

The process will be exactly the same for updating, you make your changes to the JSON/XML payload, find out the ID of the constant, and then send a PUT request to the endpoint including ID:

curl -X PUT -d @pi.json -H "Content-Type: application/json"
  -u user:password "http://server/api/constants/ID"

Mazání objektů¶

Deleting objects is very straight forward, you will need to know the ID and the endpoint of the type you want to delete, let's continue our example from the last section and use a constant. Let's assume that the id is abc123, then all you need to do is the send the DELETE request to the endpoint + id:

curl -X DELETE -u user:password "http://server/api/constants/ID"

Úspěšné odstranění by mělo vrátit stav HTTP 204 (žádný obsah).

Přidávání a odebírání objektů ze sbírek¶

The collections resource lets you modify collections of objects.

Přidávání nebo odebírání jednotlivých objektů¶

In order to add or remove objects to or from a collection of objects you can use the following pattern:

/api/{collection-object}/{collection-object-id}/{collection-name}/{object-id}

You should use the POST method to add, and the DELETE method to remove an object. When there is a many-to-many relationship between objects, you must first determine which object owns the relationship. If it isn't clear which object this is, try the call both ways to see which works.

Součásti vzoru jsou:

• collection object: The type of objects that owns the collection you chtít upravit.

• collection object id: Identifikátor objektu, který vlastní collection you want to modify.

• collection name: Název kolekce, kterou chcete upravit.

• object id: Identifikátor objektu, který chcete přidat nebo odebrat from the collection.

As an example, in order to remove a data element with identifier IDB from a data element group with identifier IDA you can do a DELETE request:

DELETE /api/dataElementGroups/IDA/dataElements/IDB

To add a category option with identifier IDB to a category with identifier IDA you can do a POST request:

POST /api/categories/IDA/categoryOptions/IDB

Přidání nebo odebrání více objektů¶

You can add or remove multiple objects from a collection in one request with a payload like this:

{
  "identifiableObjects": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ]
}

Pomocí tohoto datového obsahu můžete přidávat, nahrazovat nebo mazat položky:

Přidávání položek:

POST /api/categories/IDA/categoryOptions

Replacing Items:

PUT /api/categories/IDA/categoryOptions

Delete Items:

DELETE /api/categories/IDA/categoryOptions

Přidávání a odebírání objektů v jednom požadavku¶

You can both add and remove objects from a collection in a single POST request to the following URL:

POST /api/categories/IDA/categoryOptions

Formát datového obsahu je:

{
  "additions": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ],
  "deletions": [{
      "id": "IDD"
    }, {
      "id": "IDE"
    }, {
      "id": "IDF"
    }
  ]
}

Ověřování datového obsahu¶

DHIS2 supports system wide validation of metadata payloads, which means that create and update operations on the API endpoints will be checked for valid payload before allowing changes to be made. To find out what validations are in place for a specific endpoint, have a look at the /api/schemas endpoint, i.e. to figure out which constraints a data element have, you would go to /api/schemas/dataElement.

You can also validate your payload manually by sending it to the proper schema endpoint. If you wanted to validate the constant from the create section before, you would send it like this:

POST /api/schemas/constant

Jednoduchý (nevalidující) příklad by byl:

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/schemas/dataElement"

Což přinese výsledek:

[
   {
      "message" : "Required property missing.",
      "property" : "type"
   },
   {
      "property" : "aggregationOperator",
      "message" : "Required property missing."
   },
   {
      "property" : "domainType",
      "message" : "Required property missing."
   },
   {
      "property" : "shortName",
      "message" : "Required property missing."
   }
]

Částečné aktualizace¶

Pro naše koncové body API, které se zabývají metadaty, podporujeme částečné aktualizace (PATCH) pomocí opravy JSON [standardní] (https://tools.ietf.org/html/rfc6902). Užitná zátěž v podstatě nastiňuje sadu operací, které chcete použít na existující objekt metadat. Podrobnosti a příklady oprav JSON najdete na [jsonpatch.com] (http://jsonpatch.com/). Podporovány jsou tři operátory: add, remove a replace.

Níže je uvedeno několik příkladů relevantních pro DHIS2. Všimněte si, že jakákoli aktualizace datové části by měla být považována za operaci HTTP PUT, tj. jakákoli mutace musí vést k platnému datovému obsahu metadat PUT.

Výchozí importReportMode pro opravu JSON je ERRORS_NOT_OWNER, což znamená, že při aktualizaci jakékoli vlastnosti, která není vlastněna tímto konkrétním objektem (například při pokusu o přidání skupiny indikátorů přímo do indikátoru), se zobrazí chyba.

Podle specifikace opravy JSON musíte při odesílání oprav vždy použít typ mime application/json-patch+json.

Příklady¶

Update name and value type of data element¶

PATCH /api/dataElements/{id}

[
  {"op": "add", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/valueType", "value": "INTEGER"}
] 

Add new data element to a data element group¶

PATCH /api/dataElementGroups/{id}

[
  {"op": "add", "path": "/dataElements/-", "value": {"id": "data-element-id"}}
]

Remove all data element associations from a data element group¶

PATCH /api/dataElementGroups/{id}

[
  {"op": "remove", "path": "/dataElements"}
]

Change domain and value type of a data element¶

PATCH /api/dataElements/{id}

[
    {"op": "add", "path": "/domainType", "value": "TRACKER"},
    {"op": "add", "path": "/valueType", "value": "INTEGER"}
]

Remove a specific orgUnit from an orgUnit group¶

PATCH /api/organisationUnitGroups/{id}

[
  {"op": "remove", "path": "/organisationUnits/1"}
]

Blocked add dataElementGroup to dataElement¶

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "add", "path": "/dataElementGroups/-", "value": {"id": "data-element-group-id"}}
]

Blocked update name of dataElementGroup in dataElement¶

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "add", "path": "/dataElementGroups/0", "value": {"name": "new-name"}}
]

Remove collection item by id¶

PATCH /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/organisationUnits", "id": "u6CvKyF0Db5"}
]

Patch request with invalid path¶

Pokud je vlastnost cesta neplatná nebo neexistuje, opravná služba vrátí chybu, jak je uvedeno níže

PATCH /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/test", "id": "u6CvKyF0Db5"}
]

{
    "httpStatus": "Bad Request",
    "httpStatusCode": 400,
    "status": "ERROR",
    "message": "Invalid path /test"
}

Metadata CSV export¶

Field filtering works almost the same for CSV (please note that using CSV on the /api/metadata endpoint is not supported), but not that field fransformations are not yet supported.

For endpoints that support CSV (our metadata endpoints like /api/dataElements /api/organisationUnits) you can either use the Accept header with value text/csv or you can use the extension .csv. Be aware that complex objects are not supported, and we only support id-object collections (so a list of UIDs will be returned).

Příklady¶

Get all data elements including their group associations¶

/api/dataElements.csv?fields=id,displayName,dataElementGroups

Get all org units including geometry (which will get ignored)¶

/api/organisationUnits.csv?fields=id,displayName,organisationUnitGroups,geometry

Export metadat¶

This section explains the metatada API which is available at /api/metadata. XML and JSON resource representations are supported.

/api/metadata

The most common parameters are described below in the "Export Parameter" table. You can also apply this to all available types by using type:fields=<filter> and type:filter=<filter>. You can also enable/disable the export of certain types by setting type=true|false.

Tabulka: Parametr exportu

Příklady exportu metadat¶

Export all metadata. Be careful as the response might be very large depending on your metadata configuration:

/api/metadata

Export všech metadat seřazených podle lastUpdated sestupně:

/api/metadata?defaultOrder=lastUpdated:desc

Exportujte metadata pouze včetně indikátorů a skupin indikátorů:

/api/metadata?indicators=true&indicatorGroups=true

Export id a displayName pro všechny datové prvky, seřazené podle displayName:

/api/metadata?dataElements:fields=id,name&dataElements:order=displayName:desc

Export datových prvků a indikátorů, kde název začíná „ANC“:

/api/metadata?filter=name:startsWith:ANC&dataElements=true&indicators=true

Export metadat se závislostmi¶

When you want to exchange metadata for a data set, program, category combo, dashboard, option set or data element group from one DHIS2 instance to another instance there are six dedicated endpoints available:

/api/dataSets/{id}/metadata.json

/api/programs/{id}/metadata.json

/api/categoryCombos/{id}/metadata.json

/api/dashboards/{id}/metadata.json

/api/optionSets/{id}/metadata.json

/api/dataElementGroups/{id}/metadata.json

Tyto exporty lze poté importovat pomocí /api/metadata.

Tyto koncové body také podporují následující parametry:

Tabulka: Parametr exportu

Import metadat¶

This section explains the metadata import API. XML and JSON resource representations are supported. Metadata can be imported using a POST request.

/api/metadata

The importer allows you to import metadata payloads which may include many different entities and any number of objects per entity. The metadata export generated by the metadata export API can be imported directly.

The metadata import endpoint support a variety of parameters, which are listed below.

Tabulka: Parametr importu

(*) Currently the mergeMode=MERGE option of the import service has limitations and doesn't support all objects. It doesn't work with some object types such as Embedded objects, or objects which are saved as JSONB format in database ( sharing, attributeValues, etc...). Fixing those issues are complicated and would just cause new issues. Therefore, this mergedMode=MERGE is deprecated and currently is not recommended to use. The update mode should always be mergedMode=REPLACE. We have developed a new JSON Patch API which can be used as an alternative approach. This feature is introduced in 2.37 release.

An example of a metadata payload to be imported looks like this. Note how each entity type have their own property with an array of objects:

{
  "dataElements": [
    {
      "name": "EPI - IPV 3 doses given",
      "shortName": "EPI - IPV 3 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    },
    {
      "name": "EPI - IPV 4 doses given",
      "shortName": "EPI - IPV 4 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    }
  ],
  "indicators": [
    {
      "name": "EPI - ADS stock used",
      "shortName": "ADS stock used",
      "numerator": "#{LTb8XeeqeqI}+#{Fs28ZQJET6V}-#{A3mHIZd2tPg}",
      "numeratorDescription": "ADS 0.05 ml used",
      "denominator": "1",
      "denominatorDescription": "1",
      "annualized": false,
      "indicatorType": {
        "id": "kHy61PbChXr"
      }
    }
  ]
}

When posting this payload to the metadata endpoint, the response will contain information about the parameters used during the import and a summary per entity type including how many objects were created, updated, deleted and ignored:

{
  "importParams": {
    "userOverrideMode": "NONE",
    "importMode": "COMMIT",
    "identifier": "UID",
    "preheatMode": "REFERENCE",
    "importStrategy": "CREATE_AND_UPDATE",
    "atomicMode": "ALL",
    "mergeMode": "REPLACE",
    "flushMode": "AUTO",
    "skipSharing": false,
    "skipTranslation": false,
    "skipValidation": false,
    "metadataSyncImport": false,
    "firstRowIsHeader": true,
    "username": "UNICEF_admin"
  },
  "status": "OK",
  "typeReports": [
    {
      "klass": "org.hisp.dhis.dataelement.DataElement",
      "stats": {
        "created": 2,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 2
      }
    },
    {
      "klass": "org.hisp.dhis.indicator.Indicator",
      "stats": {
        "created": 1,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 1
      }
    }
  ],
  "stats": {
    "created": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0,
    "total": 3
  }
}

GeoJSON import¶

Import GeoJSON se používá k připojení geometrických dat k organizačním jednotkám.

For a bulk import a GeoJSON file with a feature collection is expected. Each feature in the collection requires a reference to the organisation unit it should be linked to.

By default, the geometry from the file is stored as the geometry property of an organisation unit. To store additional geometries attributes of type GEOJSON can be created. When attributes are use all geometries from a file are stored for the same attribute which is provided with an additional parameter attributeId.

Hromadný import dat GeoJSON¶

Tabulka: Parametry importu

Uasge:

POST /api/organisationUnits/geometry

The post body is the GeoJSON file. Content type should be application/json or application/geo+json. The file may be .zip or .gzip compressed.

For example, a default file where id is used to refer to an organisation unit id has this structure:

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "O6uvpzGd5pu",
      "geometry": { ... }
    },
    ...
  ]
}

A file where a feature property is used to refer to the organisation unit code would have this structure:

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "code": "OU1_CODE" },
      "geometry": { ... }
    },
    ...
  ]
}

A geometry may also be null to effectively clear or delete the geometry for specific organisation units. There is a special bulk deletion API that is described in the next section.

When run synchronously an import report is returned directly. The HTTP status code is always OK, the status in the message payload indicates if all rows were imported successfully. The import counts statistics contained in the report give further information:

• imported: number of organisation units that were successfully updated with a geometry that did not have one before for the updated property
• updated: number of organisation units that were successfully updated with a geometry that did have value for the updated property already
• ignored: number of organisation units that failed to update
• deleted: number of organisation units that where successfully update with a empty geometry

When the import is run asynchronous the request returns immediately with status OK and job configuration response that contains a relative reference to the task endpoint that allows to track the status of the asynchronous import. For example:

/api/system/tasks/GEOJSON_IMPORT/{job-id}

Souhrn, který je vrácen přímo pro synchronní spuštění, je k dispozici na adrese

/api/system/taskSummaries/GEOJSON_IMPORT/{job-id}

jakmile je import dokončen.

Hromadné mazání dat GeoJSON¶

To clear or unset the geometry data for all organisation units use:

DELETE /api/organisationUnits/geometry

To clear or unset the geometry data for a specific GEOJSON attribute for all organisation units use:

DELETE /api/organisationUnits/geometry?attributeId={attr-id}

Clearing is always synchronous and returns a similar report as the bulk import. It does not support any other parameters. No dry-run can be performed. Bulk clearing requires the F_PERFORM_MAINTENANCE authority.

GeoJSON Single Data Import¶

Samostatný import umožňuje aktualizovat geometrii jedné organizační jednotky.

POST /api/organisationUnits/{id}/geometry

The post body only contains the GeoJSON geometry value, for example:

{
  "type": "Polygon",
  "coordinates": [...]
}

GeoJSON Single Data Deletion¶

To clear the geometry GeoJSON data of an individual organisation unit use:

DELETE /api/organisationUnits/{id}/geometry

Similarly to clear a GEOJSON attribute value for an individual organisation unit use:

DELETE /api/organisationUnits/{id}/geometry?attributeId={attr-id}

Clearing is always synchronous returns a similar report as single import. The dry-run parameter is supported as well. The performing user requires authority to modify the target organisation unit.

Schéma¶

A resource which can be used to introspect all available DXF 2 objects can be found on /api/schemas. For specific resources you can have a look at /api/schemas/<type>.

Chcete-li získat všechna dostupná schémata v XML:

GET /api/schemas.xml

Chcete-li získat všechna dostupná schémata v JSON:

GET /api/schemas.json

Postup získání schématu JSON pro konkrétní třídu:

GET /api/schemas/dataElement.json

Ikony¶

DHIS2 includes a collection of icons that can be used to give visual context to metadata. These icons can be accessed through the icons resource.

GET /api/icons

This endpoint returns a list of information about the available icons. Each entry contains information about the icon, and a reference to the actual icon.

{
  key: "mosquito_outline",
  description: "Mosquito outline",
  keywords: [
    "malaria",
    "mosquito",
    "dengue"
  ],
  href: "<dhis server>/api/icons/mosquito_outline/icon.svg"
}

The keywords can be used to filter which icons to return. Passing a list of keywords with the request will only return icons that match all the keywords:

GET /api/icons?keywords=shape,small

Seznam všech jedinečných klíčových slov naleznete na zdroji klíčových slov:

GET /api/icons/keywords

Typ vykreslení¶

Some metadata types have a property named renderType. The render type property is a map between a device and a renderingType. Applications can use this information as a hint on how the object should be rendered on a specific device. For example, a mobile device might want to render a data element differently than a desktop computer.

V současné době jsou k dispozici dva různé druhy typů vykreslování:

1. Vykreslení typu hodnoty

2. Vykreslování části programové fáze

K dispozici jsou také 2 typy zařízení:

1. MOBILE

2. PLOCHA

The following table lists the metadata and rendering types available. The value type rendering has addition constraints based on the metadata configuration, which will be shown in a second table.

Tabulka: Přehled metadat a RenderingType

Since handling the default rendering of data elements and tracked entity attributes are depending on the value type of the object, there is also a DEFAULT type to tell the client it should be handled as normal. Program Stage Section is LISTING as default.

Tabulka: RenderingTypes povoleny na základě typů hodnot

A complete reference of the previous table can also be retrieved using the following endpoint:

GET /api/staticConfiguration/renderingOptions

Value type rendering also has some additional properties that can be set, which is usually needed when rendering some of the specific types:

Tabulka: vlastnosti objektu renderType

Při vytváření nebo aktualizaci metadat uvedených v první tabulce lze nastavit renderingType. Příklad datového obsahu pro typ vykreslování pro sekci fáze programu vypadá takto:

{
  "renderingType": {
    "type": "MATRIX"
  }
}

Pro datový prvek a atribut trasované entity:

{
  "renderingType": {
    "type": "SLIDER",
    "min": 0,
    "max": 1000,
    "step": 50,
    "decimalPoints": 0
  }
}

Styl objektu¶

Most metadata have a property names "style". This property can be used by clients to represent the object in a certain way. The properties currently supported by style is as follows:

Tabulka: Vlastnosti stylu

Currently, there is no official list or support for icon-libraries, so this is currently up to the client to provide. The following list shows all objects that support style:

• Datový prvek

• Možnost kategorie datových prvků

• Datová sada

• Indikátor

• Možnost

• Program

• Indikátor programu

• Sekce programu

• Fáze programu

• Sekce fáze programu

• Vztah (Trasovač)

• Atribut trasované entity

• Typ trasované entity

When creating or updating any of these objects, you can include the following payload to change the style:

{
  "style": {
    "color": "#ffffff",
    "icon": "my-beautiful-icon"
  }
}

Indikátory¶

Tato část popisuje indikátory a výrazy indikátorů.

Agregované indikátory¶

To retrieve indicators you can make a GET request to the indicators resource like this:

/api/indicators

Indikátory představují výrazy, které lze vypočítat a prezentovat jako výsledek. Výrazy indikátorů se dělí na čitatele a jmenovatele. Čitatelé a jmenovatelé jsou matematické výrazy, které mohou obsahovat odkazy na datové prvky, jiné indikátory, konstanty a skupiny organizačních jednotek. Proměnné budou při použití např. ve výkazech nahrazeny hodnotami dat. Proměnné, které jsou ve výrazech povoleny, jsou popsány v následující tabulce.

Tabulka: Indikátorové proměnné

V rámci operandu datového prvku nebo agregovaného datového prvku lze provést následující substituce:

Syntaxe vypadá jako toto:

#{<dataelement-id>.<catoptcombo-id>} + C{<constant-id>} + OUG{<orgunitgroup-id>}

Odpovídající příklad vypadá takto:

#{P3jJH5Tu5VC.S34ULMcHMca} + C{Gfd3ppDfq8E} + OUG{CXw2yu5fodb}

Note that for data element variables the category option combo identifier can be omitted. The variable will then represent the total for the data element, e.g. across all category option combos. Example:

#{P3jJH5Tu5VC} + 2

Data element operands can include any of category option combination and attribute option combination, and use wildcards to indicate any value:

#{P3jJH5Tu5VC.S34ULMcHMca} + #{P3jJH5Tu5VC.*.j8vBiBqGf6O} + #{P3jJH5Tu5VC.S34ULMcHMca.*}

Příklad použití skupiny datových prvků:

#{deGroup:oDkJh5Ddh7d} + #{deGroup:GBHN1a1Jddh.j8vBiBqGf6O}

Příklad použití možností kategorie, skupiny datových prvků a skupiny možností kategorie:

#{P3jJH5Tu5VC.co:FbLZS3ueWbQ} + #{deGroup:GBHN1a1Jddh.coGroup:OK2Nr4wdfrZ.j8vBiBqGf6O}

Příklad použití více skupin možností kategorií:

#{P3jJH5Tu5VC.coGroup:OK2Nr4wdfrZ&j3C417uW6J7&ddAo6zmIHOk}

Příklad s použitím datového prvku programu a atributu programu:

( D{eBAyeGv0exc.vV9UWAZohSf} * A{IpHINAT79UW.cejWyOfXge6} ) / D{eBAyeGv0exc.GieVkTxp4HH}

Příklad kombinace programových indikátorů a souhrnných indikátorů:

I{EMOt6Fwhs1n} * 1000 / #{WUg3MYWQ7pt}

Příklad použití četnosti hlášení zpráv:

R{BfMAe6Itzgt.REPORTING_RATE} * #{P3jJH5Tu5VC.S34ULMcHMca}

Další příklad četnosti hlášení zpráv využívající skutečné hlášení zpráv datových souborů a očekávané hlášení zpráv:

R{BfMAe6Itzgt.ACTUAL_REPORTS} / R{BfMAe6Itzgt.EXPECTED_REPORTS}

Příklad použití existujícího indikátoru:

N{Rigf2d2Zbjp} * #{P3jJH5Tu5VC.S34ULMcHMca}

Expressions can be any kind of valid mathematical expression, as an example:

( 2 * #{P3jJH5Tu5VC.S34ULMcHMca} ) / ( #{FQ2o8UBlcrS.S34ULMcHMca} - 200 ) * 25

Indikátory programu¶

To retrieve program indicators you can make a GET request to the program indicators resource like this:

/api/programIndicators

Program indicators can contain information collected in a program. Indicators have an expression which can contain references to data elements, attributes, constants and program variables. Variables which are allowed in expressions are described in the following table.

Tabulka: proměnné Programového indikátoru

Syntaxe vypadá jako toto:

#{<programstage-id>.<dataelement-id>} + #{<attribute-id>} + V{<varible-id>} + C{<constant-id>}

Odpovídající příklad vypadá takto:

#{A03MvHHogjR.a3kGcGDCuk6} + A{OvY4VVhSDeJ} + V{incident_date} + C{bCqvfPR02Im}

Výrazy¶

Expressions are mathematical formulas which can contain references to data elements, constants and organisation unit groups. To validate and get the textual description of an expression, you can make a GET request to the expressions resource:

/api/expressions/description?expression=<expression-string>

The response follows the standard JSON web message format. The status property indicates the outcome of the validation and will be "OK" if successful and "ERROR" if failed. The message property will be "Valid" if successful and provide a textual description of the reason why the validation failed if not. The description provides a textual description of the expression.

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Valid",
  "description": "Acute Flaccid Paralysis"
}

Organizační jednotky¶

Zdroj organisationUnits se řídí standardními konvencemi jako ostatní metadatové zdroje v DHIS2. Tento zdroj podporuje některé další parametry dotazu.

Získejte seznam organizačních jednotek¶

Chcete-li získat seznam organizačních jednotek, můžete použít následující zdroj.

/api/33/organisationUnits

Tabulka: Parametry dotazu organizačních jednotek

Get organisation unit with sub-hierarchy¶

Chcete-li získat organizační jednotku včetně organizačních jednotek v její podhierarchii, můžete použít následující zdroj.

/api/33/organisationUnits/{id}

Tabulka: Parametry organizační jednotky

Get organisation units by category option¶

Účelově vytvořený koncový bod pro načtení přidružení mezi možnostmi kategorií a organizačními jednotkami. Tento koncový bod je preferovaným způsobem načítání přidružení organizačních jednotek programu.

/api/33/categoryOptions/orgUnits?categoryOptions={categoryOptionIdA},{categoryOptionIdB}

odpovědi budou mít následující formát:

{
  "<categoryOptionIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdC>": []
}

Možnosti kategorií, které jsou přístupné všem organizačním jednotkám, jsou vráceny s prázdným polem ([]) organizačních jednotek.

Get organisation units by programs¶

Účelově vytvořený koncový bod pro načtení přidružení mezi programy a organizačními jednotkami. Tento koncový bod je preferovaným způsobem načítání přidružení organizačních jednotek programu.

/api/33/programs/orgUnits?programs={programIdA},{programIdB}

odpovědi budou mít následující formát:

{
  "<programIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdC>": []
}

Programy, které jsou přístupné všem organizačním jednotkám, jsou vráceny s prázdným polem ([]) organizačních jednotek.

Rozdělená organizační jednotka¶

Koncový bod rozdělení organizační jednotky umožňuje rozdělit organizační jednotky na několik cílových organizačních jednotek.

Požadavek¶

Rozdělení organizačních jednotek pomocí požadavku POST:

POST /api/organisationUnits/split

Užitná zátěž ve formátu JSON vypadá takto:

{
  "source": "rspjJHg4WY1",
  "targets": [
    "HT0w9YLMLyn",
    "rEpnzuNpRKM"
  ],
  "primaryTarget": "HT0w9YLMLyn",
  "deleteSource": true
}

Vlastnosti JSON jsou popsány v následující tabulce.

Tabulka: Rozdělit pole datového obsahu

Operace rozdělení rozdělí zdrojovou organizační jednotku na cílové organizační jednotky. Před rozdělením se doporučuje nejprve vytvořit nové cílové organizační jednotky a minimálně zajistit, že pro cílové organizační jednotky neexistují žádná agregovaná data. Lze zadat libovolný počet cílových organizačních jednotek.

Operace rozdělení přenese všechna přidružení metadat zdrojové organizační jednotky do cílových organizačních jednotek. To zahrnuje datové sady, programy, skupiny organizačních jednotek, možnosti kategorií, uživatele, vizualizace, mapy a zprávy o událostech.

Operace přenese všechny datové záznamy zdrojové organizační jednotky do organizační jednotky zadané jako primární cíl, nebo pokud není specifikována, do první zadané cílové organizační jednotky. To zahrnuje agregované hodnoty dat, záznamy o schválení dat, události, sledované entity a další.

Validation¶

Platí následující omezení a chybové kódy.

Tabulka: Omezení a chybové kódy

Sloučit organizační jednotky¶

Koncový bod sloučení organizačních jednotek vám umožňuje sloučit několik organizačních jednotek do cílové organizační jednotky.

Authorisation¶

The main authority required to perform an organisation unit merge is F_ORGANISATION_UNIT_MERGE.

Požadavek¶

Sloučení organizačních jednotek s požadavkem POST:

POST /api/organisationUnits/merge

Užitná zátěž ve formátu JSON vypadá takto:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "dataValueMergeStrategy": "LAST_UPDATED",
  "dataApprovalMergeStrategy": "LAST_UPDATED",
  "deleteSources": true
}

Vlastnosti JSON jsou popsány v následující tabulce.

Tabulka: Sloučit pole datového obsahu

Operace sloučení sloučí zdrojové organizační jednotky do cílové organizační jednotky. Před provedením sloučení se doporučuje nejprve vytvořit novou cílovou organizační jednotku a minimálně zajistit, že pro cílovou organizační jednotku neexistují žádná agregovaná data. Lze zadat libovolný počet zdrojových organizačních jednotek.

Operace sloučení přenese všechna přidružení metadat zdrojových organizačních jednotek do cílové organizační jednotky. To zahrnuje datové sady, programy, skupiny organizačních jednotek, možnosti kategorií, uživatele, vizualizace, mapy a zprávy o událostech. Operace také přenese všechna data událostí a sledování, jako jsou události, registrace, historie vlastnictví, vlastnictví programu a sledované entity, do cílové organizační jednotky.

Zadaná strategie slučování datových hodnot definuje, jak se zachází s datovými hodnotami. U strategie LAST_UPDATED se datové hodnoty pro všechny zdrojové organizační jednotky přenesou do cílové organizační jednotky a v situaci, kdy pro stejné parametry existují datové hodnoty, bude použita poslední aktualizovaná nebo vytvořená datová hodnota. To se provádí, aby se zabránilo duplicitě dat. U strategie DISCARD se datové hodnoty nepřenesou do cílové organizační jednotky a jednoduše se smažou. Zadaná strategie slučování schvalování dat definuje, jak se zachází se záznamy schvalování dat, a řídí se stejnou logikou jako hodnoty dat.

Validation¶

Platí následující omezení a chybové kódy.

Tabulka: Omezení a chybové kódy

Datové sady¶

The dataSets resource follows the standard conventions as other metadata resources in DHIS2. This resource supports some additional query parameters.

/api/33/dataSets

Chcete-li načíst verzi datové sady, můžete vystavit požadavek GET:

GET /api/33/dataSets/<uid>/version

To bump (increase by one) the version of a data set you can issue a POST request:

POST /api/33/dataSets/<uid>/version

Data set notification template¶

The dataset notification templates resource follows the standard conventions as other metadata resources in DHIS2.

GET /api/33/dataSetNotficationTemplates

Chcete-li načíst šablonu oznámení sady dat, můžete vystavit požadavek GET:

GET /api/33/dataSetNotficationTemplates/<uid>

Chcete-li přidat šablonu oznámení sady dat, můžete vystavit požadavek POST:

POST /api/33/dataSetNotficationTemplates

Chcete-li odstranit šablonu oznámení datové sady, můžete zadat požadavek DELETE:

DELETE /api/33/dataSetNotficationTemplates/<uid>

Ukázka datového obsahu JSON je uvedena níže:

{
  "name": "dataSetNotificationTemplate1",
  "dataSetNotificationTrigger": "DATA_SET_COMPLETION",
  "relativeScheduledDays": 0,
  "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
  "dataSets": [{
    "id": "eZDhcZi6FLP"
  }],
  "deliveryChannels": ["SMS","EMAIL"],
  "subjectTemplate": "V{data_set_name}",
  "messageTemplate": "V{data_set_name}V{registration_period}",
  "sendStrategy": "SINGLE_NOTIFICATION"
}

notificationRecipient can be one of: - USER_GROUP for internal messages - ORGANISATION_UNIT_CONTACT for external messages

Naplněné úrovně organizační jednotky¶

The filledOrganisationUnitLevels resource provides an ordered list of organisation unit levels, where generated levels are injected into the list to fill positions for which it does not exist a persisted level.

GET /api/33/filledOrganisationUnitLevels

To set the organisation unit levels you can issue a POST request with a JSON payload and content type application/json looking like this:

{
  "organisationUnitLevels": [{
    "name": "National",
    "level": 1,
    "offlineLevels": 3
  }, {
    "name": "District",
    "level": 2
  }, {
    "name": "Chiefdom",
    "level": 3
  }, {
    "name": "Facility",
    "level": 4
  }]
}

Prediktory¶

A predictor allows you to generate data values based on an expression. This can be used for example to generate targets, thresholds, or estimated values.

To retrieve predictors you can make a GET request to the predictors resource like this:

/api/predictors

Vytvoření prediktoru¶

You can create a predictor with a POST request to the predictors resource:

POST /api/predictors

Ukázkové užitečné zatížení vypadá takto:

{
  "id": "AG10KUJCrRk",
  "name": "Malaria Outbreak Threshold Predictor",
  "shortName": "Malaria Outbreak Predictor",
  "description": "Computes the threshold for potential malaria outbreaks based on the mean plus 1.5x the std dev",
  "output": {
    "id": "nXJJZNVAy0Y"
  },
  "generator": {
    "expression": "AVG(#{r6nrJANOqMw})+1.5*STDDEV(#{r6nrJANOqMw})",
    "description": "Maximum normal malaria case count",
    "missingValueStrategy": "NEVER_SKIP",
    "slidingWindow": false
  },
  "periodType": "Monthly",
  "sequentialSampleCount": 4,
  "sequentialSkipCount": 1,
  "annualSampleCount": 3,
  "organisationUnitLevels": [4]
}

The output element refers to the identifier of the data element for which to saved predicted data values. The generator element refers to the expression to use when calculating the predicted values.

Výrazy prediktoru¶

A predictor always has a generator expression that describes how the predicted value is calculated. A predictor may also have a skip test expression returning a boolean value. When the skip test expression is present, it is evaluated in each of the sampled periods to tell whether values from that period should be skipped.

The following variables may be used in either a generator expression or a skip test expression:

Generování předpokládaných hodnot¶

To run all predictors (generating predicted values) you can make a POST request to the run resource:

POST /api/predictors/run

To run a single predictor you can make a POST request to the run resource for a predictor:

POST /api/predictors/AG10KUJCrRk/run

Pravidla programu¶

This section is about sending and reading program rules, and explains the program rules data model. The program rules give functionality to configure dynamic behaviour in the programs in DHIS2.

Model pravidla programu¶

The program rules data model consists of programRuleVariables, programRules and programRuleActions. The programRule contains an expression - when this expression is true, the child programRuleActions is triggered. The programRuleVariables is used to address data elements, tracked entity data values and other data values needed to run the expressions. All programRules in a program share the same library of programRuleVariables, and one programRuleVariable can be used in several programRules' expressions.

Podrobnosti modelu modelu programu¶

The following table gives a detailed overview over the programRule model.

Tabulka: programRule

Podrobnosti o akčním modelu pravidla programu¶

The following table gives a detailed overview over the programRuleAction model.

Tabulka: programRuleAction

ProgramRuleAction Validation¶

There are certain validations added to ProgramRuleAction model in 2.37. Main purpose was to keep user from creating erroneous ProgramRules in order to keep the database consistent. These validations depends on program rule action type. Each action type has its own respective validation.

Tabulka: Ověření ProgramRuleAction

Apart from above validations, data field in program rule action which normally contains expression can also be evaluated using below api endpoint.

POST /api/programRuleActions/data/expression/description?programId=<uid>

{
  "condition": "1 + 1"
}

Podrobnosti o variabilním modelu pravidla programu¶

Následující tabulka poskytuje podrobný přehled o modelu programRuleVariable.

Tabulka: programRuleVariable

Vytváření pravidel programu¶

• K provádění hrubých operací je v rozhraní API k dispozici zdroj programRules.

Chcete-li načíst seznam programRules, můžete provést požadavek GET takto:

/api/programRules

Chcete-li načíst jeden programRule, můžete provést požadavek GET takto:

/api/programRules/<program_rule_uid>

Chcete-li uložit / přidat jeden programRule, můžete provést požadavek POST takto:

/api/programRules/<program_rule_uid>

Chcete-li aktualizovat jeden programRule, můžete provést požadavek PUT takto:

/api/programRules/<program_rule_uid>

Chcete-li odstranit jeden programRule, můžete provést požadavek VYMAZAT takto:

/api/programRules/<program_rule_uid>

Chcete-li získat popis podmínky programRule, můžete použít POST a zadat řetězec podmínky v těle POST.

/api/programRules/condition/description?<program_rule_uid>

formuláře¶

To retrieve information about a form (which corresponds to a data set and its sections) you can interact with the form resource. The form response is accessible as XML and JSON and will provide information about each section (group) in the form as well as each field in the sections, including labels and identifiers. By supplying period and organisation unit identifiers the form response will be populated with data values.

Tabulka: Parametry dotazu formuláře

Chcete-li načíst formulář pro datovou sadu, můžete provést požadavek GET takto:

/api/dataSets/<dataset-id>/form.json

Načíst formulář pro datovou sadu s identifikátorem "BfMAe6Itzgt" v XML:

/api/dataSets/BfMAe6Itzgt/form

Načtení formuláře včetně metadat v JSON:

/api/dataSets/BfMAe6Itzgt/form.json?metaData=true

To retrieve the form filled with data values for a specific period and organisation unit in XML:

/api/dataSets/BfMAe6Itzgt/form.xml?ou=DiszpKrYNg8&pe=201401

When it comes to custom data entry forms, this resource also allows for creating such forms directly for a data set. This can be done through a POST or PUT request with content type text/html where the payload is the custom form markup such as:

curl -d @form.html "localhost/api/dataSets/BfMAe6Itzgt/form"
  -H "Content-Type:text/html" -u admin:district -X PUT

Dokumenty¶

Odkazy na soubory lze uložit pomocí zdroje dokumentu.

Tabulka: Pole dokumentu

Požadavek GET na koncový bod dokumentů vrátí všechny dokumenty:

/api/documents

Požadavek POST na koncový bod dokumentů vytvoří nový dokument:

curl -X POST -d @document.json -H "Content-type: application/json"
  "http://dhis.domain/api/documents"

{
  "name": "dhis home",
  "external": true,
  "url": "https://www.dhis2.org"
}

A GET request with the id of a document appended will return information about the document. A PUT request to the same endpoint will update the fields of the document:

/api/documents/<documentId>

Appending /data to the GET request will return the actual file content of the document:

/api/documents/<documentId>/data

Import metadat CSV¶

DHIS2 podporuje import metadat ve formátu CSV, jako jsou datové prvky, organizační jednotky a ověřovací pravidla. Vlastnosti různých objektů metadat jsou identifikovány na základě pořadí sloupců / indexu sloupců (podrobnosti viz níže). Můžete vynechat nepožadované vlastnosti / sloupce objektu, ale protože pořadí sloupců je významné, musí být zahrnut prázdný sloupec. Jinými slovy, pokud byste chtěli určit vlastnosti / sloupce, které se objeví pozdě v pořadí sloupců, ale neurčit určité sloupce, které se objeví brzy v pořadí, můžete pro ně zahrnout prázdné / nevyplněné sloupce.

První řádek souboru CSV je považován za záhlaví a je během importu ignorován. Znak comma by měl být použit jako oddělovač textu. Text, který obsahuje čárky, musí být uveden v dvojitých uvozovkách.

Chcete-li nahrát metadata ve formátu CSV, můžete odeslat požadavek POST do koncového bodu metadat:

POST /api/metadata?classKey=CLASS-KEY

Jsou podporovány následující typy objektů. Parametr dotazu classKey je povinný a je uveden vedle každého typu objektu v tabulce níže.

Tabulka: Typy objektů a klíče

Tip

Pokud používáte curl, měla by být použita možnost --data-binary, protože zachovává konce řádků a nové řádky, což je pro data CSV zásadní.

Jako příklad můžete k nahrání souboru datových prvků ve formátu CSV pomocí curl použít následující příkaz:

curl --data-binary @data_elements.csv "http://localhost/api/metadata?classKey=DATA_ELEMENT"
  -H "Content-Type:application/csv" -u admin:district

Formáty aktuálně podporovaných typů objektů pro import CSV jsou uvedeny v následujících částech.

Datové prvky¶

Tabulka: Formát CSV datových prvků

An example of a CSV file for data elements can be seen below. The first row will always be ignored. Note how you can skip columns and rely on default values to be used by the system. You can also skip columns which you do not use which appear to the right of the ones

name,uid,code,shortname,description
"Women participated skill development training",,"D0001","Women participated in training"
"Women participated community organizations",,"D0002","Women participated in organizations"

Organizační jednotky¶

Tabulka: Formát CSV organizační jednotky

A minimal example for importing organisation units with a parent unit looks like this:

name,uid,code,parent
"West province",,"WESTP","ImspTQPwCqd"
"East province",,"EASTP","ImspTQPwCqd"

Pravidla ověřování¶

Tabulka: Formát CSV ověřovacího pravidla

Sady možností¶

Tabulka: Možnost Nastavit formát CSV

The format for option sets is special. The three first values represent an option set. The three last values represent an option. The first three values representing the option set should be repeated for each option.

optionsetname,optionsetuid,optionsetcode,optionname,optionuid,optioncode
"Color",,"COLOR","Blue",,"BLUE"
"Color",,"COLOR","Green",,"GREEN"
"Color",,"COLOR","Yellow",,"YELLOW"
"Sex",,,"Male",,"MALE"
"Sex",,,"Female",,"FEMALE"
"Sex",,,"Unknown",,"UNKNOWN"
"Result",,,"High",,"HIGH"
"Result",,,"Medium",,"MEDIUM"
"Result",,,"Low",,"LOW"
"Impact","cJ82jd8sd32","IMPACT","Great",,"GREAT"
"Impact","cJ82jd8sd32","IMPACT","Medium",,"MEDIUM"
"Impact","cJ82jd8sd32","IMPACT","Poor",,"POOR"

Skupina možností¶

Tabulka: Formát CSV skupiny možností

Ukázkový datový obsah CSV OptionGroup

optionGroupName,optionGroupUid,optionGroupCode,optionGroupShortName,optionSetUid,optionUid,optionCode
optionGroupA,,,groupA,xmRubJIhmaK,,OptionA
optionGroupA,,,groupA,xmRubJIhmaK,,OptionB
optionGroupB,,,groupB,QYDAByFgTr1,,OptionC

Sada skupin možností¶

Tabulka: Skupina možností Nastavit formát CSV

Ukázkový datový obsah CSV OptionGroupSet

name,uid,code,description,datadimension,optionsetuid
optiongroupsetA,,,,,xmRubJIhmaK
optiongroupsetB,,,,false,QYDAByFgTr1

Indicators¶

An example of a CSV file for Indicators can be seen below. The first row will always be ignored. Note how you can skip columns and rely on default values to be used by the system. You can also skip columns which you do not use which appear to the right of the ones

Name,UID,Code,Description,shortName,denominator,denominatorDescription,numerator,numeratorDescription,annualized,decimals,indicatorType
Indicator A,yiAKjiZVoOU,CodeA,Indicator A description,Indicator A shortname,#{fbfJHSPpUQD},denominatorDescription,#{h0xKKjijTdI},numeratorDescription,false,2,sqGRzCziswD
Indicator B,Uvn6LCg7dVU,CodeB,Indicator B description,Indicator B shortname,#{fbfJHSPpUQD},denominatorDescription,#{h0xKKjijTdI},numeratorDescription,false,2,sqGRzCziswD

Členství ve sbírce¶

In addition to importing objects, you can also choose to only import the group-member relationship between an object and a group. Currently, the following group and object pairs are supported

• Skupina organizační jednotky - organizační jednotka

• Skupina datových prvků - datový prvek

• Skupina indikátorů - indikátor

• Sada skupin možností - Skupina možností

Formát CSV pro tyto importy je stejný

Tabulka: Formát CSV členství ve sbírce

Ostatní objekty¶

Tabulka: Skupina datových prvků, možnost kategorie, skupina možností kategorie, skupina organizačních jednotek Formát CSV

Příklad možností kategorií vypadá takto:

name,uid,code,shortname
"Male",,"MALE"
"Female",,"FEMALE"

Odstraněné objekty¶

Prostředek odstraněné objekty poskytuje protokol odstraněných objektů metadat.

/api/deletedObjects

Whenever an object of type metadata is deleted, a log is being kept of the uid, code, the type and the time of when it was deleted. This API is available at /api/deletedObjects field filtering and object filtering works similarly to other metadata resources.

Získejte odstraněné objekty datových prvků typu:

GET /api/deletedObjects.json?klass=DataElement

Get deleted object of type indicator which was deleted in 2015 and forward:

GET /api/deletedObjects.json?klass=Indicator&deletedAt=2015-01-01

Oblíbené¶

Některé typy objektů metadat lze označit jako oblíbené pro aktuálně přihlášeného uživatele. V současnosti to platí pro ovládací panely.

/api/dashboards/<uid>/favorite

To make a dashboard a favorite you can make a POST request (no content type required) to a URL like this:

/api/dashboards/iMnYyBfSxmM/favorite

To remove a dashboard as a favorite you can make a DELETE request using the same URL as above.

The favorite status will appear as a boolean favorite field on the object (e.g. the dashboard) in the metadata response.

Odběry¶

A logged user can subscribe to certain types of objects. Currently subscribable objects are those of type EventChart, EventReport, Map, Visualization and EventVisualization.

Poznámka

Objekty EventChart a EventReport jsou zastaralé. Místo toho použijte EventVisualization.

To get the subscribers of an object (return an array of user IDs) you can make a GET request:

/api/<object-type>/<object-id>/subscribers

Viz příklad takto:

/api/visualizations/DkPKc1EUmC2/subscribers

To check whether the current user is subscribed to an object (returns a boolean) you can perform a GET call:

/api/<object-type>/<object-id>/subscribed

Viz příklad takto:

/api/visualizations/DkPKc1EUmC2/subscribed

Pro přihlášení/odhlášení k odběru objektu provedete POST/DELETE požadavek (není vyžadován typ obsahu):

/api/<object-type>/<object-id>/subscriber

Zdroje souborů¶

File resources are objects used to represent and store binary content. The FileResource object itself contains the file meta-data (name, Content-Type, size, etc.) as well as a key allowing retrieval of the contents from a database-external file store. The FileResource object is stored in the database like any other but the content (file) is stored elsewhere and is retrievable using the contained reference (storageKey).

/api/fileResources

Obsah souborových prostředků není přímo přístupný, ale odkazuje se na ně z jiných objektů (například z datových hodnot) k ukládání binárního obsahu prakticky neomezené velikosti.

To create a file resource that does not require a corresponding data value, POST to the endpoint /api/fileResources with a multipart upload:

curl "https://server/api/fileResources" -X POST
  -F "file=@/path/to/file/name-of-file.png"

curl "https://server/api/fileResources?uid=0123456789x" -X POST
  -F "file=@/path/to/file/name-of-file.png"

To create both a file resource and a data value that references the file, POST to the /api/dataValues/file endpoint in DHIS 2.36 or later:

curl "https://server/api/dataValues/file?de=xPTAT98T2Jd
  &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -X POST
  -F "file=@/path/to/file/name-of-file.png"

For the api/fileResources endpoint, the only form parameter required is file, which is the file to upload. For the api/dataValues/file endpoint, the parameters required are the same as for a post to api/dataValues, with the addition of file.

The filename and content-type should also be included in the request but will be replaced with defaults when not supplied.

On successfully creating a file resource the returned data will contain a response field which in turn contains the fileResource like this:

{
  "httpStatus": "Accepted",
  "httpStatusCode": 202,
  "status": "OK",
  "response": {
    "responseType": "FileResource",
    "fileResource": {
      "name": "name-of-file.png",
      "created": "2015-10-16T16:34:20.654+0000",
      "lastUpdated": "2015-10-16T16:34:20.667+0000",
      "externalAccess": false,
      "publicAccess": "--------",
      "user": { ... },
      "displayName": "name-of-file.png",
      "contentType": "image/png",
      "contentLength": 512571,
      "contentMd5": "4e1fc1c3f999e5aa3228d531e4adde58",
      "storageStatus": "PENDING",
      "id": "xm4JwRwke0i"
    }
  }
}

Note that the response is a 202 Accepted, indicating that the returned resource has been submitted for background processing (persisting to the external file store in this case). Also, note the storageStatus field which indicates whether the contents have been stored or not. At this point, the persistence to the external store is not yet finished (it is likely being uploaded to a cloud-based store somewhere) as seen by the PENDING status.

Even though the content has not been fully stored yet the file resource can now be used, for example as referenced content in a data value (see Working with file data values). If we need to check the updated storageStatus or otherwise retrieve the metadata of the file, the fileResources endpoint can be queried.

curl "https://server/api/fileResources/xm4JwRwke0i" -H "Accept: application/json"

This request will return the FileResource object as seen in the response of the above example.

Omezení souborových zdrojů¶

• Souborové zdroje musí být odkazovány (přiřazeny) z jiného objektu in order to be persisted in the long term. A file resource which is created but not referenced by another object such as a data value is considered to be in staging. Any file resources which are in this state and are older than two hours will be marked for deletion and will eventually be purged from the system.

• ID vrácené počátečním vytvořením souborového prostředku není retrievable from any other location unless the file resource has bylo odkazováno (ve kterém bude ID uloženo jako reference), takže jeho ztráta bude vyžadovat opakování požadavku POST a nové objekt, který má být vytvořen. Prostředek osiřelého souboru bude vyčištěn up automatically.

• Objekty souborových prostředků jsou neměnné, což znamená, že modifikace nemají allowed and requires creating a completely new resource instead.

Seznam blokovaných zdrojů souborů¶

Nahrávání určitých typů souborů je z bezpečnostních důvodů blokováno.

Následující typy obsahu jsou blokovány.

Následující přípony souborů jsou blokovány.

Verze metadat¶

Tato část vysvětluje rozhraní API pro správu verzí metadat.

• /api/metadata/version: This endpoint will return the current metadata verzi systému, na kterém je vyvolána.

Tabulka: Parametry dotazu

Získejte příklady verzí metadat¶

Příklad: Získejte aktuální verzi metadat tohoto systému

Požadavek:

/api/metadata/version

Odezva:

{
  "name": "Version_4",
  "created": "2016-06-30T06:01:28.684+0000",
  "lastUpdated": "2016-06-30T06:01:28.685+0000",
  "externalAccess": false,
  "displayName": "Version_4",
  "type": "BEST_EFFORT",
  "hashCode": "848bf6edbaf4faeb7d1a1169445357b0",
  "id": "Ayz2AEMB6ry"
}

Příklad: Získejte podrobnosti o verzi s názvem „Version_2“

Požadavek:

/api/metadata/version?versionName=Version_2

Odezva:

{
  "name": "Version_2",
  "created": "2016-06-30T05:59:33.238+0000",
  "lastUpdated": "2016-06-30T05:59:33.239+0000",
  "externalAccess": false,
  "displayName": "Version_2",
  "type": "BEST_EFFORT",
  "hashCode": "8050fb1a604e29d5566675c86d02d10b",
  "id": "SaNyhusVxBG"
}

• /api/metadata/version/history: This endpoint will return the list of all metadata versions of the system on which it is invoked.

Tabulka: Parametry dotazu

Získá seznam všech verzí metadat¶

Příklad: Získat seznam všech verzí v tomto systému

Požadavek:

/api/metadata/version/history

Odezva:

{
  "metadataversions": [{
    "name": "Version_1",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T05:54:41.139+0000",
    "id": "SjnhUp6r4hG",
    "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798"
  }, {
    "name": "Version_2",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T05:59:33.238+0000",
    "id": "SaNyhusVxBG",
    "hashCode": "8050fb1a604e29d5566675c86d02d10b"
  }, {
    "name": "Version_3",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:23.680+0000",
    "id": "FVkGzSjAAYg",
    "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
  }]
}

Příklad: Získat seznam všech verzí v tomto systému vytvořených po verzi „Version_2“

Požadavek:

/api/metadata/version/history?baseline=Version_2

Odezva:

{
  "metadataversions": [{
    "name": "Version_3",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:23.680+0000",
    "id": "FVkGzSjAAYg",
    "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
  }, {
    "name": "Version_4",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:28.684+0000",
    "id": "Ayz2AEMB6ry",
    "hashCode": "848bf6edbaf4faeb7d1a1169445357b0"
  }]
 }

• /api/metadata/version/create: Tento koncový bod vytvoří metadata version for the version type as specified in the parameter.

Tabulka: Parametry dotazu

Users can select the type of metadata which needs to be created. Metadata Version type governs how the importer should treat the given version. This type will be used while importing the metadata. There are two types of metadata.

• BEST_EFFORT: This type suggests that missing references can be ignored and the importer can continue importing the metadata (e.g. missing data elements on a data element group import).

• ATOMIC: This type ensures a strict type checking of the metadata references and the metadata import will fail if any of the references do not exist.

Note

It's recommended to have an ATOMIC type of versions to ensure that all systems (central and local) have the same metadata. Any missing reference is caught in the validation phase itself. Please see the importer details for a full explanation.

Vytvořte verzi metadat¶

Příklad: Vytvořte verzi metadat typu BEST_EFFORT

Požadavek:

curl -X POST -u admin:district "https://play.dhis2.org/dev/api/metadata/version/create?type=BEST_EFFORT"

Odezva:

{
  "name": "Version_1",
  "created": "2016-06-30T05:54:41.139+0000",
  "lastUpdated": "2016-06-30T05:54:41.333+0000",
  "externalAccess": false,
  "publicAccess": "--------",
  "user": {
    "name": "John Traore",
    "created": "2013-04-18T17:15:08.407+0000",
    "lastUpdated": "2016-04-06T00:06:06.571+0000",
    "externalAccess": false,
    "displayName": "John Traore",
    "id": "xE7jOejl9FI"
  },
  "displayName": "Version_1",
  "type": "BEST_EFFORT",
  "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798",
  "id": "SjnhUp6r4hG"
}

• /api/metadata/version/{versionName}/data: This endpoint will download the actual metadata specific to the version name passed as path parameter.

• /api/metadata/version/{versionName}/data.gz: Tento koncový bod se stáhne the actual metadata specific to the version name passed as path parameter in a compressed format (gzipped).

Tabulka: Parametry cesty

Stažení metadat verze¶

Příklad: Získejte aktuální metadata pro "Version 5"

Požadavek:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/Version_5/data"

Odezva:

{
  "date": "2016-06-30T06:10:23.120+0000",
  "dataElements": [
    {
      "code": "ANC 5th Visit",
      "created": "2016-06-30T06:10:09.870+0000",
      "lastUpdated": "2016-06-30T06:10:09.870+0000",
      "name": "ANC 5th Visit",
      "id": "sCuZKDsix7Y",
      "shortName": "ANC 5th Visit ",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "zeroIsSignificant": false,
      "valueType": "NUMBER",
      "categoryCombo": {
        "id": "p0KPaWEg3cf"
      },
      "user": {
        "id": "xE7jOejl9FI"
      }
    }
  ]
}

Synchronizace metadat¶

This section explains the Metadata Synchronization API available starting 2.24

• /api/metadata/sync: Tento koncový bod provádí synchronizaci metadat název verze předaný v parametru dotazu stažením a import zadané verze ze vzdáleného serveru, jak je definováno v the settings app.

Tabulka: Parametry databázového dotazu

• Toto API by mělo být používáno s maximální opatrností. Upozorňujeme, že existuje alternativní způsob, jak dosáhnout synchronizace zcela automatizovaným způsobem využití úlohy synchronizace metadat ze „správy dat“ app. See Chapter 22, Section 22.17 of User Manual for more details regarding Metadata Sync Task.

• This sync API can alternatively be used to sync metadata for the verze, které selhaly z plánovače synchronizace metadat. Kvůli its dependence on the given metadata version number, care should be taken for the order in which this gets invoked. E.g. If this api is used to sync some higher version from the central instance, then the sync might fail as the metadata dependencies are not present in the local instance.

• Assume the local instance is at Version_12 and if this endpoint is used to sync Version_15 (of type BEST_EFFORT) from the central instance, the scheduler will start syncing metadata from Version_16. Místní instance tedy nebude mít metadata verze mezi Version_12 a Version_15. Musíte ručně sync the missing versions using these endpoints only.

Synchronizovat verzi metadat¶

Příklad: Synchronizace Version_6 z centrálního systému do tohoto systému

Požadavek:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/sync?versionName=Version_6"

Úložiště metadat¶

DHIS2 provides a metadata repository containing metadata packages with various content. A metadata package is a DHIS2-compliant JSON document which describes a set of metadata objects.

Chcete-li získat index dostupných balíčků metadat, můžete zadat požadavek GET na prostředek metadataRepo:

GET /api/synchronization/metadataRepo

A metadata package entry contains information about the package and a URL to the relevant package. An index could look like this:

{
  "packages": [
    {
      "id": "sierre-leone-demo",
      "name": "Sierra Leone demo",
      "description": "Sierra Leone demo database",
      "version": "0.1",
      "href": "https://dhis2.org/metadata-repo/221/sierra-leone-demo/metadata.json"
    },
    {
      "id": "trainingland-org-units",
      "name": "Trainingland organisation units",
      "description": "Trainingland organisation units with four levels",
      "version": "0.1",
      "href": "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
    }
  ]
}

A client can follow the URLs and install a metadata package through a POST request with content type text/plain with the metadata package URL as the payload to the metadataPull resource:

POST /api/synchronization/metadataPull

Příklad příkazu curl vypadá takto:

curl "localhost:8080/api/synchronization/metadataPull" -X POST
  -d "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
  -H "Content-Type:text/plain" -u admin:district

Reference to created by user¶

Každý objekt vytvořený v DHIS2 bude mít vlastnost s názvem user, která je spojena s User, který objekt vytvořil.

Od verze 2.36 jsme změnili název této vlastnosti na createdBy, aby nedošlo k záměně.

Aby však byla zachována zpětná kompatibilita, je původní vlastnost user stále zahrnuta do datového obsahu a funguje normálně jako dříve.

{
  "createdBy": {
      "displayName": "John Kamara",
      "name": "John Kamara",
      "id": "N3PZBUlN8vq",
      "username": "district"
  },
  "user": {
      "displayName": "John Kamara",
      "name": "John Kamara",
      "id": "N3PZBUlN8vq",
      "username": "district"
  }
}

Pracovní postup návrhu metadat¶

Koncový bod pracovního postupu návrhu metadat umožňuje pracovní postup navrhování a přijímání změn metadat.

/api/metadata/proposals

Navrhněte změnu metadat¶

Nabídka vždy cílí na jeden objekt metadat pomocí:

POST /api/metadata/proposals

V závislosti na datovém obsahu by návrh mohl:

• Přidat nový objekt metadat.
• Aktualizujte existující odkazy na objekt metadat podle ID.
• Odstraňte existující objekt metadat, na který odkazuje ID.

Chcete-li navrhnout přidání nového objektu metadat, odešlete datovou část JSON, jako je následující:

{
  "type": "ADD",
  "target": "ORGANISATION_UNIT",
  "change": {"name":"My Unit", "shortName":"MyOU", "openingDate": "2020-01-01"}
}

Chcete-li navrhnout aktualizaci existujícího objektu metadat, odešlete datovou část JSON jako v níže uvedeném příkladu:

{
  "type": "UPDATE",
  "target": "ORGANISATION_UNIT",
  "targetId": "<id>",
  "change": [
    {"op": "replace", "path": "/name", "value": "New name"}
  ]
}

Chcete-li navrhnout odstranění existujícího objektu, odešlete datový obsah jako v posledním příkladu:

{
  "type": "REMOVE",
  "target": "ORGANISATION_UNIT",
  "targetId": "<id>"
}

V současnosti je podporován pouze cílový target typ ORGANISATION_UNIT.

Přijměte návrh na změnu metadat¶

Chcete-li přijmout otevřenou nabídku, použijte příkaz POST ve zdroji nabídky

POST /api/metadata/proposals/<uid>

Po úspěchu se stav návrhu změní na stav ACCEPTED. Jakmile je návrh přijat, již nelze odmítnout.

Should a proposal fail to apply it changes to status NEEDS_UPDATE. The reason field contains a summary of the failures when this information is available.

Odmítněte návrh změny metadat¶

Pokud návrh není zcela v pořádku a potřebuje úpravu, lze to označit tak, že se proti návrhu postavíte zasláním PATCH pro zdroj návrhu.

PATCH /api/metadata/proposals/<uid>

Volitelně lze k tomu přidat tělo ve formátu prostého textu, aby byl uveden důvod, proč byl návrh proti.

Oponovaný návrh musí být ve stavu PROPOSED a změní se na stav NEEDS_UPDATE.

Upravte návrh změny metadat¶

A proposal in state NEEDS_UPDATE needs to be adjusted before it can be accepted. To adjust the proposal a PUT request is made for the proposal's resource

PUT /api/metadata/proposals/<uid>

Such an adjustment can either be made without a body or with a JSON body containing an object with the updated change and targetId for the adjustment:

{
  "targetId": "<id>",
  "change": ...
}

Odmítněte návrh změny metadat¶

Chcete-li odmítnout otevřenou nabídku, použijte ve zdroji nabídky možnost DELETE

DELETE /api/metadata/proposals/<uid>

Tím se definitivně změní stav návrhu na REJECTED. V tomto návrhu nelze provádět žádné další změny. Je vedena jako dokumentace událostí.

Výpis návrhů změn metadat¶

Všechny návrhy mohou být uvedeny:

GET /api/metadata/proposals/

The result list can be filtered using the filter parameter. For example, to list only accepted proposals use:

GET /api/metadata/proposals?filter=status:eq:ACCEPTED

Podobně jako k zobrazení pouze otevřených návrhů použijte:

GET /api/metadata/proposals?filter=status:eq:PROPOSED

Filtry lze také použít na libovolné pole kromě pole change. Podporované operátory filtrů jsou popsány v Gist Metadata API. Patří sem také transformátory vlastností popsané pro Gist API.

Seznam dostupných polí je:

Zobrazení návrhů na změnu metadat¶

Individual change proposals can be viewed using

GET /api/metadata/proposals/<uid>

Parametr fields lze použít k zúžení polí zahrnutých pro zobrazený objekt. Například:

GET /api/metadata/proposals/<uid>?fields=id,type,status,change

Metadata Attribute Value Type and validations¶