Metadata¶

Esquemas de identificador¶

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.

The full set of identifier scheme object types available are listed below, using the name of the property to use in queries:

• 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.

Tabela: Scheme Values

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.

As an example, to specify CODE as the general id scheme and override with UID for organisation unit id scheme you can use these query parameters:

? 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

Navegando na API da Web¶

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:

An example of how these parameters can be used to get a full list of data element groups in XML response format is:

/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

Pode obter páginas específicas e tamanhos de página de objetos como este:

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

Pode desativar completamente a paginação assim:

/api/indicatorGroups.json?paging=false

Para ordenar o resultado com base em uma propriedade específica:

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

To order the result based on created datetime property first (descending order) and then by name property (ascending order):

/api/indicators.json?order=created:desc,name:asc

Pode encontrar um objecto com base em seu ID em todos os tipos de objecto por meio de o recurso identifiableObjects:

/api/identifiableObjects/<id>

Tradução¶

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).

API de tradução¶

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).

Exemplo de elemento de dados com matriz de tradução filtrada na localidade do usuário:

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

Exemplo de elemento de dados com traduções desativadas:

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

Exemplo de propriedade NAME para a localidade francesa:

{
  "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).

The status code will be 204 No Content if the data value was successfully saved or updated, or 404 Not Found if there was a validation error (e.g. more than one SHORT_NAME for the same locale).

Versões da API da web¶

The Web API is versioned starting from DHIS 2.25. The API versioning follows the DHIS2 major version numbering. As an example, the API version for DHIS 2.33 is 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

Se omitir a parte da versão da URL, o sistema usará a versão actual Versão da API. Como exemplo, para DHIS 2.25, ao omitir a parte da API, o sistema usará a versão 25 da API. Ao desenvolver clientes de API, é recomendado usar versões de API explícitas (em vez de omitir a API versão), pois isso protegerá o cliente de mudanças imprevistas na API.

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.

Filtro de objeto de metadados¶

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.

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.

Obtenha elementos de dados com propriedade id ID1 ou ID2:

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

Get data elements, ignoring case, with name property MyDataElement:

/api/dataElements?filter=name:ieq:mydataelement

Get all data elements which have a data set with 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]

Operadores lógicos¶

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

Filtro de token identificável¶

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

Também é possível especificar vários valores de filtragem.

Example: Get all data elements where ANC visit is found in any of the identifiable properties. The system returns all data elements where both tokens (ANC and visit) are found anywhere in identifiable properties.

/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

Filtro de campo de metadados¶

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.

** Exemplo **: Obtenha id ename no recurso de indicadores:

/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.

Example: Include all fields from data sets except organisation units:

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

** Exemplo **: inclui apenas id, nome e a coleção de unidades de organização de um conjunto de dados, mas exclui a id de unidades de organização:

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

** Exemplo **: Incluir propriedades que podem ser nomeadas de todos os indicadores:

/api/indicators.json?fields=:nameable

Transformadores de campo¶

Field transforms can be used to transform properties. The syntax is described below.

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

Isso renomeará a propriedade id para i e a propriedade name para n.

Multiple transformers can be applied to a single property by repeating the transformer operator:

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

The supported transformer operators are described in the table below.

Exemplos¶

Examples of transformer usage are found below.

Get the size of a collection:

/api/dataElements?fields=dataSets~size

Test if a collection is empty:

/api/dataElements?fields=dataSets~isEmpty

Test if a collection is not empty:

/api/dataElements?fields=dataSets~isNotEmpty

Rename properties:

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

Apply paging to a collection:

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

Get array with IDs of organisation units:

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

Get array with names of organisation units:

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

Key the dataElements array by the id field:

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

Key the dataElements array by the valueType field, since multiple hits this will results in arrays (of data elements):

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

Metadados criam, lêem, atualizam, excluem, validam¶

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

NOTE: When updating objects, all existing property values will be overwritten, even if the new value is null. Please use JSON Patch API in case you want do partial update to an object.

Criar / actualizar parâmetros¶

Os seguintes parâmetros de consulta de solicitação estão disponíveis em todos os terminais de metadados.

Criação e actualização de objectos¶

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

O mesmo conteúdo de uma carga útil 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

A specific example of posting the constant to the demo server:

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

Se tudo correr bem, verá uma saída semelhante a:

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

O processo será exatamente o mesmo para actualização, faz suas alterações para a carga JSON/XML, descubra o ID da constante e, em seguida, envie uma solicitação PUT para o endpoint incluindo o ID:

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

Excluindo objetos¶

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"

Uma exclusão bem-sucedida deve retornar o status HTTP 204 (sem conteúdo).

Adicionar e remover objetos em coleções¶

O recurso de coleções permite modificar coleções de objectos.

Adicionar ou remover objetos únicos¶

Para adicionar ou remover objectos de ou para uma coleção de objectos, pode usar o seguinte padronizar:

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

Deve usar o método POST para adicionar e o método DELETE para remover um objecto. Quando há uma relação muitos-para-muitos entre objectos, deve primeiro determinar qual objecto possui o relacionamento. Se não for claro qual objecto é este, tente a chamada nos dois sentidos para ver qual funciona.

Os componentes do padrão são:

• objecto de coleção: o tipo de objectos que possui a coleção que deseja modificar.

• ID do objecto de coleção: O identificador do objecto que possui o coleção que deseja modificar.

• nome da coleção: o nome da coleção que deseja modificar.

• ID do objecto: O identificador do objeto que deseja adicionar ou remover da coleção.

Como exemplo, para remover um elemento de dados com identificador IDB de um grupo de elementos de dados com identificador IDA, pode fazer um DELETE solicitar:

DELETE /api/dataElementGroups/IDA/dataElements/IDB

Para adicionar uma opção de categoria com identificador IDB a uma categoria com identificador IDA você pode fazer um POST solicitar:

POST /api/categories/IDA/categoryOptions/IDB

Adicionar ou remover vários objetos¶

Pode adicionar ou remover vários objectos de uma coleção em uma solicitação com uma carga como esta:

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

Usando essa carga, você pode adicionar, substituir ou excluir itens:

Adicionando itens:

POST /api/categories/IDA/categoryOptions

Substituindo itens:

PUT /api/categories/IDA/categoryOptions

Excluir Itens:

DELETE /api/categories/IDA/categoryOptions

Adicionar e remover objetos em uma única solicitação¶

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

POST /api/categories/IDA/categoryOptions

O formato da carga útil é:

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

Validando cargas úteis¶

DHIS 2 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.

Também pode validar sua carga manualmente enviando-a para o ponto final do esquema. Se quisesse validar a constante do create secção antes, enviaria assim:

POST /api/schemas/constant

Um exemplo simples (não validante) seria:

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

Which will yield the result:

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

Atualizações parciais¶

For our API endpoints that deal with metadata, we support partial updates (PATCH) using the JSON patch standard. The payload basically outlines a set of operation you want applied to a existing metadata object. For JSON patch details and examples, see jsonpatch.com. Three operators are supported: add, remove and replace.

Below is a few examples relevant to DHIS2. Note that any update to a payload should be thought of as a HTTP PUT operation, i.e. any mutation must result in a valid PUT metadata payload.

The default importReportMode for JSON patch is ERRORS_NOT_OWNER which implies that when updating any property which is not owned by that particular object (for example trying to add a indicator group directly to an indicator) you will get an error.

As per the JSON patch specification you must always use the mimetype application/json-patch+json when sending patches.

Exemplos¶

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¶

If path property is invalid or does not exist the patch service will return an error as below

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).

Exemplos¶

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

Exportação de metadados¶

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.

Exemplos de exportação de metadados¶

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

/api/metadata

Exportar todos os metadados ordenados por lastUpdated decrescente:

/api/metadata?defaultOrder=lastUpdated:desc

Exporte metadados apenas incluindo indicadores e grupos de indicadores:

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

Exportar id e displayName para todos os elementos de dados, ordenados por displayName:

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

Exporte elementos de dados e indicadores onde o nome começa com "ANC":

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

Exportação de metadados com dependências¶

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

Essas exportações podem então ser importadas usando / api / metadata.

Esses endpoints também oferecem suporte aos seguintes parâmetros:

Importação de metadados¶

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.

NOTE When updating objects, all property values will be overwritten even if the new values are null. Please use JSON Patch API in case you want do partial update to an object.

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",
    "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¶

The GeoJSON import is used to attach geometry data to organisation units.

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.

GeoJSON Bulk Data Import¶

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}

The summary that is returned directly for synchronous execution is available at

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

once the import is finished.

GeoJSON Bulk Data Deletion¶

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¶

The single import allows to update the geometry of a single organisation unit.

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.

Esquema¶

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>.

Para obter todos os esquemas disponíveis em XML:

GET /api/schemas.xml

Para obter todos os esquemas disponíveis em JSON:

GET /api/schemas.json

Para obter o esquema JSON para uma classe específica:

GET /api/schemas/dataElement.json

Ícones¶

DHIS2 includes a collection of icons that can be used to give visual context to metadata. There are two different kind of icons: - Default icons: they are pre-installed in the application and are not possible to modify nor delete. - Custom icons: can be created, updated and deleted at will.

Both of them be accessed through the icons resource.

GET /api/icons

This endpoint returns a list of information about the available default and custom icons. By default key, description, keywords and href will be included in response. But fields parameter can be used to change this behaviour.

{
  key: "mosquito_outline",
  description: "Mosquito outline",
  keywords: [
    "malaria",
    "mosquito",
    "dengue"
  ],
  "created": "2024-02-12T09:50:11.794",
  "lastUpdated": "2024-02-12T09:50:11.794",
  href: "<dhis server>/api/icons/mosquito_outline/icon.svg"
}

It's also possible to get a particular icon directly by filtering by its key, in the example below, the key is mosquito_outline.

GET /api/icons/mosquito_outline

Custom icon operations¶

A list of custom icons can be fetched retrieved certain request parameters

GET /api/icons?type=CUSTOM

Request parameters for pagination¶

Request parameters for ordering¶

Request parameter to filter responses¶

The endpoints accept a fields parameter which controls which fields will be returned in the JSON response. fields parameter accepts a comma separated list of field names. If nothing is specified, default fields will be used and those are

key,keywords,description,fileResourceUid,createdByUserUid,href

A custom icon resource can be downloaded by providing the icon key:

GET /api/icons/{key}/icon

Custom icons can be created, modified and deleted. To create a custom icon, use the resource below.

POST /api/icons

It expects a payload containing the icon key, description, list of keywords and the file resource uid to be linked to the data.

{
    "key": "iconKey",
    "description": "description",
    "keywords": ["keyword 1","keyword 2"],
    "fileResourceUid": "ARsqBjfB2cf"
}

Only custom icons can be updated using below resource.

PUT /api/icons

With the following payload, the icon's description and keywords would be updated.

{
    "key": "iconKey",
    "description": "new description",
    "keywords": ["new keyword 1", "new keyword 2"] 
}

Please notice that's also possible to just update one of the two. That means in case we would like to update the description while keeping the keywords, we would just need to provide the icon key and the descripton json field. Same would work the other way around, to update the keywords and leave the original description untouched.

Only custom icon can be deleted using below resource.

DELETE /api/icons/{icon_key}

Render type¶

Alguns tipos de metadados têm uma propriedade chamada renderType. O tipo de renderização é um mapa entre um device e um renderingType. Formulários pode usar esta informação como uma dica sobre como o objeto deve ser renderizado em um dispositivo específico. Por exemplo, um dispositivo móvel pode querer renderizar um elemento de dados de forma diferente de um computador desktop.

Atualmente, existem dois tipos diferentes de renderingTypes disponíveis:

1. Renderização de tipo de valor

2. Renderização da seção do estágio do programa

Existem também 2 tipos de dispositivos disponíveis:

1. MÓVEL

2. ÁREA DE TRABALHO

A tabela a seguir lista os metadados e os tipos de renderização disponíveis. A renderização do tipo de valor tem restrições de adição com base nos metadados configuração, que será mostrada em uma segunda tabela.

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.

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:

The renderingType can be set when creating or updating the metadata listed in the first table. An example payload for the rendering type for program stage section looks like this:

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

Para elemento de dados e atributo de entidade rastreada:

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

Object Style¶

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:

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:

• Elemento de dados

• Opção de categoria de elemento de dados

• Conjunto de dados

• Indicador

• Opção

• Programa

• Indicador de programa

• Seção do programa

• Estágio do Programa

• Seção de estágio do programa

• Relacionamento (Tracker)

• Atributo de entidade rastreada

• Tipo de entidade rastreada

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

Indicadores¶

Esta seção descreve indicadores e expressões de indicadores.

Indicadores agregados¶

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

/ api / indicadores

Indicators represent expressions which can be calculated and presented as a result. The indicator expressions are split into a numerator and denominator. The numerators and denominators are mathematical expressions which can contain references to data elements, other indicators, constants and organisation unit groups. The variables will be substituted with data values when used e.g. in reports. Variables which are allowed in expressions are described in the following table.

Within a Data element operand or an Aggregate data element, the following substitutions may be made:

The syntax looks like this:

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

Um exemplo correspondente tem a seguinte aparência:

# {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. *}

An example using a data element group:

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

An example using a category option, data element group, and a category option group:

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

An example using multiple category option groups:

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

An example using a program data element and a program attribute:

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

An example combining program indicators and aggregate indicators:

I {EMOt6Fwhs1n} * 1000 / # {WUg3MYWQ7pt}

An example using a reporting rate:

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

Another reporting rate example using actual data set reports and expected reports:

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

An example using an existing indicator:

N {Rigf2d2Zbjp} * # {P3jJH5Tu5VC.S34ULMcHMca}

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

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

Indicadores de programa¶

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.

The syntax looks like this:

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

Um exemplo correspondente tem a seguinte aparência:

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

Expressões¶

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 / expression / 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"
}

Merge indicators¶

The indicator merge endpoint allows you to merge a number of indicators (sources) into a target indicator.

Authorisation¶

The authority F_INDICATOR_MERGE is required to perform indicator merges.

Request¶

Merge indicators with a POST request:

POST /api/indicators/merge

The payload in JSON format looks like the following:

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

The JSON properties are described in the following table.

The merge operation will merge the source indicators into the target indicator. One or many source indicators can be specified. Only one target should be specified.

The merge operation will transfer all source indicator metadata associations to the target indicator. The following metadata get updated:

Validation¶

The following constraints and error codes apply.

Response¶

Success¶

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "INDICATOR",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "INDICATOR merge complete"
        }
    }
}

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source indicator must be specified",
                    "errorCode": "E1540",
                    "args": []
                },
                {
                    "message": "Target indicator does not exist: `abcdefg1221`",
                    "errorCode": "E1543",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "INDICATOR",
            "sourcesDeleted": [],
            "message": "INDICATOR merge has errors"
        }
    }
}

Indicator Types¶

Merge indicator types¶

The indicator type merge endpoint allows you to merge a number of indicator types into a target indicator type.

Authorisation¶

The authority F_INDICATOR_TYPE_MERGE is required to perform indicator type merges.

Request¶

Merge indicator types with a POST request:

POST /api/indicatorTypes/merge

The payload in JSON format looks like the following:

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

The JSON properties are described in the following table.

The merge operation will merge the source indicator types into the target indicator type. One or many source indicator types can be specified. Only one target should be specified.

The merge operation will transfer all of the indicator metadata associations to the source indicator types over to the target indicator type.

Validation¶

The following constraints and error codes apply.

Response¶

Success¶

Sample success response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "INDICATOR_TYPE",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "INDICATOR_TYPE merge complete"
        }
    }
}

Sample error response looks like:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source indicator type must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target indicator type does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "INDICATOR_TYPE",
            "sourcesDeleted": [],
            "message": "INDICATOR_TYPE merge has errors"
        }
    }
}

Unidades organizacionais¶

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

Obtenha uma lista de unidades organizacionais¶

Para obter uma lista de unidades de organização, você pode usar o seguinte recurso.

/ api / 33 / organisationUnits

Get organisation unit with sub-hierarchy¶

To get an organisation unit including organisation units in its sub-hierarchy you can use the following resource.

/ api / 33 / organisationUnits / {id}

Get organisation units by category option¶

Purpose-built endpoint to retrieve associations between category options and organisation units. This endpoint is the preferred way to retrieve program organisation unit associations.

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

responses will have the following format:

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

Category options that are accessible by all organisation units are returned with an empty array ([]) of organisation units.

Get organisation units by programs¶

Purpose-built endpoint to retrieve associations between programs and organisation units. This endpoint is the preferred way to retrieve program organisation unit associations.

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

responses will have the following format:

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

Programs which are accessible by all organisation units are returned with an empty array ([]) of organisation units.

Split organisation unit¶

The organisation unit split endpoint allows you to split organisation units into a number of target organisation units.

Request¶

Split organisation units with a POST request:

POST /api/organisationUnits/split

The payload in JSON format looks like the following:

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

The JSON properties are described in the following table.

The split operation will split the source org unit into the target org units. It is recommended to first create new target org units before performing the split, and at a minimum ensure that no aggregate data exists for the target org units. Any number of target org units can be specified.

The split operation will transfer all of the metadata associations of the source org unit over to the target org units. This includes data sets, programs, org unit groups, category options, users, visualizations, maps and event reports.

The operation will transfer all data records of the source org unit over to the org unit specified as the primary target, or if not specified, the first specified target org unit. This includes aggregate data values, data approval records, events, tracked entities and more.

Validation¶

The following constraints and error codes apply.

Merge organisation units¶

The organisation unit merge endpoint allows you to merge a number of organisation units into a target organisation unit.

Authorisation¶

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

Request¶

Merge organisation units with a POST request:

POST /api/organisationUnits/merge

The payload in JSON format looks like the following:

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

The JSON properties are described in the following table.

The merge operation will merge the source org units into the target org unit. It is recommended to first create a new target org unit before performing the merge, and at a minimum ensure that no aggregate data exists for the target org unit. Any number of source org units can be specified.

The merge operation will transfer all of the metadata associations of the source org units over to the target org unit. This includes data sets, programs, org unit groups, category options, users, visualizations, maps and event reports. The operation will also transfer all event and tracker data, such as events, enrollments, ownership history, program ownership and tracked entities, over to the target org unit.

The specified data value merge strategy defines how data values are handled. For strategy LAST_UPDATED, data values for all source org units are transferred over to the target org unit, and in situation where data values exist for the same parameters, the last updated or created data value will be used. This is done to avoid duplication of data. For strategy DISCARD, data values are not transferred over to the target org unit, and simply deleted. The specified data approval merge strategy defines how data approval records are handled, and follows the same logic as data values.

Validation¶

The following constraints and error codes apply.

Conjuntos de dados¶

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

/ api / 33 / dataSets

Para recuperar a versão de um conjunto de dados, você pode emitir uma solicitação 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> / versão

Data set notification template¶

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

GET /api/33/dataSetNotficationTemplates

Para recuperar o modelo de notificação de conjunto de dados, você pode emitir uma solicitação GET:

GET /api/33/dataSetNotficationTemplates/<uid>

Para adicionar um modelo de notificação de conjunto de dados, você pode emitir uma solicitação POST:

POST / api / 33 / dataSetNotficationTemplates

Para excluir o modelo de notificação de conjunto de dados, você pode emitir uma solicitação DELETE:

DELETE / api / 33 / dataSetNotficationTemplates / <uid>

A amostra de carga útil JSON é fornecida abaixo:

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

Níveis de unidade organizacional preenchidos¶

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
  }]
}

Preditores¶

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

Criação de um preditor¶

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

POST /api/predictors

Uma amostra de carga tem a seguinte aparência:

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

Predictor expressions¶

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:

Gerando valores previstos¶

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

Regras do programa¶

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.

Modelo de regra de programa¶

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.

Detalhes do modelo de regra do programa¶

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

Detalhes do modelo de ação da regra do programa¶

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

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.

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

Detalhes do modelo de variável de regra de programa¶

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

Criação de regras de programa¶

• To perform crud operations, programRules resource is available in API.

To retrieve list of programRules you can do a GET request like this:

/api/programRules

To retrieve single programRule you can do a GET request like this:

/api/programRules/<program_rule_uid>

To save/add single programRule you can do a POST request like this:

/api/programRules/<program_rule_uid>

To update single programRule you can do a PUT request like this:

/api/programRules/<program_rule_uid>

To delete single programRule you can do a DELETE request like this:

/api/programRules/<program_rule_uid>

To retrieve description of programRule condition you can use POST and provide condition string in the POST body.

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

Formulários¶

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.

Para recuperar o formulário de um conjunto de dados, você pode fazer uma solicitação GET como esta:

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

To retrieve the form for the data set with identifier "BfMAe6Itzgt" in XML:

/ api / dataSets / BfMAe6Itzgt / form

Para recuperar o formulário incluindo metadados em 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

Documentos¶

As referências aos arquivos podem ser armazenadas com o recurso de documento.

Uma solicitação GET para o endpoint de documentos retornará todos os documentos:

/ api / documents

Uma solicitação POST para o endpoint de documentos criará um novo documento:

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

Importação de metadados CSV¶

DHIS2 oferece suporte à importação de metadados no formato CSV, como elementos de dados, unidades de organização e regras de validação. As propriedades dos vários objetos de metadados são identificadas com base na ordem / índice da coluna (veja detalhes abaixo). Você pode omitir propriedades / colunas de objeto não obrigatórias, mas como a ordem das colunas é significativa, uma coluna vazia deve ser incluída. Em outras palavras, se você quiser especificar propriedades / colunas que aparecem no final da ordem das colunas, mas não especificar certas colunas que aparecem no início da ordem, você pode incluir colunas vazias / em branco para elas.

A primeira linha do arquivo CSV é considerada um cabeçalho e é ignorada durante a importação. O caractere comma deve ser usado como um delimitador de texto. O texto que contém vírgulas deve ser colocado entre paspas duplas.

Para fazer upload de metadados no formato CSV, você pode fazer uma solicitação POST para o endpoint de metadados:

POST / api / metadata? ClassKey = CLASS-KEY

Os seguintes tipos de objeto são suportados. O parâmetro de consulta classKey é obrigatório e pode ser encontrado próximo a cada tipo de objeto na tabela abaixo.

Tip

If using curl, the --data-binary option should be used as it preserves line breaks and newlines, which is essential for CSV data.

Por exemplo, para fazer upload de um arquivo de elementos de dados no formato CSV com curl, você pode usar o seguinte comando:

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

Os formatos dos tipos de objetos atualmente suportados para importação de CSV estão listados nas seções a seguir.

Elementos de dados¶

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

nome, uid, código, nome curto, descrição
"Mulheres participaram do treinamento de desenvolvimento de habilidades" ,, "D0001", "Mulheres participaram do treinamento"
"Mulheres participaram de organizações comunitárias" ,, "D0002", "Mulheres participaram de organizações"

Unidades organizacionais¶

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

nome, uid, código, pai
"Província oeste" ,, "WESTP", "ImspTQPwCqd"
"Província leste" ,, "EASTP", "ImspTQPwCqd"

Regras de validação¶

Conjuntos de opções¶

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
"Cor" ,, "COR", "Azul" ,, "AZUL"
"Cor" ,, "COR", "Verde" ,, "VERDE"
"Cor" ,, "COR", "Amarelo" ,, "AMARELO"
"Sexo" ,,, "Masculino" ,, "MASCULINO"
"Sexo" ,,, "Fêmea" ,, "FÊMEA"
"Sexo" ,,, "Desconhecido" ,, "DESCONHECIDO"
"Resultado" ,,, "Alto" ,, "ALTO"
"Resultado" ,,, "Médio" ,, "MÉDIO"
"Resultado" ,,, "Baixo" ,, "BAIXO"
"Impacto", "cJ82jd8sd32", "IMPACTO", "Ótimo" ,, "EXCELENTE"
"Impacto", "cJ82jd8sd32", "IMPACTO", "Médio" ,, "MÉDIO"
"Impacto", "cJ82jd8sd32", "IMPACTO", "Ruim" ,, "POBRE"

Grupo de opções¶

Amostra de carga útil do OptionGroup CSV

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

Conjunto de Grupo de Opções¶

Amostra de carga útil de OptionGroupSet CSV

`csv nome, uid, código, descrição, dimensão de dados, opçõesetuid optiongroupsetA ,,,,, xmRubJIhmaK optiongroupsetB ,,,, false, QYDAByFgTr1 ` Para adicionar OptionGroups a um OptionGroupSet importado, siga as etapas de importação de associação de coleção

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

Associação de coleção¶

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

• Grupo de Unidade Organizacional - Unidade Organizacional

• Grupo de elemento de dados - Elemento de dados

• Grupo Indicador - Indicador

• Conjunto de grupo de opções - Grupo de opções

O formato CSV para essas importações é o mesmo

Category Option Group¶

Outros objetos¶

Um exemplo de opções de categoria se parece com isto:

nome, uid, código, nome curto
"Masculino" ,, "MASCULINO"
"Feminino" ,, "FEMALE"

Objetos excluídos¶

The deleted objects resource provides a log of metadata objects being deleted.

/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.

Obtenha objetos excluídos de elementos de tipo de dados:

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

Favoritos¶

Certain types of metadata objects can be marked as favorites for the currently logged in user. This applies currently for dashboards.

/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.

Assinaturas¶

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

Note

The EventChart and EventReport objects are deprecated. Use EventVisualization instead.

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

Veja o exemplo a seguir:

/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

Veja o exemplo a seguir:

/api/visualizations/DkPKc1EUmC2/subscribed

To subscribe/de-subscribe to an object you perform a POST/DELETE request (no content type required):

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

Recursos de arquivo¶

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

The contents of file resources are not directly accessible but are referenced from other objects (such as data values) to store binary content of virtually unlimited size.

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.

Restrições de recursos de arquivo¶

• File resources must be referenced (assigned) from another object 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.

• The ID returned by the initial creation of the file resource is not retrievable from any other location unless the file resource has been referenced (in which the ID will be stored as the reference), so losing it will require the POST request to be repeated and a new object to be created. The orphaned file resource will be cleaned up automatically.

• File resource objects are immutable, meaning modification is not allowed and requires creating a completely new resource instead.

File resource blocklist¶

Certain types of files are blocked from being uploaded for security reasons.

The following content types are blocked.

The following file extensions are blocked.

Controle de versão de metadados¶

This section explains the metadata versioning APIs.

• /api/metadata/version: This endpoint will return the current metadata version of the system on which it is invoked.

Obtenha exemplos de versão de metadados¶

** Exemplo: ** Obtenha a versão atual dos metadados deste sistema

Solicitação:

/ api / metadata / version

Resposta:

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

** Exemplo: ** Obtenha os detalhes da versão com o nome "Versão_2"

Solicitação:

/api/metadata/version?versionName=Version_2

Resposta:

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

Obtenha a lista de todas as versões de metadados¶

** Exemplo: ** Obtenha a lista de todas as versões deste sistema

Solicitação:

/api/metadata/version/history

Resposta:

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

** Exemplo: ** Obtenha a lista de todas as versões neste sistema criadas após "Versão_2"

Solicitação:

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

Resposta:

{
  "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: This endpoint will create the metadata version for the version type as specified in the parameter.

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.

Criar versão de metadados¶

** Exemplo: ** Criar versão de metadados do tipo BEST_EFFORT

Solicitação:

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

Resposta:

{
  "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: This endpoint will download the actual metadata specific to the version name passed as path parameter in a compressed format (gzipped).

Baixar metadados da versão¶

** Exemplo: ** Obtenha os metadados reais para a "Versão 5"

Solicitação:

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

Resposta:

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

Metadata synchronization¶

This section explains the Metadata Synchronization API available starting 2.24

• /api/metadata/sync: This endpoint performs metadata sync of the version name passed in the query parameter by downloading and importing the specified version from the remote server as defined in the settings app.

• This API should be used with utmost care. Please note that there is an alternate way to achieve sync in a completely automated manner by leveraging the Metadata Sync Task from the "Data Administration" 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 versions which have failed from the metadata sync scheduler. Due to 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. So the local instance will not have the metadata versions between Version_12 and Version_15. You need to manually sync the missing versions using these endpoints only.

Versão de metadados de sincronização¶

** Exemplo: ** Sincronizar versão_6 do sistema central para este sistema

Solicitação:

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

Repositório de metadados¶

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.

To retrieve an index over available metadata packages you can issue a GET request to the metadataRepo resource:

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

Um exemplo de comando curl se parece com este:

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

Note

The supplied URL will be checked against the config property system.remote_servers_allowed in the dhis.conf file. If the base URL is not one of the configured servers allowed then the operation will not be allowed. See failure example below.
Some examples where the config set is system.remote_servers_allowed=https://server1.org/,https://server2.org/ - supply https://server1.org/path/to/resource -> this will be accepted - supply https://server2.org/resource/path -> this will be accepted - supply https://oldserver.org/resource/path -> this will be rejected

Sample failure response in JSON format.

 {
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Provided URL is not in the remote servers allowed list",
  "errorCode": "E1004"
}

Reference to created by user¶

Each object created in DHIS2 will have a property named user which is linked to User who created the object.

From version 2.36 we have changed the name of this property to createdBy to avoid confusion.

However, in order to keep the backwards compability, the legacy user property is still included in the payload and works normally as before.

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

Metadata proposal workflow¶

The metadata proposal workflow endpoint allows for a workflow of proposing and accepting changes to metadata.

/api/metadata/proposals

Propose a metadata change¶

A proposal always targets a single metadata object using:

POST /api/metadata/proposals

Depending on the payload the proposal could:

• Add a new metadata object.
• Update an existing metadata object references by ID.
• Remove an existing metadata object referenced by ID.

To propose adding a new metadata object send a JSON payload like the following:

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

To propose updating an existing metadata object send a JSON payload like in the below example:

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

To propose the removal of an existing object send a payload like in the last example:

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

Only target type ORGANISATION_UNIT is supported currently.

Accept a metadata change proposal¶

To accept an open proposal use POST on the proposal resource

POST /api/metadata/proposals/<uid>

When successful the status of the proposal changes to status ACCEPTED. Once accepted the proposal can no longer be rejected.

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.

Oppose a metadata change proposal¶

If a proposal isn't quite right and needs adjustment this can be indicated by opposing the proposal by sending a PATCH for the proposal resource

PATCH /api/metadata/proposals/<uid>

Optionally a plain text body can be added to this to give a reason why the proposal got opposed.

A opposed proposal must be in state PROPOSED and will change to state NEEDS_UPDATE.

Adjust a metadata change proposal¶

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": ...
}

Reject a metadata change proposal¶

To reject an open proposal use DELETE on the proposal resource

DELETE /api/metadata/proposals/<uid>

This changes the status of the proposal conclusively to REJECTED. No further changes can be made to this proposal. It is kept as a documentation of the events.

List metadata change proposals¶

All proposals can be listed:

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

Similarly to only show open proposals use:

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

Filters can also be applied to any field except change. Supported filter operators are those described in the Gist Metadata API. This also includes property transformers described for Gist API.

List of available fields are:

Viewing metadata change proposals¶

Individual change proposals can be viewed using

GET /api/metadata/proposals/<uid>

The fields parameter can be used to narrow the fields included for the shown object. For example:

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

Metadata Attribute Value Type and validations¶

Copy Program¶

Introdução¶

A user will often want to create many Programs which share many of the same characteristics, and instead of having to create a new Program from scratch, it is efficient and beneficial to copy an existing Program and make modifications to it.
A template Program could theoretically be setup as a base to copy from, which may help with the consistency of Program setups also.

API info¶

Endpoint¶

POST /api/programs/{uid}/copy

Example with a Program with a UID of Program123a

POST /api/programs/Program123a/copy

Successful response will include the new Program UID and will look like this:

{
    "httpStatus": "Created",
    "httpStatusCode": 201,
    "status": "OK",
    "message": "Program created: 'Program456b'"
}

The response will also contain a Location header with a link to the newly-created Program. e.g. when run locally the Location value would be http://localhost:9090/api/programs/Program456b

Copy options¶

The API does allow the optional supplying of a custom prefix, which will be prefixed to the following properties.

In this example when a custom prefix is supplied, an original Program with a name of My Simple Program would be copied to a new Program with the name my prefix My Simple Program

If no copy options are sent in the API call then the default Copy of prefix will be used for the above properties.
To send a custom prefix just add a HTTP request param prefix like so:

 POST /api/programs/{uid}/copy?prefix=my prefix

Note

The database does have limits for the number of characters allowed for properties. At the time of writing these limits are noted in the table below. Bear these in mind.

If a property has exceeded its character limit, then an error will be returned like so:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "ERROR",
    "message": "ERROR: value too long for type character varying(230)",
    "errorCode": "E1004"
}

If trying to copy a Program that is not found, a response like this will be returned:

{
    "httpStatus": "Not Found",
    "httpStatusCode": 404,
    "status": "ERROR",
    "message": "Program with id {uid} could not be found.",
    "errorCode": "E1005"
}