Přeskočit obsah
For the complete DHIS2 documentation index, see llms.txt.
Použití API

Vizualizace

Ovládací panel

The dashboard is designed to give you an overview of multiple analytical items like maps, charts, pivot tables and reports which together can provide a comprehensive overview of your data. Dashboards are available in the Web API through the dashboards resource. A dashboard contains a list of dashboard items. An item can represent a single resource, like a chart, map or report table, or represent a list of links to analytical resources, like reports, resources, tabular reports and users. A dashboard item can contain up to eight links. Typically, a dashboard client could choose to visualize the single-object items directly in a user interface, while rendering the multi-object items as clickable links.

/api/dashboards

Procházení ovládacích panelů

To get a list of your dashboards with basic information including identifier, name and link in JSON format you can make a GET request to the following URL:

/api/dashboards.json

The dashboards resource will provide a list of dashboards. Remember that the dashboard object is shared so the list will be affected by the currently authenticated user. You can retrieve more information about a specific dashboard by following its link, similar to this:

/api/dashboards/vQFhmLJU5sK.json

A dashboard contains information like name and creation date and an array of dashboard items. The response in JSON format will look similar to this response (certain information has been removed for the sake of brevity).

{
  "lastUpdated" : "2013-10-15T18:17:34.084+0000",
  "id": "vQFhmLJU5sK",
  "created": "2013-09-08T20:55:58.060+0000",
  "name": "Mother and Child Health",
  "href": "https://play.dhis2.org/demo/api/dashboards/vQFhmLJU5sK",
  "publicAccess": "--------",
  "restrictFilters": false,
  "externalAccess": false,
  "itemCount": 17,
  "displayName": "Mother and Child Health",
  "access": {
    "update": true,
    "externalize": true,
    "delete": true,
    "write": true,
    "read": true,
    "manage": true
  },
  "user": {
    "id": "xE7jOejl9FI",
    "name": "John Traore",
    "created": "2013-04-18T15:15:08.407+0000",
    "lastUpdated": "2014-12-05T03:50:04.148+0000",
    "href": "https://play.dhis2.org/demo/api/users/xE7jOejl9FI"
  },
  "dashboardItems": [{
    "id": "bu1IAnPFa9H",
    "created": "2013-09-09T12:12:58.095+0000",
    "lastUpdated": "2013-09-09T12:12:58.095+0000"
    }, {
    "id": "ppFEJmWWDa1",
    "created": "2013-09-10T13:57:02.480+0000",
    "lastUpdated": "2013-09-10T13:57:02.480+0000"
  }],
  "layout": {
    "spacing": {
      "column": 5,
      "row": 5
    },
    "columns": [{
      "index": 0,
      "span": 2
    }, {
      "index": 1,
      "span": 1
    }]
  },
  "userGroupAccesses": []
}

A more tailored response can be obtained by specifying specific fields in the request. An example is provided below, which would return more detailed information about each object on a users dashboard.

/api/dashboards/vQFhmLJU5sK/?fields=:all,dashboardItems[:all]

Hledání ovládacích panelů

When a user is building a dashboard it is convenient to be able to search for various analytical resources using the /dashboards/q or /dashboards/search resources. These resources let you search for matches on the name property of the following objects: visualizations, eventVisualizations maps, users, reports and resources. You can do a search by making a GET request on the following resource URL pattern, where my-query should be replaced by the preferred search query:

/api/dashboards/q/my-query.json
/api/dashboards/search?q=my-query

Například tento dotaz:

/api/dashboards/q/ma?count=6&maxCount=20&max=REPORT&max=MAP
/api/dashboards/search?q=ma?count=6&maxCount=20&max=REPORT&max=MAP

Vyhledá následující:

  • Název analytického objektu obsahuje řetězec „ma“
  • Vraťte až 6 z každého typu
  • U typů REPORT a MAP vrátí až 20 položek
dashboards/q and dashboards/search query parameters
Parametr dotazu Popis Typ Výchozí
počet Počet položek každého typu, které se mají vrátit Kladné celé číslo 6
maxCount Počet položek maximálních typů, které se mají vrátit Kladné celé číslo 25
max Typ, pro který se má vrátit maxCount String [MAP|USER|REPORT|RESOURCE|VISUALIZATION#124;EVENT_VISUALIZATION,EVENT_CHART,EVENT_REPORT] Nedostupné

Podporovány jsou formáty odpovědí JSON a XML. Odpověď ve formátu JSON bude obsahovat odkazy na odpovídající zdroje a počty nalezených shod celkem a pro každý typ zdroje. Bude vypadat podobně:

{
  "visualizations": [{
    "name": "ANC: ANC 3 Visits Cumulative Numbers",
    "id": "arf9OiyV7df",
    "type": "LINE"
  }, {
    "name": "ANC: 1st and 2rd trends Monthly",
    "id": "jkf6OiyV7el",
    "type": "PIVOT_TABLE"
  }],
  "eventVisualizations": [{
    "name": "Inpatient: Cases 5 to 15 years this year (case)",
    "id": "TIuOzZ0ID0V",
    "type": "LINE_LIST"
  }, {
    "name": "Inpatient: Cases last quarter (case)",
    "id": "R4wAb2yMLik",
    "type": "LINE_LIST"
  }],
  "maps": [{
    "name": "ANC: 1st visit at facility (fixed) 2013",
    "id": "YOEGBvxjAY0"
  }, {
    "name": "ANC: 3rd visit coverage 2014 by district",
    "id": "ytkZY3ChM6J"
  }],
  "reports": [{
    "name": "ANC: 1st Visit Cumulative Chart",
    "id": "Kvg1AhYHM8Q"
  }, {
    "name": "ANC: Coverages This Year",
    "id": "qYVNH1wkZR0"
  }],
  "searchCount": 8,
  "visualizationCount": 2,
  "eventVisualizationCount": 2,
  "mapCount": 2,
  "reportCount": 2,
  "userCount": 0,
  "eventReports": 0,
  "eventCharts" :0,
  "resourceCount": 0
}

Vytváření, aktualizace a odstraňování ovládacích panelů

Creating, updating and deleting dashboards follow standard REST semantics. In order to create a new dashboard you can make a POST request to the /api/dashboards resource. From a consumer perspective it might be convenient to first create a dashboard and later add items to it. JSON and XML formats are supported for the request payload. To create a dashboard with the name "My dashboard" you can use a payload in JSON like this:

{
  "name": "Můj ovládací panel"
}

To update, e.g. rename, a dashboard, you can make a PUT request with a similar request payload the same api/dashboards resource.

To remove a dashboard, you can make a DELETE request to the specific dashboard resource similar to this:

/api/dashboards/vQFhmLJU5sK

Přidávání, přesouvání a odebírání položek a obsahu ovládacích panelů

In order to add dashboard items a consumer can use the /api/dashboards/<dashboard-id>/items/content resource, where <dashboard-id> should be replaced by the relevant dashboard identifier. The request must use the POST method. The URL syntax and parameters are described in detail in the following table.

Tabulka: Parametry obsahu položek

Parametr dotazu Popis Možnosti
typ Typ zdroje, který má být reprezentován položkou ovládacího panelu vizualizace | mapa | eventVizualizace | uživatelé | zprávy | zdroje | aplikace
id Identifikátor zdroje, který má být reprezentován položkou ovládacího panelu Identifikátor zdroje

A POST request URL for adding a visualization to a specific dashboard could look like this, where the last id query parameter value is the chart resource identifier:

/api/dashboards/vQFhmLJU5sK/items/content?type=visualization&id=LW0O27b7TdD

When adding resource of type map, visualization and app, the API will create and add a new item to the dashboard. When adding a resource of type users, reports and resources, the API will try to add the resource to an existing dashboard item of the same type. If no item of same type or no item of same type with less than eight resources associated with it exists, the API will create a new dashboard item and add the resource to it.

In order to move a dashboard item to a new position within the list of items in a dashboard, a consumer can make a POST request to the following resource URL, where <dashboard-id> should be replaced by the identifier of the dashboard, <item-id> should be replaced by the identifier of the dashboard item and <index> should be replaced by the new position of the item in the dashboard, where the index is zero-based:

/api/dashboards/<dashboard-id>/items/<item-id>/position/<index>

To remove a dashboard item completely from a specific dashboard a consumer can make a DELETE request to the below resource URL, where <dashboard-id> should be replaced by the identifier of the dashboard and <item-id> should be replaced by the identifier of the dashboard item. The dashboard item identifiers can be retrieved through a GET request to the dashboard resource URL.

/api/dashboards/<dashboard-id>/items/<item-id>

To remove a specific content resource within a dashboard item a consumer can make a DELETE request to the below resource URL, where <content-resource-id> should be replaced by the identifier of a resource associated with the dashboard item; e.g. the identifier of a report or a user. For instance, this can be used to remove a single report from a dashboard item of type reports, as opposed to removing the dashboard item completely:

/api/dashboards/<dashboard-id>/items/<item-id>/content/<content-resource-id>

Defining a dashboard layout

Pro každý ovládací panel můžete definovat a uložit rozvržení. Následující objekt je zodpovědný za udržení tohoto nastavení.

{
  "layout": {
    "spacing": {
      "column": 5,
      "row": 5
    },
    "columns": [{
      "index": 0,
      "span": 2
    }, {
      "index": 1,
      "span": 1
    }]
  }
}

Definice rozvržení bude použita pro všechny položky ovládacího panelu související s daným řídicím panelem, přičemž budou respektovány atributy rozvržení, jako jsou mezery, sloupce, rozpětí a tak dále. Níže naleznete stručný popis každého atributu.

Tabulka: Atributy rozvržení

Atribut Popis Typ
layout Toto je kořenový objekt Objekt
spacing Definuje mezery pro konkrétní součásti rozvržení. V současné době podporuje sloupce a řádky. Objekt
sloupce Ukládá specifické parametry související se sloupci (v tuto chvíli index a rozsah) Pole objektů

Vizualizace

Vizualizace API je navržena tak, aby pomohla klientům komunikovat s grafy a kontingenčními / reportovacími tabulkami. Koncové body tohoto API používá aplikace Vizualizace dat, která umožňuje vytváření, konfiguraci a správu grafů a kontingenčních tabulek na základě definic klienta. Hlavní myšlenkou je umožnit klientům a uživatelům mít jedinečné a centralizované API poskytující všechny typy grafů a kontingenčních tabulek, jakož i specifické parametry a konfiguraci pro každý typ vizualizace.

Toto rozhraní API bylo zavedeno s cílem sjednotit rozhraní API charts a reportTables a zcela je nahradit rozhraním vizualizations API.

A Visualization object is composed of many attributes (some of them related to charts and others related to pivot tables), but the most important ones responsible to reflect the core information of the object are: "id", "name", "type", "dataDimensionItems", "columns", "rows" and "filters".

The root endpoint of the API is /api/visualizations, and the list of current attributes and elements are described in the table below.

Tabulka: Atributy vizualizace

Pole Popis
id Jedinečný identifikátor.
code Vlastní kód k identifikaci vizualizace.
název Název vizualizace
typ Typ vizualizace. Platné typy jsou: COLUMN, STACKED_COLUMN, BAR, STACKED_BAR, LINE, AREA, PIE, RADAR, GAUGE, YEAR_OVER_YEAR_LINE YEAR_OVER_YEAR_COLUMN, SINGLE_VALUE, PIVOT_TABLE.
title Vlastní nadpis.
subtitle Vlastní podnadpis.
popis Definuje vlastní popis pro vizualizaci.
created Datum/čas vytvoření vizualizace.
startDate Počáteční datum použité při filtrování.
endDate Datum ukončení použité během filtrování.
sortOrder Pořadí řazení této vizualizace. Celočíselná hodnota.
user Objekt představující tvůrce vizualizace.
publicAccess Nastavuje oprávnění pro veřejný přístup.
displayDensity Hustota zobrazení textu.
fontSize Velikost písma textu.
fontStyle Vlastní styly písma pro: visualizationTitle, visualizationSubtitle, horizontalAxisTitle, verticalAxisTitle, targetLineLabel, baseLineLabel, seriesAxisLabel, categoryAxisLabel, legenda.
relativePeriods Objekt představující relativní období použitá v analytickém dotazu.
legendSet Objekt představující definice pro legendu.
legendDisplayStyle Styl zobrazení legendy. Může to být: FILL nebo TEXT.
legendDisplayStrategy Styl zobrazení legendy. Může to být: FIXED nebo BY_DATA_ITEM.
aggregationType Určuje, jak se agregují hodnoty v kontingenční tabulce. Platné možnosti: SUM, AVERAGE, AVERAGE_SUM_ORG_UNIT, LAST, LAST_AVERAGE_ORG_UNIT, FIRST, FIRST_AVERAGE_ORG_UNIT, COUNT, STDDEV, VARIANCE, MIN, MAX, NONE, CUSTOM nebo DEFAULT.
regressionType Platný typ regrese: NONE, LINEAR, POLYNOMIAL nebo LOESS.
targetLineValue Cílová čára grafu. Přijímá typ Double.
targetLineLabel Štítek cílové čáry grafu.
rangeAxisLabel Popis / název svislé osy (y) grafu.
domainAxisLabel Popis / název vodorovné osy (x) grafu.
rangeAxisMaxValue Maximální hodnota osy grafu. Hodnoty mimo rozsah se nezobrazí.
rangeAxisMinValue Minimální hodnota osy grafu. Hodnoty mimo rozsah se nezobrazí.
rangeAxisSteps Počet kroků osy mezi minimální a maximální hodnotou.
rangeAxisDecimals Počet desetinných míst pro hodnoty os.
baseLineValue Základní hodnota grafu.
baseLineLabel Popisek základní linie grafu.
digitGroupSeparator Oddělovač skupiny číslic. Platné hodnoty: COMMA, SPACE nebo NONE.
topLimit Horní limit nastavený pro kontingenční tabulku.
measureCriteria Popisuje kritéria použitá pro toto opatření.
percentStackedValues Používá složené hodnoty nebo ne. Pravděpodobnější použití pro grafiku / grafy. Booleovská hodnota.
noSpaceBetweenColumns Zobrazit / skrýt mezeru mezi sloupci. Booleovská hodnota.
regression Označuje, zda vizualizace obsahuje regresní sloupce. S větší pravděpodobností bude použitelný pro Pivot / Report. Booleovská hodnota.
externalAccess Označuje, zda je vizualizace dostupná jako externí pouze pro čtení. Platí pouze v případě, že není přihlášen žádný uživatel. Booleovská hodnota.
userOrganisationUnit Označuje, zda má uživatel organizační jednotku. Booleovská hodnota.
userOrganisationUnitChildren Označuje, zda má uživatel podřízenou organizační jednotku. Booleovská hodnota.
userOrganisationUnitGrandChildren Označuje, zda má uživatel velkou podřízenou organizační jednotku . Booleovská hodnota.
reportingParams Objekt používaný k definování booleovských atributů souvisejících s vytvářením přehledů.
rowTotals Zobrazí (nebo ne) součty řádků. Booleovská hodnota.
colTotals Zobrazí (nebo ne) součty sloupců. Booleovská hodnota.
rowSubTotals Zobrazí (nebo ne) řádkové mezisoučty. Booleovská hodnota.
colSubTotals Zobrazí (nebo ne) mezisoučty sloupců. Booleovská hodnota.
cumulativeValues Označuje, zda vizualizace používá kumulativní hodnoty. Booleovská hodnota.
hideEmptyColumns Označuje, zda se mají skrýt sloupce bez datových hodnot. Booleovská hodnota.
hideEmptyRows Označuje, zda se mají skrýt řádky bez datových hodnot. Booleovská hodnota.
fixColumnHeaders Udržuje záhlaví sloupců v kontingenční tabulce pevná (nebo ne). Booleovská hodnota.
fixRowHeaders Udržuje záhlaví řádků v kontingenční tabulce pevná (nebo ne). Booleovská hodnota.
completedOnly Flag used in analytics requests. If true, only completed events/enrollments will be taken into consideration. Boolean value.
skipRounding Použít nebo nezaokrouhlit. Booleovská hodnota.
showDimensionLabels Zobrazuje štítky rozměrů nebo ne. Booleovská hodnota.
hideTitle Skryje název nebo ne. Booleovská hodnota.
hideSubtitle Skryje titulky nebo ne. Booleovská hodnota.
hideLegend Zobrazit / skrýt legendu. Velmi pravděpodobně bude používán grafy. Booleovská hodnota.
showHierarchy Zobrazuje (nebo ne) názvy hierarchie organizačních jednotek. Booleovská hodnota.
showData Používá se v grafech ke skrytí nebo neskrytí dat / hodnot v rámci vykresleného modelu. Booleovská hodnota.
lastUpdatedBy Objekt, který představuje uživatele, který použil poslední změny ve vizualizaci.
lastUpdated Datum / čas poslední změny vizualizace.
favorites Seznam ID uživatelů, kteří označili tento objekt jako oblíbený.
subscribers Seznam ID uživatelů, kteří se přihlásili k odběru této vizualizace.
translations Sada dostupných překladů objektů, obvykle filtrovaných podle národního prostředí.
outlierAnalysis Objekt odpovědný za zachování nastavení souvisejících s analýzou odlehlých hodnot. Interní atribut 'outlierMethod' podporuje: IQR, STANDARD_Z_SCORE, MODIFIED_Z_SCORE. „Metoda normalizace“ prozatím přijímá pouze Y_RESIDUALS_LINEAR.
seriesKey Možnosti stylingu a zda se má či nemá zobrazit klíč řady.
legenda Možnosti a zda použít barvy legendy na řadu grafů.

Načítání vizualizací

Chcete-li načíst seznam všech existujících vizualizací, ve formátu JSON, s některými základními informacemi (včetně identifikátoru, názvu a stránkování), můžete na níže uvedenou adresu URL vytvořit požadavek GET. Měli byste vidět seznam všech veřejných / sdílených vizualizací a vašich soukromých.

GET /api/visualizations.json

Pokud chcete načíst definici JSON konkrétní vizualizace, můžete do adresy URL přidat její příslušný identifikátor:

GET /api/visualizations/hQxZGXqnLS9.json

Následující reprezentace je příkladem odpovědi ve formátu JSON (pro stručnost byly některé informace odstraněny). Pro kompletní schéma použijte GET /api/schemas/visualization.

{
  "lastUpdated": "2020-02-06T11:57:09.678",
  "href": "http://my-domain/dhis/api/visualizations/hQxZGXqnLS9",
  "id": "hQxZGXqnLS9",
  "created": "2017-05-19T17:22:00.785",
  "name": "ANC: ANC 1st visits last 12 months cumulative values",
  "publicAccess": "rw------",
  "userOrganisationUnitChildren": false,
  "type": "LINE",
  "access": {},
  "reportingParams": {
    "parentOrganisationUnit": false,
    "reportingPeriod": false,
    "organisationUnit": false,
    "grandParentOrganisationUnit": false
  },
  "dataElementGroupSetDimensions": [],
  "attributeDimensions": [],
  "yearlySeries": [],
  "axes": [
    {
      "index": 0,
      "type": "RANGE",
      "title": {
        "textMode": "CUSTOM",
        "text": "Any Title"
      }
    }
  ],
  "filterDimensions": [
    "dx"
  ],
  "columns": [
    {
      "id": "ou"
    }
  ],
  "dataElementDimensions": [],
  "categoryDimensions": [],
  "rowDimensions": [
    "pe"
  ],
  "columnDimensions": [
    "ou"
  ],
  "dataDimensionItems": [
    {
      "dataDimensionItemType": "DATA_ELEMENT",
      "dataElement": {
        "id": "fbfJHSPpUQD"
      }
    }
  ],
  "filters": [
    {
      "id": "dx"
    }
  ],
  "rows": [
    {
      "id": "pe"
    }
  ]
}
Více přizpůsobené odpovědi lze získat zadáním polí, která chcete extrahovat, do adresy URL. Např.: 
GET /api/visualizations/hQxZGXqnLS9.json?fields=interpretations

vrátí se

{
  "interpretations": [
    {
      "id": "Lfr8I2RPU0C"
    },
    {
      "id": "JuwgdJlJPGb"
    },
    {
      "id": "WAoU2rSpyZp"
    }
  ]
}

Jak je vidět, výše uvedené ZÍSKAT vrátí pouze interpretace související s daným identifikátorem (v tomto případě hQxZGXqnLS9).

Vytváření, aktualizace a odstraňování vizualizací

These operations follow the standard REST semantics. A new Visualization can be created through a POST request to the /api/visualizations resource with a valid JSON payload. An example of payload could be:

{
  "columns": [
    {
      "dimension": "J5jldMd8OHv",
      "items": [
        {
          "name": "CHP",
          "id": "uYxK4wmcPqA",
          "displayName": "CHP",
          "displayShortName": "CHP",
          "dimensionItemType": "ORGANISATION_UNIT_GROUP"
        },
        {
          "name": "Hospital",
          "id": "tDZVQ1WtwpA",
          "displayName": "Hospital",
          "displayShortName": "Hospital",
          "dimensionItemType": "ORGANISATION_UNIT_GROUP"
        }
      ]
    }
  ],
  "rows": [
    {
      "dimension": "SooXFOUnciJ",
      "items": [
        {
          "name": "DOD",
          "id": "B0bjKC0szQX",
          "displayName": "DOD",
          "displayShortName": "DOD",
          "dimensionItemType": "CATEGORY_OPTION_GROUP"
        },
        {
          "name": "CDC",
          "id": "OK2Nr4wdfrZ",
          "displayName": "CDC",
          "displayShortName": "CDC",
          "dimensionItemType": "CATEGORY_OPTION_GROUP"
        }
      ]
    }
  ],
  "filters": [
    {
      "dimension": "ou",
      "items": [
        {
          "name": "Sierra Leone",
          "id": "ImspTQPwCqd",
          "displayName": "Sierra Leone",
          "displayShortName": "Sierra Leone",
          "dimensionItemType": "ORGANISATION_UNIT"
        },
        {
          "name": "LEVEL-1",
          "id": "LEVEL-H1KlN4QIauv",
          "displayName": "LEVEL-1"
        }
      ]
    }
  ],
  "name": "HIV Cases Monthly",
  "description": "Cases of HIV across the months",
  "category": "XY1vwCQskjX",
  "showDimensionLabels": true,
  "hideEmptyRows": true,
  "hideEmptyColumns": true,
  "skipRounding": true,
  "aggregationType": "SUM",
  "regressionType": "LINEAR",
  "type": "PIVOT_TABLE",
  "numberType": "VALUE",
  "measureCriteria": "Some criteria",
  "showHierarchy": true,
  "completedOnly": true,
  "displayDensity": "NORMAL",
  "fontSize": "NORMAL",
  "digitGroupSeparator": "SPACE",
  "legendDisplayStyle": "FILL",
  "legendDisplayStrategy": "FIXED",
  "hideEmptyRowItems": "BEFORE_FIRST_AFTER_LAST",
  "fixColumnHeaders": true,
  "fixRowHeaders": false,
  "regression": false,
  "cumulative": true,
  "sortOrder": 1,
  "topLimit": 2,
  "rowTotals": true,
  "colTotals": true,
  "hideTitle": true,
  "hideSubtitle": true,
  "hideLegend": true,
  "showData": true,
  "percentStackedValues": true,
  "noSpaceBetweenColumns": true,
  "rowSubTotals": true,
  "colSubTotals": true,
  "userOrgUnitType": "TEI_SEARCH",
  "externalAccess": false,
  "publicAccess": "--------",
  "reportingParams": {
    "reportingPeriod": true,
    "organisationUnit": true,
    "parentOrganisationUnit": true,
    "grandParentOrganisationUnit": true
  },
  "parentGraphMap": {
    "ImspTQPwCqd": ""
  },
  "access": {
    "read": true,
    "update": true,
    "externalize": true,
    "delete": false,
    "write": true,
    "manage": false
  },
  "optionalAxes": [
    {
      "dimensionalItem": "fbfJHSPpUQD",
      "axis": 1
    },
    {
      "dimensionalItem": "cYeuwXTCPkU",
      "axis": 2
    }
  ],
  "relativePeriods": {
    "thisYear": false,
    "quartersLastYear": true,
    "last52Weeks": false,
    "thisWeek": false,
    "lastMonth": false,
    "last14Days": false,
    "biMonthsThisYear": false,
    "monthsThisYear": false,
    "last2SixMonths": false,
    "yesterday": false,
    "thisQuarter": false,
    "last12Months": false,
    "last5FinancialYears": false,
    "thisSixMonth": false,
    "lastQuarter": false,
    "thisFinancialYear": false,
    "last4Weeks": false,
    "last3Months": false,
    "thisDay": false,
    "thisMonth": false,
    "last5Years": false,
    "last6BiMonths": false,
    "last4BiWeeks": false,
    "lastFinancialYear": false,
    "lastBiWeek": false,
    "weeksThisYear": false,
    "last6Months": false,
    "last3Days": false,
    "quartersThisYear": false,
    "monthsLastYear": false,
    "lastWeek": false,
    "last7Days": false,
    "thisBimonth": false,
    "lastBimonth": false,
    "lastSixMonth": false,
    "thisBiWeek": false,
    "lastYear": false,
    "last12Weeks": false,
    "last4Quarters": false
  },
  "user": {},
  "yearlySeries": [
    "THIS_YEAR"
  ],
  "userGroupAccesses": [
    {
      "access": "rwx-----",
      "userGroupUid": "ZoHNWQajIoe",
      "displayName": "Bo District M&E officers",
      "id": "ZoHNWQajIoe"
    }
  ],
  "userAccesses": [
    {
      "access": "--------",
      "displayName": "John Barnes",
      "id": "DXyJmlo9rge",
      "userUid": "DXyJmlo9rge"
    }
  ],
  "legendSet": {
    "name": "Death rate up",
    "id": "ham2eIDJ9k6",
    "legends": [
      {
        "startValue": 1,
        "endValue": 2,
        "color": "red",
        "image": "some-image"
      },
      {
        "startValue": 2,
        "endValue": 3,
        "color": "blue",
        "image": "other-image"
      }
    ]
  },
  "outlierAnalysis": {
    "enabled": true,
    "outlierMethod": "IQR",
    "thresholdFactor": 1.5,
    "normalizationMethod": "Y_RESIDUALS_LINEAR",
    "extremeLines": {
      "enabled": true,
      "value": 3.5
    }
  },
  "legend": {
    "strategy": "FIXED",
    "style": "FILL",
    "set": {
      "id": "fqs276KXCXi",
      "displayName": "ANC Coverage"
    },
    "showKey": false
  },
  "seriesKey": {
    "hidden": true,
    "label": {
      "fontStyle": {
        "textColor": "#cccddd"
      }
    }
  },
  "axes": [
    {
      "index": 0,
      "type": "RANGE",
      "label": {
        "fontStyle": {
          "textColor": "#cccddd"
        }
      },
      "title": {
        "text": "Range axis title",
        "textMode": "CUSTOM",
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "decimals": 1,
      "maxValue": 100,
      "minValue": 20,
      "steps": 5,
      "baseLine": {
        "value": 50,
        "title": {
          "text": "My baseline",
          "fontStyle": {
            "textColor": "#000000"
          }
        }
      },
      "targetLine": {
        "value": 80,
        "title": {
          "text": "My targetline",
          "fontStyle": {
            "textColor": "#cccddd"
          }
        }
      }
    },
    {
      "index": 1,
      "type": "DOMAIN",
      "label": {
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "title": {
        "text": "Domain axis title",
        "textMode": "CUSTOM",
        "fontStyle": {
          "textColor": "#cccddd"
        }
      }
    }
  ],
  "axes": [
    {
      "index": 0,
      "type": "RANGE",
      "label": {
        "fontStyle": {
          "textColor": "#cccddd"
        }
      },
      "title": {
        "text": "Range axis title",
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "decimals": 1,
      "maxValue": 100,
      "minValue": 20,
      "steps": 5,
      "baseLine": {
        "value": 50,
        "title": {
          "text": "My baseline",
          "fontStyle": {
            "textColor": "#000000"
          }
        }
      },
      "targetLine": {
        "value": 80,
        "title": {
          "text": "My targetline",
          "fontStyle": {
            "textColor": "#cccddd"
          }
        }
      }
    },
    {
      "index": 1,
      "type": "DOMAIN",
      "label": {
        "fontStyle": {
          "textColor": "#000000"
        }
      },
      "title": {
        "text": "Domain axis title",
        "fontStyle": {
          "textColor": "#cccddd"
        }
      }
    }
  ]
}

Chcete-li aktualizovat konkrétní vizualizaci, můžete odeslat požadavek PUT na stejný prostředek /api/visualizations s podobným datovým obsahem PLUS a příslušným identifikátorem vizualizace, např.:

PUT /api/visualizations/hQxZGXqnLS9

Nakonec, chcete-li odstranit existující vizualizaci, můžete provést požadavek DELETE s uvedením identifikátoru vizualizace, která má být odstraněna, jak je znázorněno:

DELETE /api/visualizations/hQxZGXqnLS9

Event visualization

The EventVisualization API is designed to help clients to interact with event charts and reports. The endpoints of this API are used by the Event Visualization application which allows the creation, configuration and management of charts and reports based on the client's definitions. The main idea is to enable clients and users to have a unique and centralized API providing all types of event charts and reports as well as specific parameters and configuration for each type of event visualization. This API was introduced with the expectation to unify both eventCharts and eventReports APIs and entirely replace them in favour of the eventVisualizations API (which means that the usage of eventCharts and eventReports APIs should be avoided). In summary, the following resources/APIs: /api/eventCharts, /api/eventReports are being replaced by /api/eventVisualizations

Poznámka

Nové aplikace a klienti by se měli vyvarovat používání rozhraní API eventCharts a eventReports, protože jsou zastaralá. Místo toho použijte rozhraní API eventVisualizations.

An EventVisualization object is composed of many attributes (some of them related to charting and others related to reporting), but the most important ones responsible to reflect the core information of the object are: "id", "name", "type", "dataDimensionItems", "columns", "rows" and "filters". The root endpoint of the API is /api/eventVisualizations, and the list of current attributes and elements are described in the table below.

Tabulka: Atributy EventVisualization

Pole Popis
id Jedinečný identifikátor.
code Vlastní kód k identifikaci EventVisualation.
název Název EventVisualation
typ Platné typy EventVisualiation jsou: The valid types are: COLUMN, STACKED_COLUMN, BAR, STACKED_BAR, LINE, LINE_LIST, AREA, STACKED_AREA, PIE, RADAR, GAUGE, YEAR_OVER_YEAR_LINE, YEAR_OVER_YEAR_COLUMN, SINGLE_VALUE, PIVOT_TABLE, SCATTER, BUBBLE.
title Vlastní nadpis.
subtitle Vlastní podnadpis.
popis Definuje vlastní popis pro EventVisualation.
created Datum / čas vytvoření EventVisualation.
startDate Počáteční datum použité při filtrování.
endDate Datum ukončení použité během filtrování.
sortOrder Pořadí řazení této EventVisualation. Celočíselná hodnota.
user Objekt představující tvůrce vizualizace.
publicAccess Nastavuje oprávnění pro veřejný přístup.
displayDensity Hustota zobrazení textu.
fontSize Velikost písma textu.
relativePeriods Objekt představující relativní období použitá v analytickém dotazu.
legenda An object representing the definitions for the legend and legend set, display style (FILL or TEXT) and display strategy (FIXED or BY_DATA_ITEM).
aggregationType Určuje, jak jsou hodnoty agregovány (pokud existuje). Platné možnosti: SUM, AVERAGE, AVERAGE_SUM_ORG_UNIT, LAST, LAST_AVERAGE_ORG_UNIT, FIRST, FIRST_AVERAGE_ORG_UNIT, COUNT, STDDEV, VARIANCE, MIN, MAX, NONE, CUSTOM or DEFAULT.
regressionType Platný typ regrese: NONE, LINEAR, POLYNOMIAL nebo LOESS.
targetLineValue Cílová čára grafu. Přijímá typ Double.
targetLineLabel Štítek cílové čáry grafu.
rangeAxisLabel Popis / název svislé osy (y) grafu.
domainAxisLabel Popis / název vodorovné osy (x) grafu.
rangeAxisMaxValue Maximální hodnota osy grafu. Hodnoty mimo rozsah se nezobrazí.
rangeAxisMinValue Minimální hodnota osy grafu. Hodnoty mimo rozsah se nezobrazí.
rangeAxisSteps Počet kroků osy mezi minimální a maximální hodnotou.
rangeAxisDecimals Počet desetinných míst pro hodnoty os.
baseLineValue Základní hodnota grafu.
baseLineLabel Popisek základní linie grafu.
digitGroupSeparator Oddělovač skupiny číslic. Platné hodnoty: COMMA, SPACE nebo NONE.
topLimit Horní limit nastavený pro kontingenční tabulku.
measureCriteria Popisuje kritéria použitá pro toto opatření.
percentStackedValues Používá složené hodnoty nebo ne. Pravděpodobnější použití pro grafiku / grafy. Booleovská hodnota.
noSpaceBetweenColumns Zobrazit / skrýt mezeru mezi sloupci. Booleovská hodnota.
externalAccess Označuje, zda je EventVisualization k dispozici jako externí pouze pro čtení. Booleovská hodnota.
userOrganisationUnit Označuje, zda má uživatel organizační jednotku. Booleovská hodnota.
userOrganisationUnitChildren Označuje, zda má uživatel podřízenou organizační jednotku. Booleovská hodnota.
userOrganisationUnitGrandChildren Označuje, zda má uživatel organizační jednotku velkých dětí. Booleovská hodnota.
rowTotals Zobrazí (nebo ne) součty řádků. Booleovská hodnota.
colTotals Zobrazí (nebo ne) součty sloupců. Booleovská hodnota.
rowSubTotals Zobrazí (nebo ne) řádkové mezisoučty. Booleovská hodnota.
colSubTotals Zobrazí (nebo ne) mezisoučty sloupců. Booleovská hodnota.
cumulativeValues Označuje, zda EventVisualization používá kumulativní hodnoty. Booleovská hodnota.
hideEmptyRows Označuje, zda se mají skrýt řádky bez datových hodnot. Booleovská hodnota.
completedOnly Flag used in analytics requests. If true, only completed events/enrollments will be taken into consideration. Boolean value.
showDimensionLabels Zobrazuje štítky rozměrů nebo ne. Booleovská hodnota.
hideTitle Skryje název nebo ne. Booleovská hodnota.
hideSubtitle Skryje titulky nebo ne. Booleovská hodnota.
showHierarchy Zobrazuje (nebo ne) názvy hierarchie organizačních jednotek. Booleovská hodnota.
showData Používá se v grafech ke skrytí nebo neskrytí dat / hodnot v rámci vykresleného modelu. Booleovská hodnota.
lastUpdatedBy Objekt, který představuje uživatele, který použil poslední změny na EventVisualization.
lastUpdated Datum / čas poslední změny EventVisualization.
favorites Seznam ID uživatelů, kteří označili tento objekt jako oblíbený.
subscribers Seznam ID uživatelů, kteří se přihlásili k odběru této EventVisualization.
translations Sada dostupných překladů objektů, obvykle filtrovaných podle národního prostředí.
program Program spojený.
programStage Související programová fáze.
programStatus Stav programu. Může být ACTIVE, COMPLETED, CANCELLED.
eventStatus Stav události. Může být ACTIVE, COMPLETED, VISITED, SCHEDULE, OVERDUE, SKIPPED.
dataType Typ dat události. Může to být AGGREGATED_VALUES nebo EVENTS.
columnDimensions Rozměry definované pro sloupce.
rowDimensions Rozměry definované pro řádky.
filterDimensions Rozměry definované pro filtry.
outputType Označuje typ výstupu EventVisualization. Může to být EVENT, ENROLLMENT nebo TRACKED_ENTITY_INSTANCE.
collapseDataDimensions Označuje, zda se mají sbalit všechny datové dimenze do jedné dimenze. Booleovská hodnota.
hideNaData Označuje, zda se mají skrýt N/A data. Booleovská hodnota.

Retrieving event visualizations

To retrieve a list of all existing event visualizations, in JSON format, with some basic information (including identifier, name and pagination) you can make a GET request to the URL below. You should see a list of all public/shared event visualizations plus your private ones. GET /api/eventVisualizations.json If you want to retrieve the JSON definition of a specific EventVisualization you can add its respective identifier to the URL: GET /api/eventVisualizations/hQxZGXqnLS9.json The following representation is an example of a response in JSON format (for brevity, certain information has been removed). For the complete schema, please use GET /api/schemas/eventVisualization.

{
    "lastUpdated": "2021-11-25T17:18:03.834",
    "href": "http://localhost:8080/dhis/api/eventVisualizations/EZ5jbRTxRGh",
    "id": "EZ5jbRTxRGh",
    "created": "2021-11-25T17:18:03.834",
    "name": "Inpatient: Mode of discharge by facility type this year",
    "publicAccess": "rw------",
    "userOrganisationUnitChildren": false,
    "type": "STACKED_COLUMN",
    "subscribed": false,
    "userOrganisationUnit": false,
    "rowSubTotals": false,
    "cumulativeValues": false,
    "showDimensionLabels": false,
    "sortOrder": 0,
    "favorite": false,
    "topLimit": 0,
    "collapseDataDimensions": false,
    "userOrganisationUnitGrandChildren": false,
    "displayName": "Inpatient: Mode of discharge by facility type this year",
    "percentStackedValues": false,
    "noSpaceBetweenColumns": false,
    "showHierarchy": false,
    "hideTitle": false,
    "showData": true,
    "hideEmptyRows": false,
    "hideNaData": false,
    "regressionType": "NONE",
    "completedOnly": false,
    "colTotals": false,
    "sharing": {
      "owner": "GOLswS44mh8",
      "external": false,
      "users": {},
      "userGroups": {},
      "public": "rw------"
    },
    "programStatus": "CANCELLED",
    "hideEmptyRowItems": "NONE",
    "hideSubtitle": false,
    "outputType": "EVENT",
    "hideLegend": false,
    "externalAccess": false,
    "colSubTotals": false,
    "rowTotals": false,
    "digitGroupSeparator": "SPACE",
    "program": {
      "id": "IpHINAT79UW"
    },
    "access": {
      "read": true,
      "update": true,
      "externalize": true,
      "delete": true,
      "write": true,
      "manage": true
    },
    "lastUpdatedBy": {
      "displayName": "John Traore",
      "name": "John Traore",
      "id": "xE7jOejl9FI",
      "username": "admin"
    },
    "relativePeriods": {
      "thisYear": false,
      ...
    },
    "programStage": {
      "id": "A03MvHHogjR"
    },
    "createdBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "user": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "attributeDimensions": [],
    "translations": [],
    "legend": {
      "set": {
        "id": "gFJUXah1uRH"
      },
      "showKey": false,
      "style": "FILL",
      "strategy": "FIXED"
    },
    "filterDimensions": [
      "ou",
      "H6uSAMO5WLD"
    ],
    "interpretations": [],
    "userGroupAccesses": [],
    "subscribers": [],
    "columns": [
      {
        "id": "X8zyunlgUfM"
      }
    ]
    "periods": [],
    "categoryDimensions": [],
    "rowDimensions": [
      "pe"
    ],
    "itemOrganisationUnitGroups": [],
    "programIndicatorDimensions": [],
    "attributeValues": [],
    "columnDimensions": [
      "X8zyunlgUfM"
    ],
    "userAccesses": [],
    "favorites": [],
    "dataDimensionItems": [],
    "categoryOptionGroupSetDimensions": [],
    "organisationUnitGroupSetDimensions": [],
    "organisationUnitLevels": [],
    "organisationUnits": [
      {
        "id": "ImspTQPwCqd"
      }
    ],
    "filters": [
      {
        "id": "ou"
      },
      {
        "id": "H6uSAMO5WLD"
      }
    ],
    "rows": [
      {
        "id": "pe"
      }
    ]
}

A more tailored response can be obtained by specifying, in the URL, the fields you want to extract. Ie.: GET /api/eventVisualizations/hQxZGXqnLS9.json?fields=interpretations will return

{
  "interpretations": [
    {
      "id": "Lfr8I2RPU0C"
    },
    {
      "id": "JuwgdJlJPGb"
    },
    {
      "id": "WAoU2rSpyZp"
    }
  ]
}

Jak je vidět, výše uvedené ZÍSKAT vrátí pouze interpretace související s daným identifikátorem (v tomto případě hQxZGXqnLS9).

Creating, updating and removing event visualizations

These operations follow the standard REST semantics. A new EventVisualization can be created through a POST request to the /api/eventVisualizations resource with a valid JSON payload. An example of payload could be:

{
    "name": "Inpatient: Cases under 10 years last 4 quarters",
    "publicAccess": "rw------",
    "userOrganisationUnitChildren": false,
    "type": "STACKED_COLUMN",
    "subscribed": false,
    "userOrganisationUnit": false,
    "rowSubTotals": false,
    "cumulativeValues": false,
    "showDimensionLabels": false,
    "sortOrder": 0,
    "favorite": false,
    "topLimit": 0,
    "collapseDataDimensions": false,
    "userOrganisationUnitGrandChildren": false,
    "displayName": "Inpatient: Cases under 10 years last 4 quarters",
    "percentStackedValues": false,
    "noSpaceBetweenColumns": false,
    "showHierarchy": false,
    "hideTitle": false,
    "showData": true,
    "hideEmptyRows": false,
    "userAccesses": [],
    "userGroupAccesses": [],
    "hideNaData": false,
    "regressionType": "NONE",
    "completedOnly": false,
    "colTotals": false,
    "programStatus": "CANCELLED",
    "sharing": {
      "owner": "GOLswS44mh8",
      "external": false,
      "users": {},
      "userGroups": {},
      "public": "rw------"
    },
    "displayFormName": "Inpatient: Cases under 10 years last 4 quarters",
    "hideEmptyRowItems": "NONE",
    "hideSubtitle": false,
    "outputType": "EVENT",
    "hideLegend": false,
    "externalAccess": false,
    "colSubTotals": false,
    "rowTotals": false,
    "digitGroupSeparator": "SPACE",
    "access": {
      "read": true,
      "update": true,
      "externalize": false,
      "delete": true,
      "write": true,
      "manage": true
    },
    "lastUpdatedBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "legend": {
      "set": {
        "id": "gFJUXah1uRH"
      },
      "showKey": false,
      "style": "FILL",
      "strategy": "FIXED"
    },
    "relativePeriods": {
      "thisYear": false,
    ...
    },
    "program": {
      "id": "IpHINAT79UW",
      "enrollmentDateLabel": "Date of enrollment",
      "incidentDateLabel": "Date of birth",
      "name": "Child Programme"
    },
    "programStage": {
      "id": "A03MvHHogjR",
      "executionDateLabel": "Report date",
      "name": "Birth"
    },
    "createdBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "user": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "translations": [],
    "filterDimensions": [
      "ou"
    ],
    "interpretations": [],
    "dataElementDimensions": [
      {
        "filter": "LE:10",
        "dataElement": {
          "id": "qrur9Dvnyt5"
        }
      }
    ],
    "periods": [],
    "categoryDimensions": [],
    "rowDimensions": [
      "pe"
    ],
    "columnDimensions": [
      "qrur9Dvnyt5"
    ],
    "organisationUnits": [
      {
        "id": "ImspTQPwCqd"
      }
    ],
    "filters": [
      {
        "dimension": "ou",
        "items": [
          {
            "id": "ImspTQPwCqd"
          }
        ]
      },
      {
        "dimension": "H6uSAMO5WLD",
        "items": []
      }
    ],
    "columns": [
      {
        "dimension": "X8zyunlgUfM",
        "items": [],
        "repetition": {
          "indexes": [1, 2, 3, -2, -1, 0]
        }
      },
      {
        "dimension": "eventDate",
        "items": [
          {
            "id": "2021-07-21_2021-08-01"
          },
          {
            "id": "2021-01-21_2021-02-01"
          }
        ]
      },
      {
        "dimension": "incidentDate",
        "items": [
          {
            "id": "2021-10-01_2021-10-30"
          }
        ]
      },
      {
        "dimension": "eventStatus",
        "items": [
          {
            "id": "ACTIVE"
          },
          {
            "id": "COMPLETED"
          }
        ]
      },
      {
        "dimension": "createdBy",
        "items": [
          {
            "id": "userA"
          }
        ]
      },
      {
        "dimension": "lastUpdatedBy",
        "items": [
          {
            "id": "userB"
          }
        ]
      }
    ],
    "rows": [
      {
        "dimension": "pe",
        "items": [
          {
            "id": "LAST_12_MONTHS"
          }
        ]
      }
    ]
}

For multi-program support, the root program should not be specified. This will turn the eventVisualization into a multi-program. Consequently, we have to specify the program and programStage (when applicable) for each dimension in rows, columns, and filters.

Příklad:

"program": null,
"columns": [
  {
    "dimension": "ou",
    "items": [
        {
            "id": "O6uvpzGd5pu"
        }
    ],
    "program": {
        "id": "IpHINAT79UW"
    }
  },
  {
    "dimensionType": "CATEGORY_OPTION_GROUP_SET",
    "items": [
      {
          "id": "JLGV7lRQRAg"
      },
      {
          "id": "p916ZCVGNyq"
      }
    ],
    "dimension": "C31vHZqu0qU",
    "program": {
        "id": "kla3mAPgvCH"
    },
    "programStage": {
        "id": "aNLq9ZYoy9W"
    }
  }
]

Note

The repetition attribute (in rows, columns or filters) indicates the events indexes to be retrieved. Taking the example above (in the previous json payload), it can be read as follows:

1 = First event
2 = Second event
3 = Third event
...
-2 = Third latest event
-1 = Second latest event
0 = Latest event (default)

To update a specific EventVisualization, you can send a PUT request to the same /api/eventVisualizations resource with a similar payload PLUS the respective EventVisualization's identifier, ie.: PUT /api/eventVisualizations/hQxZGXqnLS9 Finally, to delete an existing EventVisualization, you can make a DELETE request specifying the identifier of the EventVisualization to be removed, as shown: DELETE /api/eventVisualizations/hQxZGXqnLS9

Interpretace

Pro zdroje související s analýzou dat v DHIS2, jako jsou vizualizace, mapy, zprávy událostí, grafy událostí a dokonce vizualizace, můžete psát a sdílet interpretace dat. Interpretace může být komentář, otázka, pozorování nebo výklad k datové zprávě nebo vizualizaci.

/api/interpretations

Čtení interpretací

To read interpretations we will interact with the /api/interpretations resource. A typical GET request using field filtering can look like this:

GET /api/interpretations?fields=*,comments[id,text,user,mentions]

The output in JSON response format could look like below (additional fields omitted for brevity):

{
  "interpretations": [
    {
      "id": "XSHiFlHAhhh",
      "created": "2013-05-30T10:24:06.181+0000",
      "text": "Data looks suspicious, could be a data entry mistake.",
      "type": "MAP",
      "likes": 2,
      "user": {
        "id": "uk7diLujYif"
      },
      "reportTable": {
        "id": "LcSxnfeBxyi"
      },
      "visualization": {
        "id": "LcSxnfeBxyi"
      }
    }, {
      "id": "kr4AnZmYL43",
      "created": "2013-05-29T14:47:13.081+0000",
      "text": "Delivery rates in Bo looks high.",
      "type": "VISUALIZATION",
      "likes": 3,
      "user": {
        "id": "uk7diLujYif"
      },
      "visualization": {
        "id": "HDEDqV3yv3H"
      },
      "mentions": [
        {
          "created": "2018-06-25T10:25:54.498",
          "username": "boateng"
        }
      ],
      "comments": [
        {
          "id": "iB4Etq8yTE6",
          "text": "This report indicates a surge.",
          "user": {
            "id": "B4XIfwOcGyI"
          }
        },
        {
          "id": "iB4Etq8yTE6",
          "text": "Likely caused by heavy rainfall.",
          "user": {
            "id": "B4XIfwOcGyI"
          }
        },
        {
          "id": "SIjkdENan8p",
          "text": "Have a look at this @boateng.",
          "user": {
            "id": "xE7jOejl9FI"
          },
          "mentions": [
            {
              "created": "2018-06-25T10:03:52.316",
              "username": "boateng"
            }
          ]
        }
      ]
    }
  ]
}

Tabulka: Interpretační pole

Pole Popis
id Identifikátor interpretace.
created Doba, kdy interpretace vznikala.
typ Typ interpretovaného analytického objektu. Platné možnosti: VISUALIZATION, MAP, EVENT_REPORT, EVENT_CHART, EVENT_VISUALIZATION, DATASET_REPORT.
user Přidružení k uživateli, který interpretaci vytvořil.
vizualizace Přidružení k vizualizaci, pokud je typ VIZUALIZACE
eventVisualization Přidružení k vizualizaci události, pokud je typ EVENT_VISUALIZATION
mapa Přidružení k mapě, pokud je typ MAP.
eventReport Přidružení k přehledu události je typu EVENT_REPORT.
eventChart Přidružení k grafu událostí, pokud je typ EVENT_CHART.
dataSet Přidružení k datové sadě, pokud je typ DATASET_REPORT.
comments Soubor komentářů k výkladu. Textové pole obsahuje aktuální komentář.
mentions Soubor zmínek pro výklad. Seznam identifikátorů uživatelů.

For all analytical objects you can append /data to the URL to retrieve the data associated with the resource (as opposed to the metadata). As an example, by following the map link and appending /data one can retrieve a PNG (image) representation of the thematic map through the following URL:

https://play.dhis2.org/demo/api/maps/bhmHJ4ZCdCd/data

For all analytical objects you can filter by mentions. To retrieve all the interpretations/comments where a user has been mentioned you have three options. You can filter by the interpretation mentions (mentions in the interpretation description):

GET /api/interpretations?fields=*,comments[*]&filter=mentions.username:in:[boateng]

Můžete filtrovat podle zmínek v komentářích interpretace (zmínky v jakémkoli komentáři):

GET /api/interpretations?fields=*,comments[*]
  &filter=comments.mentions.username:in:[boateng]

You can filter by intepretations which contains the mentions either in the interpretation or in any comment (OR junction):

GET /api/interpretations?fields=*,comments[*]&filter=mentions:in:[boateng]

Psaní interpretací

When writing interpretations you will supply the interpretation text as the request body using a POST request with content type "text/plain". The URL pattern looks like the below, where {object-type} refers to the type of the object being interpreted and {object-id} refers to the identifier of the object being interpreted.

/api/interpretations/{object-type}/{object-id}

Valid options for object type are visualization, map, eventReport, eventChart, eventVisualization and dataSetReport.

Některé platné příklady interpretací jsou uvedeny níže.

Poznámka

Rozhraní API eventCharts a eventReports jsou zastaralé. Místo toho doporučujeme použít rozhraní eventVisualizations API.

/api/interpretations/visualization/hQxZGXqnLS9
/api/interpretations/map/FwLHSMCejFu
/api/interpretations/eventReport/xJmPLGP3Cde
/api/interpretations/eventChart/nEzXB2M9YBz
/api/interpretations/eventVisualization/nEzXB2M9YBz
/api/interpretations/dataSetReport/tL7eCjmDIgM

As an example, we will start by writing an interpretation for the visualization with identifier EbRN2VIbPdV. To write visualization interpretations we will interact with the /api/interpretations/visualization/{visualizationId} resource. The interpretation will be the request body. Based on this we can put together the following request using cURL:

curl -d "This visualization shows a significant ANC 1-3 dropout" -X POST
  "https://play.dhis2.org/demo/api/interpretations/visualization/EbRN2VIbPdV" -H "Content-Type:text/plain" -u admin:district

Notice that the response provides a Location header with a value indicating the location of the created interpretation. This is useful from a client perspective when you would like to add a comment to the interpretation.

Aktualizace a odstranění interpretací

To update an existing interpretation you can use a PUT request where the interpretation text is the request body using the following URL pattern, where {id} refers to the interpretation identifier:

/api/interpretations/{id}

Na základě toho můžeme použít curl k aktualizaci interpretace:

curl -d "This visualization shows a high dropout" -X PUT
  "https://play.dhis2.org/demo/api/interpretations/visualization/EV08iI1cJRA" -H "Content-Type:text/plain" -u admin:district

You can use the same URL pattern as above using a DELETE request to remove the interpretation.

Vytváření komentářů interpretací

When writing comments to interpretations you will supply the comment text as the request body using a POST request with content type "text/plain". The URL pattern looks like the below, where {interpretation-id} refers to the interpretation identifier.

/api/interpretations/{interpretation-id}/comments

Second, we will write a comment to the interpretation we wrote in the example above. By looking at the interpretation response you will see that a Location header is returned. This header tells us the URL of the newly created interpretation and from that, we can read its identifier. This identifier is randomly generated so you will have to replace the one in the command below with your own. To write a comment we can interact with the /api/interpretations/{id}/comments resource like this:

curl -d "An intervention is needed" -X POST
  "https://play.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comments"
  -H "Content-Type:text/plain" -u admin:district

Aktualizace a odstranění komentářů k výkladu

To updating an interpretation comment you can use a PUT request where the comment text is the request body using the following URL pattern:

/api/interpretations/{interpretation-id}/comments/{comment-id}

Na základě toho můžeme použít curl k aktualizaci komentáře:

curl "https://play.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comments/idAzzhVWvh2"
  -d "I agree with that." -X PUT -H "Content-Type:text/plain" -u admin:district

You can use the same URL pattern as above using a DELETE request to the remove the interpretation comment.

Interpretace Líbí se mi

To like an interpretation you can use an empty POST request to the like resource:

POST /api/interpretations/{id}/like

A like will be added for the currently authenticated user. A user can only like an interpretation once.

To remove a like for an interpretation you can use a DELETE request to the same resource as for the like operation.

The like status of an interpretation can be viewed by looking at the regular Web API representation:

GET /api/interpretations/{id}

The like information is found in the likes field, which represents the number of likes, and the likedBy array, which enumerates the users who have liked the interpretation.

{
  "id": "XSHiFlHAhhh",
  "text": "Data looks suspicious, could be a data entry mistake.",
  "type": "VISUALIZATION",
  "likes": 2,
  "likedBy": [
    {
      "id": "k7Hg12fJ2f1"
    },
    {
      "id": "gYhf26fFkjFS"
    }
  ]
}

Zobrazení SQL

Prostředek SQL views umožňuje vytvářet a načítat výslednou sadu pohledů SQL. Pohledy SQL lze spustit přímo proti databázi a vykreslit sadu výsledků prostřednictvím prostředku Web API.

/api/sqlViews

SQL views are useful for creating data views which may be more easily constructed with SQL compared combining the multiple objects of the Web API. As an example, lets assume we have been asked to provide a view of all organization units with their names, parent names, organization unit level and name, and the coordinates listed in the database. The view might look something like this:

select ou.name as orgunit, par.name as parent, ou.coordinates, ous.level, oul.name 
from organisationunit ou
inner join _orgunitstructure ous on ou.organisationunitid = ous.organisationunitid
inner join organisationunit par on ou.parentid = par.organisationunitid
inner join orgunitlevel oul on ous.level = oul.level
where ou.coordinates is not null
order by oul.level, par.name, ou.name;

We will use curl to first execute the view on the DHIS2 server. This is essentially a materialization process, and ensures that we have the most recent data available through the SQL view when it is retrieved from the server. You can first look up the SQL view from the api/sqlViews resource, then POST using the following command:

curl "https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/execute" -X POST -u admin:district

The next step in the process is the retrieval of the data. The endpoint is available at:

/api/sqlViews/{id}/data(.csv)

The id path represents the SQL view identifier. The path extensions refers to the format of the data download. Append either data for JSON data or data.csv for comma separated values. Support response formats are json, xml, csv, xls, html and html+css.

As an example, the following command would retrieve CSV data for the SQL view defined above.

curl "https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv" -u admin:district

Existují tři typy SQL pohledu:

  • SQL pohled: Standardní SQL pohledy.

  • Materializovaný SQL pohled: SQL pohledy, které jsou zhmotněné zapsáním na disk. Je třeba aktualizovat, aby odrážely změny v podkladové tabulky. Podporuje kritéria pro filtrování sady výsledků.

  • SQL dotazy: Obyčejné SQL dotazy. Podpora inline proměnných pro přizpůsobené dotazy.

Kritéria

You can do simple filtering on the columns in the result set by appending criteria query parameters to the URL, using the column names and filter values separated by columns as parameter values, on the following format:

/api/sqlViews/{id}/data?criteria=col1:value1&criteria=col2:value2

As an example, to filter the SQL view result set above to only return organisation units at level 4 you can use the following URL:

https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv?criteria=level:4

Proměnné

SQL views support variable substitution. Variable substitution is only available for SQL view of type query, meaning SQL views which are not created in the database but simply executed as regular SQL queries. Variables can be inserted directly into the SQL query and must be on this format:

${variable-key}

As an example, an SQL query that retrieves all data elements of a given value type where the value type is defined through a variable can look like this:

select * from dataelement where valuetype = '${valueType}';

These variables can then be supplied as part of the URL when requested through the sqlViews Web API resource. Variables can be supplied on the following format:

/api/sqlViews/{id}/data?var=key1:value1&var=key2:value2

Ukázkový dotaz odpovídající výše uvedenému příkladu může vypadat takto:

/api/sqlViews/dI68mLkP1wN/data.json?var=valueType:int

Proměnná valueType bude nahrazena hodnotou int a dotaz vrátí datové prvky s hodnotovým typem int.

The variable parameter must contain alphanumeric characters only. The variables must contain alphanumeric, dash, underscore and whitespace characters only.

SQL Views of type query also support two system-defined variables that allow the query to access information about the user executing the view:

proměnná prostředek
${_current_user_id} ID uživatele databáze
${_current_username} uživatelské jméno uživatele

Hodnoty těchto proměnných nelze zadat jako součást adresy URL. Vždy jsou vyplněny informacemi o uživateli.

For example, the following SQL view of type query shows all the organisation units that are assigned to the user:

select ou.path, ou.name
from organisationunit ou_user
join organisationunit ou on ou.path like ou_user.path || '%'
join usermembership um on um.organisationunitid = ou_user.organisationunitid
where um.userinfoid = ${_current_user_id}
order by ou.path;

Filtrování

The SQL view API supports data filtering, equal to the metadata object_filter. For a complete list of filter operators you can look at the documentation for metadata object_filter.

To use filters, simply add them as parameters at the end of the request URL for your SQL view like this. This request will return a result including org units with "bo" in the name at level 2 of the org unit hierarchy:

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_level:eq:2&filter=orgunit_name:ilike:bo

Následující příklad vrátí všechny org jednotky s orgunit_level 2 nebo 4:

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_level:in:[2,4]

And last, an example to return all org units that does not start with "Bo":

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_name:!like:Bo

Datové položky

Tento koncový bod umožňuje uživateli dotazovat se na data týkající se několika různých dimenzionálních položek. Jedná se o tyto položky: INDICATOR,DATA_ELEMENT, DATA_SET,PROGRAM_INDICATOR, PROGRAM_DATA_ELEMENT,PROGRAM_ATTRIBUTE. Koncový bod podporuje pouze požadavky GET a jako ostatní koncové body může vracet odpovědi ve formátu JSON nebo XML.

URL je /api/dataItems a jak si dokážete představit, je schopen načíst různé objekty prostřednictvím stejného koncového bodu ve stejném požadavku GET. Z tohoto důvodu se některé dostupné dotazovatelné atributy budou lišit v závislosti na dotazované položce (položkách) dimenze.

Abychom porozuměli výše uvedenému prohlášení, podívejme se na následující příklady požadavků:

1) GET /api/dataItems?filter=dimensionItemType:eq:DATA_ELEMENT&filter=valueType:eq:TEXT V tomto příkladu má typ položky DATA_ELEMENT atribut valueType, který lze použít v dotazu.

2) GET /api/dataItems?pageSize=50&order=displayName:asc&filter=dimensionItemType:eq:PROGRAM_INDICATOR&filter=displayName:ilike:someName&filter=programId:eq:WSGAb5XwJ3Y

Zde PROGRAM_INDICATOR umožňuje filtrování podle programId.

So, based on the examples 1) and 2) if you try filtering a DATA_ELEMENT by programId or filter a PROGRAM_INDICATOR by valueType, you should get no results. In other words, the filter will be applied only when the attribute actually exists for the respective data item.

Another important aspect to be highlighted is that this endpoint does NOT follow the same querying standards as other existing endpoints, like Metadata object filter for example. As a consequence, it supports a smaller set of features and querying. The main reason for that is the need for querying multiple different items that have different relationships, which is not possible using the existing filtering components (used by the others endpoints).

Endpoint responses

Base on the GET request/query, the following status codes and responses are can be returned.

Results found (status code 200)

{
  "pager": {
    "page": 1,
    "pageCount": 27,
    "total": 1339,
    "pageSize": 50
  },
  "dataItems": [
    {
      "simplifiedValueType": "TEXT",
      "displayName": "TB program Gender",
      "displayShortName": "TB prog. Gen.",
      "valueType": "TEXT",
      "name": "TB program Gender",
      "shortName": "TB prog Gen",
      "id": "ur1Edk5Oe2n.cejWyOfXge6",
      "programId": "ur1Edk5Oe2n",
      "dimensionItemType": "PROGRAM_ATTRIBUTE"
    }
  ]
}

Results not found (status code 200)

{
  "pager": {
    "page": 1,
    "pageCount": 1,
    "total": 0,
    "pageSize": 50
  },
  "dataItems": [
  ]
}

Invalid query (status code 409)

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Unable to parse element `INVALID_TYPE` on filter dimensionItemType`. The values available are: [INDICATOR, DATA_ELEMENT, DATA_ELEMENT_OPERAND, DATA_SET, PROGRAM_INDICATOR, PROGRAM_DATA_ELEMENT, PROGRAM_ATTRIBUTE]",
  "errorCode": "E2016"
}

Stránkování

This endpoint also supports pagination as a default option. If needed, you can disable pagination by adding paging=false to the GET request, i.e.: /api/dataItems?filter=dimensionItemType:in:[INDICATOR]&paging=false.

Zde je příklad datového obsahu, když je povoleno stránkování. Pamatujte, že stránkování je výchozí možnost a není nutné ji výslovně nastavovat.

{
  "pager": {
    "page": 1,
    "pageCount": 20,
    "total": 969,
    "pageSize": 50
  },
  "dataItems": [...]
}

Note

For elements where there is an associated Program, the program name should also be returned as part of the element name (as a prefix). The only exception is Program Indicators. We will not prefix the element name in this case, in order to keep the same behavior as existing endpoints.

The /dataItems endpoint will bring only data items that are defined as aggregatable type. The current list of valid aggregatable types is: TEXT, LONG_TEXT, LETTER, BOOLEAN, TRUE_ONLY, NUMBER, UNIT_INTERVAL, PERCENTAGE, INTEGER, INTEGER_POSITIVE, INTEGER_NEGATIVE, INTEGER_ZERO_OR_POSITIVE, COORDINATE.

Even though the response returns several different attributes, the filtering can only be applied to specific ones: displayName, name, valueType, id, dimensionItemType, programId.

The order will be considered invalid if it is set on top of name (ie.: order=name:asc) and a filter is set to displayName (ie.: filter=displayName:ilike:aName), and vice-versa.

Atributy odpovědi

Nyní, když máme dobrou představu o hlavních funkcích a použití tohoto koncového bodu, pojďme se podívat na seznam atributů vrácených v odpovědi.

Tabulka: Atributy datových položek

Pole Popis
id Jedinečný identifikátor.
code Vlastní kód k identifikaci položky dimenze.
název Název uvedený pro položku.
displayName Definovaný zobrazovaný název.
shortName Krátký název položky.
displayShortName Definovaný zobrazovaný krátký název.
dimensionItemType Typ dimenzí. Možné typy: INDICATOR, DATA_ELEMENT, REPORTING_RATE, PROGRAM_INDICATOR, PROGRAM_DATA_ELEMENT, PROGRAM_ATTRIBUTE.
valueType Typ hodnoty položky (přesnější definice). Možné typy: TEXT, LONG_TEXT, LETTER, BOOLEAN, TRUE_ONLY, UNIT_INTERVAL, PERCENTAGE, INTEGER, INTEGER_POSITIVE, INTEGER_NEGATIVE, INTEGER_ZERO_OR_POSITIVE, COORDINATE
simplifiedValueType Obecná reprezentace hodnotového typu. Platné hodnoty: NUMBER, BOOLEAN, DATE, FILE_RESOURCE, COORDINATE, TEXT
programId Přidružené ID programu.

Prohlížení reprezentací analytických zdrojů

DHIS2 has several resources for data analysis. These resources include maps, visualizations, eventVisualizations, reports and documents. By visiting these resources you will retrieve information about the resource. For instance, by navigating to /api/visualizations/R0DVGvXDUNP the response will contain the name, last date of modification and so on for the chart. To retrieve the analytical representation, for instance, a PNG representation of the visualization, you can append /data to all these resources. For instance, by visiting /api/visualizations/R0DVGvXDUNP/data the system will return a PNG image of the visualization.

Tabulka: Analytické zdroje

Zdroj Popis Data URL Reprezentace zdrojů
eventCharts Grafy událostí /api/eventCharts/<identifier>/data png
mapy Mapy /api/maps/<identifier>/data png
visualizations Kontingenční tabulky a grafy /api/visualizations/<identifier>/data json | jsonp | html | xml | pdf | xls | csv
eventVisualizations Grafy událostí /api/eventVisualizations/<identifier>/data png
png
zprávy Standardní zprávy /api/reports/<identifier>/data pdf | xls | html
dokumenty Zdroje /api/documents/<identifier>/data <follows document>

The data content of the analytical representations can be modified by providing a date query parameter. This requires that the analytical resource is set up for relative periods for the period dimension.

Tabulka: Parametry dotazu na data

Parametr dotazu Hodnota Popis
datum Datum ve formátu yyyy-MM-dd Základ pro relativní období v přehledu (vyžaduje relativní období)

Tabulka: Parametry dotazu pro typy png / obrázky (vizualizace, mapy)

Parametr dotazu Popis
width Šířka obrázku v pixelech
height Výška obrázku v pixelech

Some examples of valid URLs for retrieving various analytical representations are listed below.

/api/visualizations/R0DVGvXDUNP/data
/api/visualizations/R0DVGvXDUNP/data?date=2013-06-01

/api/visualizations/jIISuEWxmoI/data.html
/api/visualizations/jIISuEWxmoI/data.html?date=2013-01-01
/api/visualizations/FPmvWs7bn2P/data.xls
/api/visualizations/FPmvWs7bn2P/data.pdf

/api/eventVisualizations/x5FVFVt5CDI/data
/api/eventVisualizations/x5FVFVt5CDI/data.png

/api/maps/DHE98Gsynpr/data
/api/maps/DHE98Gsynpr/data?date=2013-07-01

/api/reports/OeJsA6K1Otx/data.pdf
/api/reports/OeJsA6K1Otx/data.pdf?date=2014-01-01