Trasovač¶

Note Tracker has been re-implemented in DHIS2 2.36. This document describes the new tracker endpoints

• POST /api/tracker
• GET /api/tracker/enrollments
• GET /api/tracker/events
• GET /api/tracker/trackedEntities
• GET /api/tracker/relationships

Tracker (deprecated) describes the deprecated endpoints

• GET/POST/PUT/DELETE /api/trackedEntityInstances
• GET/POST/PUT/DELETE /api/enrollments
• GET/POST/PUT/DELETE /api/events

• GET/POST/PUT/DELETE /api/relationships

• If your are still using the deprecated tracker endpoints in production, please plan to migrate over to the new endpoints. Migrating to new tracker endpoints should help you get started. Reach out on the community of practice if you need further assistance. NOTE: The feature for data sync(importMode=SYNC) is not implemented in the new tracker endpoints, and if you are using this feature you will have to postpone the migration until a new SYNC feature is in place.

Objekty Trasovače¶

Trasovač se skládá z několika různých typů objektů, které jsou vnořeny dohromady, aby reprezentovaly data. V této části ukážeme a popíšeme každý z objektů používaných v Tracker API.

Tracked Entity¶

Trasované entity jsou kořenovým objektem pro model trasování.

Poznámka

Trasované entity "vlastní" všechny Hodnoty atributů trasované entity (nebo "atributy", jak je popsáno v předchozí tabulce). Atributy trasované entity jsou však buď spojeny s trasovanou entitou prostřednictvím jejího Typu trasované entity nebo Programu. Toto oddělení často nazýváme Atributy typu trasované entity a Atributy programu trasované entity. Důležitost tohoto oddělení souvisí s řízením přístupu a omezením toho, jaké informace může uživatel vidět.

"Atributy" uvedené v části Trasovaná entita jsou Atributy typu trasované entity.

Zápis¶

Trasované entity se mohou přihlásit do Programů, pro které mají nárok. Trasované entity jsou způsobilé, pokud je program nakonfigurován se stejným typem trasované entity jako trasovaná entita. Zápis reprezentujeme objektem Zápis, který popisujeme v této části.

Poznámka

Trasované entity "vlastní" všechny Hodnoty atributů trasovaných entit (nebo "atributy", jak je popsáno v předchozí tabulce). Atributy Trasovaných entit jsou však buď připojeny k Trasované entitě prostřednictvím jejího Typu trasované entity, nebo Programu. Toto rozdělení často označujeme jako Atributy typu trasované entity a Atributy programu trasované entity. Význam tohoto oddělení souvisí s řízením přístupu a omezením toho, jaké informace může uživatel vidět.

"Atributy", na které se odkazuje v Zápisu, jsou Atributy programu trasované entity.

Události¶

Events are either part of an EVENT PROGRAM or TRACKER PROGRAM. For TRACKER PROGRAM, events belong to an Enrollment, which again belongs to a Tracked Entity. On the other hand, EVENT PROGRAM is Events not connected to a specific Enrollment or Tracked Entity. The difference is related to whether we track a specific Tracked Entity or not. We sometimes refer to EVENT PROGRAM events as "anonymous events" or "single events" since they only represent themselves and not another Tracked Entity.

V rozhraní API je podstatný rozdíl v tom, že všechny události jsou buď připojeny ke stejnému zápisu (PROGRAM UDÁLOSTI), nebo k různým zápisům (PROGRAM TRACKER). Níže uvedená tabulka uvede všechny výjimečné případy mezi těmito dvěma.

Relationship¶

Vztahy jsou objekty, které spojují dva další objekty sledování. Omezení, kterým musí odpovídat každá strana vztahu, jsou založena na Typu vztahu ve Vztahu.

Note

Relationship item represents a link to an object. Since a relationship can be between any tracker object like tracked entity, enrollment, and event, the value depends on the relationship type. For example, if the relationship type connects from an event to a tracked entity, the format is strict:

{
   "from": {
     "event": { "event": "ABCDEF12345" }
   },
   "to": {
     "trackedEntity": { "trackedEntity": "FEDCBA12345" }
   }
}

Atribut¶

Atributy jsou skutečné hodnoty popisující trasované entity. Mohou být připojeny prostřednictvím typu trasované entity nebo programu. Implicitně to znamená, že atributy mohou být součástí trasované entity i zápisu.

Poznámka

Pro attributes jsou při přidávání dat vyžadovány pouze vlastnosti "attribute" a "value". "value" může být null, což znamená, že uživatel by měl hodnotu odstranit.

V kontextu objektů sledování označujeme atributy trasované entity a hodnoty atributů trasované entity jako "atributy". Atributy jsou však také jejich věc, související s metadaty. Proto je důležité oddělit atributy Tracker a atributy metadat. V tracker API je možné odkazovat na atributy metadat při zadávání idScheme (další informace viz parametry požadavku).

Data Values¶

Zatímco Attributes popisuje trasovanou entitu nebo zápis, datové hodnoty popisují událost. Hlavní rozdíl spočívá v tom, že atributy mohou mít pro danou trasovanou entitu pouze jednu hodnotu. Naproti tomu datové hodnoty mohou mít mnoho různých hodnot pro různé události - i když všechny události patří ke stejnému zápisu nebo trasované entitě.

Poznámka

Pro data elements jsou při přidávání dat vyžadovány pouze vlastnosti "dataElement" a "value". "value" může být null, což znamená, že uživatel by měl hodnotu odstranit.

Tracker Notes¶

DHIS2 tracker umožňuje zachycování dat pomocí datových prvků a atributů trasovaných entit. Někdy však může nastat situace, kdy je nutné zaznamenat doplňující informace nebo se k dané problematice vyjádřit. Tyto dodatečné informace lze zachytit pomocí poznámek trackeru. Poznámky ke sledování jsou ekvivalentní komentářům datových hodnot ze strany Aggregate DHIS2.

Existují dva typy poznámek – poznámky zaznamenané na úrovni události a poznámky zaznamenané na úrovni registrace. Zápis může mít jednu nebo více událostí. Komentáře ke každé z událostí – například proč byla událost zmeškána, přeplánována nebo proč bylo vyplněno jen několik datových prvků a podobně – lze dokumentovat pomocí poznámek k události. Každá z událostí v rámci registrace může mít svůj vlastní příběh/poznámky. Potom lze zaznamenat například celkové pozorování těchto událostí pomocí poznámky k zápisu pro rodiče. Poznámky k zápisu jsou také užitečné pro zdokumentování například toho, proč je zápis zrušen. Kdy a jak poznámky použije, záleží na představivosti uživatele a na jeho použití.

Zápis i událost mohou mít tolik poznámek, kolik je potřeba – není omezeno. Ani jednu z těchto poznámek však není možné smazat ani aktualizovat. Jsou jako logbook. Pokud chcete poznámku upravit, můžete tak učinit vytvořením další poznámky. Jediný způsob, jak odstranit poznámku, je smazání nadřazeného objektu – buď události, nebo zápisu.

Poznámky trackeru nemají svůj vyhrazený koncový bod; jsou vyměňovány jako součást nadřazené události a / nebo datového obsahu registrace. Níže je ukázka datového obsahu.

{
  "trackedEntityInstance": "oi3PMIGYJH8",
  <entity_details>,
  ],
  "enrollments": [
    {
      "enrollment": "EbRsJr8LSSO",
      <enrollment_details>
      "notes": [
        {
          "note": "vxmCvYcPdaW",
          "value": "Enrollment note 2.",
        },
        {
          "value": "Enrollment note 1",
        }
      ],

      "events": [
        {
          "event": "zfzS9WeO0uM",
          <event_details>,
          "notes": [
            {
              "note": "MAQFb7fAggS",
              "value": "Event Note 1.",
            },
            {
              "value": "Event Note 2.",
            }
          ],
        },
        {
          ...
        }
      ]
    }
  ]
}

Uživatel¶

Musí být uvedeno jedno mezi polem uid nebo username. Pokud jsou uvedeny obě, bere se v úvahu pouze uživatelské jméno.

Program stage working lists¶

The program stage working lists feature within the Capture app is designed to display pre-established working lists relevant to a particular program stage. This functionality enables users to save filters and sorting preferences that are related to program stages, facilitating the organization and management of their workflow. To interact with them, you'll need to use the /api/programStageWorkingLists resource. These lists can be shared and follow the same sharing pattern as any other metadata. When using the /api/sharing the type parameter will be programStageWorkingLists.

/api/40/programStageWorkingLists

Payload on CRUD operations to program stage working lists¶

The endpoint above can be used to get all program stage working lists. To get a single one, just add at the end the id of the one you are interested in. This is the same in case you want to delete it. On the other hand, if you are looking to create or update a program stage working list, besides the endpoint mentioned above, you'll need to provide a payload in the following format:

Tabulka: Datový obsah

See an example payload below:

{
    "name":"Test WL",
    "program":{"id":"uy2gU8kT1jF"},
    "programStage":{"id":"oRySG82BKE6"},
    "description": "Test WL definition",
    "programStageQueryCriteria":
        {
            "status":"VISITED",
            "eventCreatedAt":{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"},
            "scheduledAt": {"type":"RELATIVE","period":"TODAY"},
            "enrollmentStatus": "COMPLETED",
            "followUp" : true,
            "enrolledAt": {"type":"RELATIVE","period":"THIS_MONTH"},
            "enrollmentOccurredAt": {"type":"RELATIVE","period":"THIS_MONTH"},
            "orgUnit": "Rp268JB6Ne4",
            "ouMode": "SELECTED",
            "assignedUserMode":"PROVIDED",
            "assignedUsers":["DXyJmlo9rge"],
            "order": "w75KJ2mc4zz:asc",
            "displayColumnOrder":["w75KJ2mc4zz","zDhUuAYrxNC"],
            "dataFilters":[{
                "dataItem": "GXNUsigphqK",
                "ge": "10",
                "le": "20"
            }],
            "attributeValueFilters":[{
                "attribute": "ruQQnf6rswq",
                "eq": "15"
            }]
        }
}

Import trackeru (POST /api/tracker)¶

Koncový bod POST /api/tracker umožňuje klientům importovat následující objekty trasování do DHIS2:

• Trasované entity
• Zápisy
• Události
• Relationships
• Data vložená do jiných trasovacích objektů

Hlavní změny ve srovnání s ostatními koncovými body pro import trackeru jsou:

1. Import payload can be nested or flat
2. Invocation can be synchronous or asynchronous
3. Import CSV events payload

Request parameters¶

V současné době koncový bod importu trackeru podporuje následující parametry:

NOTE: idScheme and its metadata specific idScheme parameters like orgUnitIdScheme, programIdScheme, ... used to allow and use the default AUTO. AUTO has been removed. The default idScheme has already been UID. Any requests sent with idScheme AUTO will see the same behavior as before, namely matching done using UID.

Flat and nested payloads¶

Importér podporuje jednoduchý i vnořený datový obsah. Hlavní rozdíl je v tom, jak klient požaduje, aby jeho data byla strukturována.

Flat

The flat-structured payload is straightforward. It can contain collections for each of the core tracker objects we have. This works seamlessly with existing data, which already have UIDs assigned. However, for new data, the client will have to provide new UIDs for any references between objects. For example, if you import a new tracked entity with a new enrollment, the tracked entity requires the client to provide a UID so that the enrollment can be linked to that UID.

Nested

Nested payloads are the most commonly used structure. Here, tracker objects are embedded within their parent object; For example, an enrollment within a tracked entity. The advantage of this structure is that the client does not need to provide UIDs for these connections since they will be given this connection during the import process since they are nested together.

POZNÁMKA

Zatímco vnořený datový obsah může být pro klienty jednodušší, před importem bude datový obsah vždy zploštěný. To znamená, že u velkých importů poskytne plochý strukturovaný datový obsah jak větší kontrolu, tak nižší režii pro samotný importní proces.

Příklady verzí FLAT a NESTED jsou uvedeny níže. Oba případy používají stejná data.

FLAT payload¶

{
  "trackedEntities": [
    {
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "Q9GufDoplCL"
    }
  ],
  "enrollments": [
    {
      "orgUnit": "O6uvpzGd5pu",
      "program": "f1AyMswryyQ",
      "trackedEntity": "Kj6vYde4LHh",
      "enrollment": "MNWZ6hnuhSw",
      "trackedEntityType": "Q9GufDoplCL",
      "enrolledAt": "2019-08-19T00:00:00.000",
      "deleted": false,
      "occurredAt": "2019-08-19T00:00:00.000",
      "status": "ACTIVE",
      "notes": [],
      "attributes": [],
    }
  ],
  "events": [
    {
      "scheduledAt": "2019-08-19T13:59:13.688",
      "program": "f1AyMswryyQ",
      "event": "ZwwuwNp6gVd",
      "programStage": "nlXNK4b7LVr",
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "status": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "attributeCategoryOptions": "xYerKDKCefk",
      "deleted": false,
      "attributeOptionCombo": "HllvX50cXC0",
      "dataValues": [
        {
          "updatedAt": "2019-08-19T13:58:37.477",
          "storedBy": "admin",
          "dataElement": "BuZ5LGNfGEU",
          "value": "20",
          "providedElsewhere": false
        },
        {
          "updatedAt": "2019-08-19T13:58:40.031",
          "storedBy": "admin",
          "dataElement": "ZrqtjjveTFc",
          "value": "Male",
          "providedElsewhere": false
        },
        {
          "updatedAt": "2019-08-19T13:59:13.691",
          "storedBy": "admin",
          "dataElement": "mB2QHw1tU96",
          "value": "[-11.566044,9.477801]",
          "providedElsewhere": false
        }
      ],
      "notes": []
    },
    {
      "scheduledAt": "2019-08-19T13:59:13.688",
      "program": "f1AyMswryyQ",
      "event": "XwwuwNp6gVE",
      "programStage": "PaOOjwLVW23",
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "status": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "attributeCategoryOptions": "xYerKDKCefk",
      "deleted": false,
      "attributeOptionCombo": "HllvX50cXC0",
      "notes": []
    }
  ],
  "relationships": [
    {
      "relationshipType": "Udhj3bsdHeT",
      "from": {
        "trackedEntity": { "trackedEntity": "Kj6vYde4LHh" }
      },
      "to": {
        "trackedEntity": { "trackedEntity": "Gjaiu3ea38E" }
      }
    }
  ]
}

NESTED payload¶

{
  "trackedEntities": [
    {
      "orgUnit": "O6uvpzGd5pu",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "Q9GufDoplCL",
      "relationships": [
        {
          "relationshipType": "Udhj3bsdHeT",
          "from": {
            "trackedEntity": { "trackedEntity": "Kj6vYde4LHh" }
          },
          "to": {
            "trackedEntity": { "trackedEntity": "Gjaiu3ea38E" }
          }
        }
      ],
      "enrollments": [
        {
          "orgUnit": "O6uvpzGd5pu",
          "program": "f1AyMswryyQ",
          "trackedEntity": "Kj6vYde4LHh",
          "enrollment": "MNWZ6hnuhSw",
          "trackedEntityType": "Q9GufDoplCL",
          "enrolledAt": "2019-08-19T00:00:00.000",
          "deleted": false,
          "occurredAt": "2019-08-19T00:00:00.000",
          "status": "ACTIVE",
          "notes": [],
          "relationships": [],
          "attributes": [],
          "events": [
            {
              "scheduledAt": "2019-08-19T13:59:13.688",
              "program": "f1AyMswryyQ",
              "event": "ZwwuwNp6gVd",
              "programStage": "nlXNK4b7LVr",
              "orgUnit": "O6uvpzGd5pu",
              "trackedEntity": "Kj6vYde4LHh",
              "enrollment": "MNWZ6hnuhSw",
              "enrollmentStatus": "ACTIVE",
              "status": "ACTIVE",
              "occurredAt": "2019-08-01T00:00:00.000",
              "attributeCategoryOptions": "xYerKDKCefk",
              "deleted": false,
              "attributeOptionCombo": "HllvX50cXC0",
              "dataValues": [
                {
                  "updatedAt": "2019-08-19T13:58:37.477",
                  "storedBy": "admin",
                  "dataElement": "BuZ5LGNfGEU",
                  "value": "20",
                  "providedElsewhere": false
                },
                {
                  "updatedAt": "2019-08-19T13:58:40.031",
                  "storedBy": "admin",
                  "dataElement": "ZrqtjjveTFc",
                  "value": "Male",
                  "providedElsewhere": false
                },
                {
                  "updatedAt": "2019-08-19T13:59:13.691",
                  "storedBy": "admin",
                  "dataElement": "mB2QHw1tU96",
                  "value": "[-11.566044,9.477801]",
                  "providedElsewhere": false
                }
              ],
              "notes": [],
              "relationships": []
            },
            {
              "scheduledAt": "2019-08-19T13:59:13.688",
              "program": "f1AyMswryyQ",
              "event": "XwwuwNp6gVE",
              "programStage": "PaOOjwLVW23",
              "orgUnit": "O6uvpzGd5pu",
              "trackedEntity": "Kj6vYde4LHh",
              "enrollment": "MNWZ6hnuhSw",
              "enrollmentStatus": "ACTIVE",
              "status": "ACTIVE",
              "occurredAt": "2019-08-01T00:00:00.000",
              "attributeCategoryOptions": "xYerKDKCefk",
              "deleted": false,
              "attributeOptionCombo": "HllvX50cXC0",
              "notes": [],
              "relationships": []
            }
          ]
        }
      ]
    }
  ]
}

SYNC and ASYNC¶

Pro uživatele je hlavním rozdílem mezi synchronním importem spíše než asynchronním okamžitá odezva z API. U synchronního importu bude odpověď vrácena, jakmile import skončí pomocí importSummary. U asynchronních importů však bude odpověď okamžitá a bude obsahovat odkaz, kde se klient může dotazovat na aktualizace importu.

U významných importů může být pro klienta výhodné použít asynchronní import, aby se vyhnul příliš dlouhému čekání na odpověď.

Příklady odezvy ASYNC jsou uvedeny níže. Odpověď SYNC najdete v sekci importSummary.

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Tracker job added",
    "response": {
        "responseType": "TrackerJob",
        "id": "LkXBUdIgbe3",
        "location": "https://play.dhis2.org/dev/api/tracker/jobs/LkXBUdIgbe3"
    }
}

CSV Events payload¶

In order to maintain compatibility with older versions of tracker, the API allows to import events using the CSV format. As this format does not allow list as field, every row of the CSV payload represents an event and a data value. So for events with multiple data values, the CSV file will have x rows per event where x is the number of data values in that event. Other fields that are lists as relationships and notes are not supported. To import a CSV payload, the content type of the request must be set to application/csv or text/csv.

CSV PAYLOAD example¶

Souhrn importu¶

Tracker API má dva primární koncové body pro spotřebitele, aby získali zpětnou vazbu z jejich importů. Tyto koncové body jsou nejrelevantnější pro úlohy asynchronního importu, ale jsou dostupné i pro úlohy synchronizace. Tyto koncové body vrátí buď protokol související s importem, nebo samotný souhrn importu.

Poznámka

Tyto koncové body se spoléhají na informace uložené v paměti aplikace. To znamená, že informace budou v určitých případech nedostupné, protože se aplikace restartuje nebo když se po tomto spustí velký počet požadavků na import.

Po odeslání požadavku na import trackeru můžeme přistupovat k následujícím koncovým bodům, abychom mohli sledovat průběh úlohy na základě protokolů:

GET /tracker/jobs/{uid}

REQUEST example¶

GET /tracker/jobs/mEfEaFSCKCC

RESPONSE example¶

[
  {
    "uid": "mEfEaFSCKCC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:06.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) finished in 6.00000 sec. Import:Done",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:05.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) commit completed in 1.00000 sec. Import:commit",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:04.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) programruleValidation completed in 1.00000 sec. Import:programruleValidation",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:03.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) programrule completed in 1.00000 sec. Import:programrule",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:02.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) validation completed in 1.00000 sec. Import:validation",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "DEBUG",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:01.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) preheat completed in 1.00000 sec. Import:preheat",
    "completed": true,
    "id": "mEfEaFSCKCC"
  },
  {
    "uid": "mEfEaFSCKCC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2021-01-01T00:00:00.00",
    "message": "TRACKER_IMPORT_JOB ( mEfEaFSCKCC ) started by admin ( xE7jOejl9FI ) Import:Start",
    "completed": true,
    "id": "mEfEaFSCKCC"
  }
]

Následující koncový bod navíc vrátí souhrn importu úlohy importu. Tento souhrn importu bude k dispozici až po dokončení importu:

GET /tracker/jobs/{uid}/report

REQUEST example¶

GET /tracker/jobs/mEfEaFSCKCC/report

RESPONSE example¶

datový obsah odezvy je stejný jako ten vrácený po požadavku na import synchronizace.

Poznámka

Oba koncové body se používají především pro asynchronní import; nicméně GET /tracker/jobs/{uid} by také fungovalo pro požadavky na synchronizaci, protože nakonec používá stejný proces importu a protokolování jako asynchronní požadavky.

Import Summary Structure¶

Souhrny importu mají v závislosti na požadovaném reportMode následující celkovou strukturu:

{
  "status": "...",
  "validationReport": { },
  "stats": { },
  "timingsStats": { },
  "bundleReport": { },
  "message" : { }
}

status

Vlastnost status souhrnu importu označuje celkový stav importu. Pokud se během importu nevyskytly žádné chyby nebo varování, je status hlášen jako OK. Přítomnost jakékoli chyby nebo varování v importu bude mít za následek stav typu ERROR nebo WARNING.

status je založen na přítomnosti nejvýznamnějšího validationReport. Nejvyšší význam má ERROR, následuje WARNING a nakonec OK. To znamená, že ERROR je hlášen, pokud byla během importu nalezena jediná chyba, bez ohledu na to, kolik varování se objevilo.

Poznámka

Pokud je import prováděn pomocí AtomicMode "OBJECT", kde import importuje jakákoli data bez chyb validace, bude celkový stav stále ERROR, pokud byly nalezeny nějaké chyby.

validationReport

Pokud se během importu vyskytly nějaké chyby nebo varování, validationReport může obsahovat errorReports a warningReports. Jsou-li k dispozici, poskytují podrobný seznam všech chyb nebo varování, se kterými se setkali.

Například chyba ověření při importu TRACKED_ENTITY:

{
  "validationReport": {
    "errorReports": [
      {
        "message": "Could not find TrackedEntityType: `Q9GufDoplCL`.",
        "errorCode": "E1005",
        "trackerType": "TRACKED_ENTITY",
        "uid": "Kj6vYde4LHh"
      },
      ...
    ],
    "warningReports" : [ ... ]
  }
}

The report contains a message and a code describing the actual error (See the error codes section for more information about errors). Additionally, the report includes the trackerType and uid, which aims to describe where in the data the error was found. In this case, there was a TRACKED_ENTITY with the uid Kj6vYde4LHh, which had a reference to a tracked entity type that was not found.

Note

When referring to the uid of tracker objects, they are labeled as their object names in the payload. For example, the uid of a tracked entity would in the payload have the name "trackedEntity". The same goes for "enrollment", "event" and "relationship" for enrollments, events, and relationships, respectively.

If no uid is provided in the payload, the import process will generate new uids. This means the error report might refer to a uid that does not exist in your payload.

Errors represent issues with the payload which the importer can not circumvent. Any errors will block that data from being imported. Warnings, on the other hand, are issues where it's safe to circumvent them, but the user should be made aware that it happened. Warnings will not block data from being imported.

stats

Statistiky poskytují rychlý přehled o importu. Po dokončení importu to budou skutečné počty představující, kolik dat bylo vytvořeno, aktualizováno, odstraněno nebo ignorováno.

Příklad:

{
  "stats": {
    "created": 2,
    "updated": 2,
    "deleted": 1,
    "ignored": 5,
    "total": 10
  }
}

updated označuje počet aktualizovaných objektů. Pokud má objekt v datové části nastaveno uid, bude se s ním zacházet jako s aktualizací, pokud stejné uid existuje v databázi.

deleted odkazuje na počet objektů odstraněných během importu. K odstranění dojde pouze tehdy, když je import nakonfigurován tak, aby smazal data, a pouze tehdy, když mají objekty v datové části nastavena existující uid.

ignored odkazuje na objekty, které nebyly trvalé. Objekty lze ignorovat z několika důvodů, například při snaze vytvořit něco, co již existuje. Ignorování by mělo být vždy bezpečné, takže pokud bylo něco ignorováno, nebylo to nutné, nebo to bylo způsobeno konfigurací importu.

timingsStats

timingStats představuje čas, který uplynul v různých krocích importu. Tyto statistiky neposkytují přesný celkový čas pro import, ale spíše čas strávený v kódu pro různé kroky.

timingStats jsou užitečné především při ladění importů, které způsobují problémy, abyste zjistili, která část importu má problémy.

{
  "timingsStats": {
    "timers": {
      "preheat": "0.234086 sec.",
      "preprocess": "0.000058 sec.",
      ...
      "totalImport": "0.236810 sec.",
      "validation": "0.001533 sec."
    }
  }
}

bundleReport

Když je import dokončen, bundleReport obsahuje všechny importované objekty sledování.

Například TRACKED_ENTITY:

{
  "bundleReport": {
    "typeReportMap": {
      "TRACKED_ENTITY": {
        "trackerType": "TRACKED_ENTITY",
        "stats": {
          "created": 1,
          "updated": 0,
          "deleted": 0,
          "ignored": 0,
          "total": 1
        },
        "objectReports": [
          {
            "trackerType": "TRACKED_ENTITY",
            "uid": "FkxTQC4EAKK",
            "index": 0,
            "errorReports": []
          }
        ]
      },
      ...
    }
  }
}

message

Pokud by import skončil náhle, message by obsahovala další informace o tom, co se stalo.

Import Summary Report Level¶

As previously stated, GET /tracker/jobs/{uid}/report can be retrieved using a specific reportMode parameter. By default the endpoint will return an importSummary with reportMode ERROR.

Kromě toho všechny reportModes v případě potřeby vrátí status, stats, bundleReport a message.

Kódy chyb¶

Existují různé chybové kódy pro různé chybové scénáře. Následující tabulka obsahuje seznam chybových kódů vržených z nového Tracker API spolu s chybovými zprávami a některými dalšími popisy. Zástupné symboly v chybových zprávách ({0},{1},{2}..) jsou obvykle uid, pokud není uvedeno jinak.

Ověření¶

Při importu dat pomocí importéru trackeru se provádí řada ověření, aby byla zajištěna platnost dat. Tato část popisuje některé z různých typů ověřování prováděného za účelem lepšího pochopení, pokud ověření vašeho importu selže.

Required properties¶

Každý z objektů trackeru má několik požadovaných vlastností, které musí být přítomny při importu dat. Úplný seznam požadovaných vlastností naleznete v sekci objektů sledování.

Při validaci požadovaných vlastností se obvykle bavíme o odkazech na jiná data nebo metadata. V těchto případech existují tři hlavní kritéria:

1. Reference je přítomna a není nulová v užitečném zatížení.
2. Odkaz ukazuje na správný typ dat a existuje v databázi
3. Uživatel má přístup k zobrazení reference

Pokud selže první podmínka, import selže se zprávou o chybějící referenci. Předpokládejme však, že odkaz odkazuje na něco, co neexistuje nebo ke kterému uživatel nemá přístup. V takovém případě budou mít oba případy za následek zprávu o tom, že reference nebyla nalezena.

Formats¶

Některé vlastnosti objektů sledování vyžadují specifický formát. Při importu dat je každá z těchto vlastností ověřena podle očekávaného formátu a vrátí různé chyby v závislosti na tom, která vlastnost má nesprávný formát. Některé příklady vlastností, které jsou takto ověřeny:

• UID (Pokrývají všechny odkazy na jiná data nebo metadata v DHIS2.)
• Termíny
• Geometrie (souřadnice musí odpovídat formátu určenému jeho typem)

User access¶

All data imported will be validated based on the metadata (Sharing) and the organisation units (Organisation Unit Scopes) referenced in the data. You can find more information about sharing and organisation unit scopes in the following sections.

Sdílení se ověřuje současně s vyhledáváním referencí v databázi. Metadata mimo přístup uživatele budou považována za neexistující. Import ověří všechna metadata odkazovaná v datech.

Organizační jednotky na druhé straně slouží dvojímu účelu. Primárně zajistí, že data lze importovat pouze při importu pro organizační jednotku, kterou má uživatel ve svém „rozsahu zachycení“. Za druhé, organizační jednotky se také používají k omezení dostupných programů. To znamená, že pokud se pokoušíte importovat data pro organizační jednotku, která nemá přístup k programu, který importujete, import bude neplatný.

Uživatelé s oprávněním ALL budou při importu dat ignorovat limity sdílení a rozsahů organizačních jednotek. Nemohou však importovat zápisy v organizačních jednotkách, které nemají přístup k programu zápisu.

Attribute and Data values¶

Atributy a datové hodnoty jsou součástí trasované entity a události. Atributy však mohou být propojeny s trasovanou entitou buď prostřednictvím jejího typu (TrackedEntityType) nebo jejího programu (Program). Kromě toho mohou být atributy také jedinečné.

Počáteční ověření provedené při importu má zajistit, aby hodnota zadaná pro atribut nebo datový prvek odpovídala očekávanému typu hodnoty. Předpokládejme například, že importujete hodnotu pro datový prvek s číselným typem. V takovém případě se očekává, že hodnota bude číselná. Jakékoli chyby související s neshodou mezi typem a hodnotou budou mít za následek stejný chybový kód, ale se specifickou zprávou související s typem porušení.

Kontrolují se také povinné atributy a hodnoty dat. V současné době není odstranění povinných atributů povoleno. Některé případy použití vyžadují, aby byly hodnoty odeslány samostatně, zatímco jiné vyžadují, aby byly všechny hodnoty odeslány jako jedna. Programy lze nakonfigurovat tak, aby buď ověřovaly povinné atributy ON_COMPLETE nebo ON_UPDATE_AND_INSERT, aby vyhovovaly těmto případům použití.

Import ověří jedinečné atributy v době importu. To znamená, že pokud je zadaná hodnota pro atribut v celém systému jedinečná, projde. Pokud však bude nalezena jedinečná hodnota, kterou používá jiná trasovaná entita než ta, která se importuje, selže.

Konfigurace¶

Poslední částí validací v importéru jsou validace na základě uživatelské konfigurace příslušných metadat. Další informace o každé konfiguraci naleznete v příslušných částech. Některé příklady konfigurovatelných ověření: - Typ prvku (pro geometrii) - Uživatelsky přiřaditelné události - Povolit budoucí data - Zapsat se jednou - A více.

Tyto konfigurace dále změní způsob provádění ověřování během importu.

Pravidla programu¶

Uživatelé mohou nakonfigurovat Pravidla programu, která přidává podmíněné chování do formulářů sledování. Kromě spouštění těchto pravidel v aplikacích sledování spustí importér sledování také výběr těchto pravidel. Vzhledem k tomu, že importer také používá tato pravidla, můžeme zajistit další úroveň ověření.

Ne všechny akce programových pravidel jsou podporovány, protože jsou vhodné pouze pro frontendovou prezentaci. Úplný seznam podporovaných akcí pravidel programu je uveden níže.

Programová pravidla se v importéru vyhodnocují stejným způsobem, jako se vyhodnocují v aplikacích Tracker. Abychom to shrnuli, při prosazování pravidel programu se berou v úvahu následující podmínky:

• Programové pravidlo musí být propojeno s importovanými daty. Například fáze programu nebo datový prvek.
• Podmínka programového pravidla musí být vyhodnocena jako true

Výsledky pravidel programu závisí na akcích definovaných v těchto pravidlech:

• Akce programových pravidel mohou skončit se 2 různými výsledky: Varování nebo Chyby.
• Chyby způsobí selhání ověření, zatímco varování budou hlášena jako zpráva v souhrnu importu.
  • Akce SHOWWARNING a WARNINGONCOMPLETION mohou generovat pouze varování.
  • SHOWERROR, ERRORONCOMPLETION, and SETMANDATORYFIELD actions can generate only Errors.
  • ASSIGN action can generate both Warnings and Errors.
  • Když akce přiřazuje hodnotu prázdnému prvku atributu/dat, vygeneruje se varování.
  • Když akce přiřazuje hodnotu atributu/datovému prvku, který již má stejnou hodnotu, která má být přiřazena, vygeneruje se varování.
  • When the action is assigning a value to an attribute/data element that already has a value and the value to be assigned is different, an error is generated unless the RULE_ENGINE_ASSIGN_OVERWRITE system setting is set to true.

Kromě toho mohou pravidla programu vést k vedlejším účinkům, jako je odesílání a plánování zpráv. Více informací o vedlejších účincích naleznete v následující části.

POZNÁMKA

Programová pravidla lze během importu přeskočit pomocí parametru skipProgramRules.

Vedlejší účinky¶

Po dokončení importu mohou být v důsledku importu spuštěny určité úlohy. Tyto úlohy označujeme jako „Vedlejší efekty“. Tyto úlohy provádějí operace, které neovlivňují samotný import.

Vedlejší efekty jsou úlohy, které běží odděleně od importu, ale jsou vždy spuštěny importem. Vzhledem k tomu, že vedlejší efekty jsou od importu odděleny, mohou selhat, i když je import úspěšný. Vedlejší efekty se navíc spouštějí pouze tehdy, když je import úspěšný, takže nemohou selhat naopak.

V současné době jsou podporovány následující vedlejší účinky:

NOTE

Certain configurations can control the execution of side effects. skipSideEffects flag can be set during the import to skip side effects entirely. This parameter can be useful if you import something you don't want to trigger notifications for, as an example.

Přiřadit uživatele k událostem¶

Konkrétní pracovní postupy těží z toho, že se s událostmi zachází jako s úkoly, a z tohoto důvodu můžete k události přiřadit uživatele.

Assigning a user to an event will not change the access or permissions for users but will create a link between the Event and the user. When an event has a user assigned, you can query events from the API using the assignedUser field as a parameter.

Když chcete přiřadit uživatele k události, jednoduše zadáte UID uživatele, kterého chcete přiřadit, do pole assignedUser. Viz následující příklad:

{
  ...
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "programStage": "nlXNK4b7LVr",
      "orgUnit": "O6uvpzGd5pu",
      "enrollment": "MNWZ6hnuhSw",
      "assignedUser" : "M0fCOxtkURr"
    }
  ],
  ...
}

In this example, the user with uid M0fCOxtkURr will be assigned to the Event with uid ZwwuwNp6gVd. Only one user can be assigned to a single event.

Chcete-li použít tuto funkci, musí mít příslušná fáze programu povoleno přiřazení uživatele a uid poskytnuté uživateli musí odkazovat na platného existujícího uživatele.

Tracker Export¶

Tracker export endpoints allow you to retrieve the previously imported objects which are:

• tracked entities
• events
• enrollments
• relationships

NOTE

• All these endpoints currently support JSON. CSV is only supported by tracked entities and events.

Common request parameters¶

The following endpoint supports standard parameters for pagination.

• Tracked Entities GET /api/tracker/trackedEntities
• Události GET /api/tracker/events
• Enrollments GET /api/tracker/enrollments
• Relationships GET /api/tracker/relationships

Request parameters for pagination¶

Caution

Be aware that the performance is directly related to the amount of data requested. Larger pages will take more time to return.

Request parameters for Organisational Unit selection mode¶

The available organisation unit selection modes are explained in the following table.

Request parameter to filter responses¶

All export 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 or patterns. A few possible fields filters are shown below. Refer to Metadata field filter for a more complete guide on how to use fields.

Příklady¶

Tracked Entities (GET /api/tracker/trackedEntities)¶

Dva koncové body jsou vyhrazeny trasovaným entitám:

• GET /api/tracker/trackedEntities
• načte trasované entity odpovídající daným kritériím
• GET /api/tracker/trackedEntities/{id}
• načte trasovanou entitu podle poskytnutého ID

Tracked Entities Collection endpoint GET /api/tracker/trackedEntities¶

Účelem tohoto koncového bodu je načíst trasované entity odpovídající kritériím zadaným klientem.

Koncový bod vrátí seznam trasovaných entit, které odpovídají parametrům požadavku.

Požádat o syntaxi¶

The available assigned user modes are explained in the following table.

Tabulka: Přiřazené uživatelské režimy

V dotazu se nerozlišují velká a malá písmena. Pro parametry dotazu platí následující pravidla.

• At least one organisation unit must be specified using the orgUnit parameter (one or many), or ouMode=ALL must be specified.

• Only one of the program and trackedEntity parameters can be specifikováno (nula nebo jedna).

• If programStatus is specified, then program must also be specifikováno.

• If followUp is specified, then program must also be specified.

• If enrollmentEnrolledAfter or enrollmentEnrolledBefore is specified then program must also be specified.

• Položky filtru lze zadat pouze jednou.

Example requests¶

A query for all instances associated with a specific organisation unit can look like this:

GET /api/tracker/trackedEntities?orgUnit=DiszpKrYNg8

To query for instances using one attribute with a filter and one attribute without a filter, with one organisation unit using the descendant organisation unit query mode:

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &attribure=AMpUYgxuCaE&orgUnit=DiszpKrYNg8;yMCshbaVExv

A query for instances where attributes are included in the response and one attribute is used as a filter:

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &filter=AMpUYgxuCaE:LIKE:Road
    &orgUnit=DiszpKrYNg8

A query where multiple operand and filters are specified for a filter item:

GET /api/tracker/trackedEntities?orgUnit=DiszpKrYNg8
    &program=ur1Edk5Oe2n
    &filter=lw1SqmMlnfh:GT:150
    &filter=lw1SqmMlnfh:LT:190

A query filter with a value that needs escaping and will be interpreted as :,/:

GET /api/tracker/trackedEntities?orgUnit=DiszpKrYNg8
    &program=ur1Edk5Oe2n
    &filter=lw1SqmMlnfh:EQ:/:/,//

To query on an attribute using multiple values in an IN filter:

GET /api/tracker/trackedEntities?orgUnit=DiszpKrYNg8
    &filter=dv3nChNSIxy:IN:Scott;Jimmy;Santiago

To constrain the response to instances which are part of a specific program you can include a program query parameter:

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS
    &program=ur1Edk5Oe2n

Chcete-li zadat data zápisu programu jako součást dotazu:

GET /api/tracker/trackedEntities?
    &orgUnit=O6uvpzGd5pu&program=ur1Edk5Oe2n
    &enrollmentEnrolledAfter=2013-01-01
    &enrollmentEnrolledBefore=2013-09-01

To constrain the response to instances of a specific tracked entity you can include a tracked entity query parameter:

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &orgUnit=O6uvpzGd5pu
    &ouMode=DESCENDANTS
    &trackedEntity=cyl5vuJ5ETQ

By default the instances are returned in pages of size 50, to change this you can use the page and pageSize query parameters:

GET /api/tracker/trackedEntities?filter=zHXD5Ve1Efw:EQ:A
    &orgUnit=O6uvpzGd5pu
    &ouMode=DESCENDANTS
    &page=2&pageSize=3

K filtrování můžete použít řadu operátorů:

Formát odpovědi¶

Odpověď JSON může vypadat následovně.

Responses can be filtered on desired fields, see Request parameter to filter responses

{
  "instances": [
    {
      "trackedEntity": "IzHblRD2sDH",
      "trackedEntityType": "nEenWmSyUEp",
      "createdAt": "2014-03-26T15:40:36.669",
      "createdAtClient": "2014-03-26T15:40:36.669",
      "updatedAt": "2014-03-28T12:28:17.544",
      "orgUnit": "g8upMTyEZGZ",
      "inactive": false,
      "deleted": false,
      "relationships": [],
      "attributes": [
        {
          "attribute": "VqEFza8wbwA",
          "code": "MMD_PER_ADR1",
          "displayName": "Address",
          "createdAt": "2016-01-12T00:00:00.000",
          "updatedAt": "2016-01-12T00:00:00.000",
          "valueType": "TEXT",
          "value": "1061 Marconi St"
        },
        {
          "attribute": "RG7uGl4w5Jq",
          "code": "Longitude",
          "displayName": "Longitude",
          "createdAt": "2016-01-12T00:00:00.000",
          "updatedAt": "2016-01-12T00:00:00.000",
          "valueType": "TEXT",
          "value": "27.866613"
        },
        ...,
        ...,
      ],
      "enrollments": [],
      "programOwners": []
    }
  ],
  "page": 1,
  "total": 39,
  "pageSize": 1
}

Tracked Entities single object endpoint GET /api/tracker/trackedEntities/{uid}¶

Účelem tohoto koncového bodu je načíst jednu trasovanou entitu s jejím uid.

Požádat o syntaxi¶

GET /api/tracker/trackedEntities/{uid}?program={programUid}&fields={fields}

Example requests¶

Dotaz na instanci trasované entity:

GET /api/tracker/trackedEntities/IzHblRD2sDH?program=ur1Edk5Oe2n&fields=*

Formát odpovědi¶

Tento koncový bod podporuje vracení dílčích objektů, když je předán parametr požadavku fields, když je požadován formát json. V případě csv nemá parametr požadavku fields žádný účinek a odpověď bude vždy obsahovat stejná pole, která jsou: - trackedEntity (Identifier) - trackedEntityType (Identifier) - createdAt (Datetime) - createdAtClient (Datetime) - updatedAt (Datetime) - updatedAtClient (Datetime) - orgUnit (Identifier) - inactive (boolean) - deleted (boolean) - potentialDuplicate (boolean) - geometry (WKT, https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) - storedBy (String) - createdBy (Username of user) - updatedBy (Username of user) - attributes (each valid attribute listed as another column)

Příklad odpovědi json:

{
    "trackedEntity": "IzHblRD2sDH",
    "trackedEntityType": "nEenWmSyUEp",
    "createdAt": "2014-03-26T15:40:36.669",
    "updatedAt": "2014-03-28T12:28:17.544",
    "orgUnit": "g8upMTyEZGZ",
    "inactive": false,
    "deleted": false,
    "relationships": [],
    "attributes": [
        {
            "attribute": "w75KJ2mc4zz",
            "code": "MMD_PER_NAM",
            "displayName": "First name",
            "createdAt": "2016-01-12T09:10:26.986",
            "updatedAt": "2016-01-12T09:10:35.884",
            "valueType": "TEXT",
            "value": "Wegahta"
        },
        {
            "attribute": "zDhUuAYrxNC",
            "displayName": "Last name",
            "createdAt": "2016-01-12T09:10:26.986",
            "updatedAt": "2016-01-12T09:10:35.884",
            "valueType": "TEXT",
            "value": "Goytiom"
        }
    ],
    "enrollments": [
        {
            "enrollment": "uT5ZysTES7j",
            "createdAt": "2017-03-28T12:28:17.539",
            "createdAtClient": "2016-03-28T12:28:17.539",
            "updatedAt": "2017-03-28T12:28:17.544",
            "trackedEntity": "IzHblRD2sDH",
            "trackedEntityType": "nEenWmSyUEp",
            "program": "ur1Edk5Oe2n",
            "status": "ACTIVE",
            "orgUnit": "g8upMTyEZGZ",
            "orgUnitName": "Njandama MCHP",
            "enrolledAt": "2020-11-10T12:28:17.532",
            "occurredAt": "2020-10-12T12:28:17.532",
            "followUp": false,
            "deleted": false,
            "events": [
                {
                    "event": "ixDYEGrNQeH",
                    "status": "ACTIVE",
                    "program": "ur1Edk5Oe2n",
                    "programStage": "ZkbAXlQUYJG",
                    "enrollment": "uT5ZysTES7j",
                    "enrollmentStatus": "ACTIVE",
                    "trackedEntity": "IzHblRD2sDH",
                    "relationships": [],
                    "scheduledAt": "2019-10-12T12:28:17.532",
                    "followup": false,
                    "deleted": false,
                    "createdAt": "2017-03-28T12:28:17.542",
                    "createdAtClient": "2016-03-28T12:28:17.542",
                    "updatedAt": "2017-03-28T12:28:17.542",
                    "attributeOptionCombo": "HllvX50cXC0",
                    "attributeCategoryOptions": "xYerKDKCefk",
                    "dataValues": [],
                    "notes": []
                }
            ],
            "relationships": [],
            "attributes": [],
            "notes": []
        }
    ],
    "programOwners": [
        {
            "orgUnit": "g8upMTyEZGZ",
            "trackedEntity": "IzHblRD2sDH",
            "program": "ur1Edk5Oe2n"
        }
    ]
}

Events (GET /api/tracker/events)¶

Two endpoints are dedicated to events:

• GET /api/tracker/events
  • načte události odpovídající zadaným kritériím
• GET /api/tracker/events/{id}
  • načte událost se zadaným ID

Events Collection endpoint GET /api/tracker/events¶

Vrátí seznam událostí na základě poskytnutých filtrů.

Note

If the query contains neither attributeCC nor attributeCos, the server returns events for all attribute option combos where the user has read access.

Example requests¶

Dotaz na všechny události s potomky konkrétní organizační jednotky:

GET /api/tracker/events?orgUnit=YuQRtpLP10I&ouMode=CHILDREN

The query for all events with all descendants of a particular organisation unit, implying all organisation units in the sub-hierarchy:

GET /api/tracker/events?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS

Dotaz na všechny události s určitou programovou a organizační jednotkou:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

Query for all events with a certain program and organisation unit, sorting by due date ascending:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=dueDate

Query for the 10 events with the newest event date in a certain program and organisation unit - by paging and ordering by due date descending:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  &order=eventDate:desc&pageSize=10&page=1

Query for all events with a certain program and organisation unit for a specific tracked entity instance:

GET /api/tracker/events?orgUnit=DiszpKrYNg8
  &program=eBAyeGv0exc&trackedEntityInstance=gfVxE3ALA9m

Query for all events with a certain program and organisation unit older or equal to 2014-02-03:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&endDate=2014-02-03

Query for all events with a certain program stage, organisation unit and tracked entity instance in the year 2014:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  &trackedEntityInstance=gfVxE3ALA9m&occurredAfter=2014-01-01&occurredBefore=2014-12-31

A query where multiple operand and filters are specified for a data element UID:

GET /api/tracker/events?orgUnit=DiszpKrYNg8
    &program=lxAQ7Zs9VYR
    &filter=lw1SqmMlnfh:GT:150
    &filter=lw1SqmMlnfh:LT:190

A query filter with a value that needs escaping and will be interpreted as :,/:

GET /api/tracker/events?orgUnit=DiszpKrYNg8
    &program=lxAQ7Zs9VYR
    &filter=lw1SqmMlnfh:EQ:/:/,//

Formát odpovědi¶

Odpověď JSON může vypadat následovně.

{
    "instances": [
        {
            "event": "rgWr86qs0sI",
            "status": "ACTIVE",
            "program": "kla3mAPgvCH",
            "programStage": "aNLq9ZYoy9W",
            "orgUnit": "DiszpKrYNg8",
            "orgUnitName": "Ngelehun CHC",
            "relationships": [],
            "occurredAt": "2021-10-12T00:00:00.000",
            "followup": false,
            "deleted": false,
            "createdAt": "2018-10-20T12:09:19.492",
            "updatedAt": "2018-10-20T12:09:19.492",
            "attributeOptionCombo": "amw2rQP6r6M",
            "attributeCategoryOptions": "RkbOhHwiOgW",
            "dataValues": [
                {
                    "createdAt": "2015-10-20T12:09:19.640",
                    "updatedAt": "2015-10-20T12:09:19.640",
                    "storedBy": "system",
                    "providedElsewhere": false,
                    "dataElement": "HyJL2Lt37jN",
                    "value": "12"
                },
              ...
            ],
            "notes": []
        }
    ],
    "page": 1,
    "pageSize": 1
}

Odpověď CSV může vypadat následovně.

|event|status|program|programStage|enrollment|orgUnit|occurredAt|scheduledAt|dataElement|value|storedBy|providedElsewhere
|---|---|---|---|---|---|---|---|---|---|---|---|
|V1CerIi3sdL|COMPLETED|IpHINAT79UW|A03MvHHogjR|CCBLMntFuzb|DiszpKrYNg8|2020-02-26T23:00:00Z|2020-02-27T23:00:00Z|a3kGcGDCuk6|11|admin|false
|V1CerIi3sdL|COMPLETED|IpHINAT79UW|A03MvHHogjR|CCBLMntFuzb|DiszpKrYNg8|2020-02-26T23:00:00Z|2020-02-27T23:00:00Z|mB2QHw1tU96|[-11.566044,9.477801]|admin|false

Koncový bod jednoho objektu událostí GET /api/tracker/events/{uid}¶

Účelem tohoto koncového bodu je načíst jednu událost s jejím uid.

Požádat o syntaxi¶

GET /api/tracker/events/{uid}?fields={fields}

Example requests¶

Dotaz na událost:

GET /api/tracker/events/rgWr86qs0sI

Formát odpovědi¶

{
  "event": "rgWr86qs0sI",
  "status": "ACTIVE",
  "program": "kla3mAPgvCH",
  "programStage": "aNLq9ZYoy9W",
  "enrollment": "Lo3SHzCnMSm",
  "enrollmentStatus": "ACTIVE",
  "orgUnit": "DiszpKrYNg8",
  "orgUnitName": "Ngelehun CHC",
  "relationships": [],
  "occurredAt": "2021-10-12T00:00:00.000",
  "followup": false,
  "deleted": false,
  "createdAt": "2018-10-20T12:09:19.492",
  "createdAtClient": "2017-10-20T12:09:19.492",
  "updatedAt": "2018-10-20T12:09:19.492",
  "attributeOptionCombo": "amw2rQP6r6M",
  "attributeCategoryOptions": "RkbOhHwiOgW",
  "dataValues": [
    {
      "createdAt": "2015-10-20T12:09:19.640",
      "updatedAt": "2015-10-20T12:09:19.640",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "HyJL2Lt37jN",
      "value": "12"
    },
    {
      "createdAt": "2015-10-20T12:09:19.514",
      "updatedAt": "2015-10-20T12:09:19.514",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "b6dOUjAarHD",
      "value": "213"
    },
    {
      "createdAt": "2015-10-20T12:09:19.626",
      "updatedAt": "2015-10-20T12:09:19.626",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "UwCXONyUtGs",
      "value": "3"
    },
    {
      "createdAt": "2015-10-20T12:09:19.542",
      "updatedAt": "2015-10-20T12:09:19.542",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "fqnXmRYo5Cz",
      "value": "123"
    },
    {
      "createdAt": "2015-10-20T12:09:19.614",
      "updatedAt": "2015-10-20T12:09:19.614",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "Qz3kfeKgLgL",
      "value": "23"
    },
    {
      "createdAt": "2015-10-20T12:09:19.528",
      "updatedAt": "2015-10-20T12:09:19.528",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "W7aC8jLASW8",
      "value": "12"
    },
    {
      "createdAt": "2015-10-20T12:09:19.599",
      "updatedAt": "2015-10-20T12:09:19.599",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "HrJmqlBqTFG",
      "value": "3"
    }
  ],
  "notes": []
}

Enrollments (GET /api/tracker/enrollments)¶

Pro zápisy jsou vyhrazeny dva koncové body:

• GET /api/tracker/enrollments
  • načte zápisy odpovídající zadaným kritériím
• GET /api/tracker/enrollments/{id}
  • načte zápis podle poskytnutého ID

Enrollment Collection endpoint GET /api/tracker/enrollments¶

Vrátí seznam událostí na základě filtrů.

V dotazu se nerozlišují velká a malá písmena. Následující pravidla platí pro parametry dotazu.

• At least one organisation unit must be specified using the orgUnit parameter (one or many), or ouMode=ALL must be specified.

• Může být pouze jeden z parametrů program a trackedEntity specifikováno (nula nebo jedna).

• If programStatus is specified, then program must also be specifikováno.

• If followUp is specified, then program must also be specified.

• If enrolledAfter or enrolledBefore is specified, then program must also be specified.

Example requests¶

A query for all enrollments associated with a specific organisation unit can look like this:

GET /api/tracker/enrollments?orgUnit=DiszpKrYNg8

To constrain the response to enrollments which are part of a specific program you can include a program query parameter:

GET /api/tracker/enrollments?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

Chcete-li zadat data zápisu programu jako součást dotazu:

GET /api/tracker/enrollments?&orgUnit=O6uvpzGd5pu&program=ur1Edk5Oe2n
  &enrolledAfter=2013-01-01&enrolledBefore=2013-09-01

To constrain the response to enrollments of a specific tracked entity you can include a tracked entity query parameter:

GET /api/tracker/enrollments?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS&trackedEntity=cyl5vuJ5ETQ

To constrain the response to enrollments of a specific tracked entity you can include a tracked entity instance query parameter, in In this case, we have restricted it to available enrollments viewable for current user:

GET /api/tracker/enrollments?ouMode=ACCESSIBLE&trackedEntity=tphfdyIiVL6

Formát odpovědi¶

Odpověď JSON může vypadat následovně.

{
  "instances": [
    {
      "enrollment": "iKaBMOyq7QQ",
      "createdAt": "2017-03-28T12:28:19.812",
      "createdAtClient": "2016-03-28T12:28:19.812",
      "updatedAt": "2017-03-28T12:28:19.817",
      "trackedEntity": "PpqV8ytvW5i",
      "trackedEntityType": "nEenWmSyUEp",
      "program": "ur1Edk5Oe2n",
      "status": "ACTIVE",
      "orgUnit": "NnQpISrLYWZ",
      "orgUnitName": "Govt. Hosp. Bonthe",
      "enrolledAt": "2020-10-23T12:28:19.805",
      "occurredAt": "2020-10-07T12:28:19.805",
      "followUp": false,
      "deleted": false,
      "events": [],
      "relationships": [],
      "attributes": [],
      "notes": []
    }
  ],
  "page": 1,
  "total": 1,
  "pageSize": 5
}

Koncový bod registrace jednoho objektu GET /api/tracker/enrollments/{uid}¶

Účelem tohoto koncového bodu je načíst jednu prohlášku s jejím uid.

Požádat o syntaxi¶

GET /api/tracker/enrollment/{uid}

Example requests¶

Dotaz na Zápis:

GET /api/tracker/enrollments/iKaBMOyq7QQ

Formát odpovědi¶

{
  "enrollment": "iKaBMOyq7QQ",
  "createdAt": "2017-03-28T12:28:19.812",
  "createdAtClient": "2016-03-28T12:28:19.812",
  "updatedAt": "2017-03-28T12:28:19.817",
  "trackedEntity": "PpqV8ytvW5i",
  "trackedEntityType": "nEenWmSyUEp",
  "program": "ur1Edk5Oe2n",
  "status": "ACTIVE",
  "orgUnit": "NnQpISrLYWZ",
  "orgUnitName": "Govt. Hosp. Bonthe",
  "enrolledAt": "2020-10-23T12:28:19.805",
  "occurredAt": "2020-10-07T12:28:19.805",
  "followUp": false,
  "deleted": false,
  "events": [],
  "relationships": [],
  "attributes": [],
  "notes": []
}

Relationships (GET /api/tracker/relationships)¶

Relationships are links between two entities in the Tracker. These entities can be tracked entity instances, enrollments, and events.

Účelem tohoto koncového bodu je načíst vztahy mezi objekty.

Na rozdíl od jiných koncových bodů trasovaných objektů vztahy odhalují pouze jeden koncový bod:

• GET /api/tracker/relationships?[trackedEntity={trackedEntityUid}|enrollment={enrollmentUid}|event={eventUid}]&fields=[fields]

Request parameters¶

Následující pravidla platí pro parametry dotazu.

• lze předat pouze jeden parametr mezi trackedEntity, enrollment, event

NOTE

Using tracked entity, Enrollment or Event params, will return any relationship where the trackedEntity, enrollment or event is part of the relationship (either from or to). As long as user has access, that is.

Example response¶

{
  "instances": [
    {
      "relationship": "SSfIicJKbh5",
      "relationshipType": "Mv8R4MPcNcX",
      "from": {
        "trackedEntity": {
          "trackedEntity": "neR4cmMY22o"
        }
      },
      "to": {
        "trackedEntity": {
          "trackedEntity": "rEYUGH97Ssd"
        }
      }
    },
    {
      "relationship": "S9kZGYPKk3x",
      "relationshipType": "Mv8R4MPcNcX",
      "from": {
        "trackedEntity": {
          "trackedEntity": "neR4cmMY22o"
        }
      },
      "to": {
        "trackedEntity": {
          "trackedEntity": "k8TU70vWtnP"
        }
      }
    }
  ],
  "page": 1,
  "pageSize": 2
}

Tracker Access Control¶

Tracker má několik různých konceptů, pokud jde o řízení přístupu, jako je sdílení, rozsahy organizačních jednotek, vlastnictví a úrovně přístupu. Následující části poskytují krátký úvod k různým tématům.

Sdílení metadat¶

Nastavení sdílení je standardní funkcí DHIS2, která se vztahuje jak na Tracker, tak na Aggregate metadata / data, stejně jako na ovládací panely a položky vizualizace. Jádrem sdílení je schopnost definovat, kdo co může vidět / dělat. Obecně existuje pět možných konfigurací sdílení – žádný přístup, čtení metadat, zápis metadat, čtení dat a zápis dat. Tyto konfigurace přístupu lze udělit na úrovni uživatele a/nebo skupiny uživatelů (pro větší flexibilitu). Se zaměřením na Tracker jsou zvláště důležitá následující metadata a jejich nastavení sdílení: Datový prvek, Možnost kategorie, Program, Fáze programu, Typ trasované entity, Atribut trasované entity a také ovládací panely a položky ovládacího panelu související s Trackerem.

Jak funguje sdílení, je jednoduché - nastavení se vynucuje během procesu importu/exportu dat Trackeru. Abyste mohli číst hodnotu, musíte mít přístup ke čtení dat. Pokud se od uživatele očekává, že bude upravovat data, musí mít přístup k zápisu dat. Podobně, pokud se od uživatele očekává úprava metadat, je nezbytné udělit přístup pro zápis metadat.

Jedním z kritických bodů u dat Tracker je potřeba mít holistický přístup. Uživatel například nebude moci zobrazit hodnotu datového prvku, pokud bude mít přístup pro čtení pouze k datovému prvku. Uživatel potřebuje načíst data, aby měl přístup k nadřazené programové ploše a programu, kam tento datový prvek patří. Stejné je to s kombinací možností kategorie. V Trackeru událost souvisí s AttributeOptionCombo, který se skládá z kombinace možností kategorie. Proto, aby uživatel mohl číst data události, potřebuje mít přístup ke čtení dat ke všem možnostem kategorií a odpovídajícím kategoriím, které tvoří AttributeOptionCombo dané události. Pokud uživatel nemá přístup pouze k jedné možnosti kategorie nebo kategorii, nemá přístup k celé události.

Pokud jde o přístup k datům zápisu, je nezbytné mít nejprve přístup k trasované entitě. Přístup k trasované entitě je řízen prostřednictvím nastavení sdílení programu, typu trasované entity a atributu trasované entity. Po zpřístupnění Zápisu je možné přistupovat k datům událostí, opět v závislosti na nastavení Fáze programu a nastavení sdílení datových prvků.

Dalším důležitým bodem ke zvážení je, jak zmapovat přístup k různým fázím programu programu. Někdy se můžeme ocitnout v situaci, kdy potřebujeme udělit přístup ke konkrétní fázi – například „Lab Result“ – určité skupině uživatelů (Lab Technicians). V této situaci můžeme poskytnout přístup k zápisu dat do fáze „Lab Result“, pravděpodobně data načtená do jedné nebo více fází pro případ, že chceme, aby laboratorní technici četli další lékařské výsledky, nebo žádný přístup, pokud si myslíme, že to pro laboratorní techniky není nutné. zobrazit data jiná než související s laboratoří.

Stručně řečeno, DHIS2 má jemné nastavení sdílení, které můžeme použít k implementaci mechanismů řízení přístupu na úrovni dat i metadat. Tato nastavení sdílení lze použít přímo na úrovni uživatele nebo na úrovni skupiny uživatelů. Jak přesně nastavení sdílení použít, závisí na konkrétním případu použití.

Podrobnější informace o sdílení dat najdete v Sdílení dat.

Rozsahy organizační jednotky¶

Organizační jednotky jsou jedním z nejzákladnějších objektů v DHIS2. Definují vesmír, ve kterém může uživatel zaznamenávat a/nebo číst data. Existují tři typy organizačních jednotek, které lze přiřadit uživateli. Jedná se o sběr dat, zobrazení dat a vyhledávání trackerů. Jak název napovídá, tyto organizační jednotky definují rozsah, ve kterém může uživatel provádět příslušné operace.

Pro další doladění rozsahu však DHIS2 Tracker zavádí koncept, který nazýváme OrganisationUnitSelectionMode. Takový režim se často používá při exportu objektů trackeru. Pokud má například uživatel určitý rozsah vyhledávání trackeru, znamená to, že musíme tento rozsah použít pokaždé, když se uživatel pokusí vyhledat objekt trackeru, registrace nebo události? Nebo má uživatel zájem omezit vyhledávání pouze na vybranou organizační jednotku nebo celý rozsah zachycené organizační jednotky a tak dále.

Users can do the fine-tuning by passing a specific value of ouMode in their API request:

api/tracker/trackedEntities?orgUnit=UID&ouMode=specific_organisation_unit_selection_mode

Currently, there are six selection modes available: SELECTED, CHILDREN, DESCENDANTS, CAPTURE, ACCESSIBLE, and ALL.

1. SELECTED: as the name implies, all operations intended by the requesting API narrow down to the selected organisation unit.
2. CHILDREN: under this mode, the organisation unit scope will be constructed using the selected organisation unit and its immediate children.
3. DESCENDANTS: here, the selected organisation unit and everything underneath it, not just the immediate children, constitute the data operation universe.
4. CAPTURE: jak název napovídá, organizační jednotky přiřazené k zachycení dat uživatele tvoří vesmír. Všimněte si, že ze tří organizačních jednotek, které lze přiřadit k zachycení uživatelských dat, je povinná. Pokud uživatel nemá organizační jednotky pro zobrazení dat a vyhledávání pomocí trackeru, systém se vrátí ke sběru dat. Tímto způsobem máme vždy jistotu, že uživatel má alespoň jeden vesmír.
5. ACCESSIBLE: technicky jde o stejný rozsah jako u organizačních jednotek vyhledávání sledovače uživatele.
6. ALL: the name ALL makes perfect sense if we are dealing with a superuser. For super users, this scope means the entire organisation unit available in the system. However, for non-superusers, ALL boils down to ACCESSIBLE organisation units.

It makes little sense to pass these modes at the time of tracker import operations. Because when writing tracker data, each of the objects needs to have a specific organisation unit attached to them. The system will then ensure if each of the mentioned organisation units falls under the CAPTURE scope. If not, the system will simply reject the write operation.

Note that there is 4 type of organisation unit associations relevant for Tracker objects. A TrackedEntity has an organisation unit, commonly referred to as the Registration Organisation unit. Enrollments have an organisation unit associated with them. Events also have an organisation unit associated with them. There is also an Owner organisation unit for a TrackedEntity-Program combination.

When fetching Tracker objects, depending on the context, the organisation unit scope is applied to one of the above four organisation unit associations.

For example, when retrieving TrackedEntities without the context of a program, the organisation unit scope is applied to the registration organisation unit of the TrackedEntity. Whereas, when retrieving TrackedEntities, including specific program data, the organisation unit scope is applied to the Owner organisation unit.

• Explain how they relate to ownership - Link to Program Ownership

Tracker Program Ownership¶

A new concept called Tracker Ownership is introduced from 2.30. This introduces a new organisation unit association for a TrackedEntity - Program combination. We call this the Owner (or Owning) Organisation unit of a TrackedEntity in the context of a Program. The Owner organisation unit is used to decide access privileges when reading and writing tracker data related to a program. This, along with the Program's Access Level configuration, decides the access behavior for Program-related data (Enrollments and Events). A user can access a TrackedEntity's Program data if the corresponding Owner OrganisationUnit for that TrackedEntity-Program combination falls under the user's organisation unit scope (Search/Capture). For Programs that are configured with access level OPEN or AUDITED , the Owner OrganisationUnit has to be in the user's search scope. For Programs that are configured with access level PROTECTED or CLOSED , the Owner OrganisationUnit has to be in the user's capture scope to be able to access the corresponding program data for the specific tracked entity.

When requesting tracked entities without specifying a program, the response will include only tracked entities that satisfy metadata sharing settings and one of the following criteria: - The tracked entity is enrolled in at least one program the user has data access to, and the user has access to the owner organisation unit. - The tracked entity is not enrolled in any program the user has data access to, but the user has access to the tracked entity registering organisation unit.

Tracker Ownership Override: Break the Glass¶

It is possible to temporarily override the ownership privilege for a program that is configured with an access level of PROTECTED. Any user with the org unit owner within their search scope, can temporarily access the program-related data by providing a reason for accessing it.

This act of temporarily gaining access is termed breaking the glass. Currently, temporary access is granted for 3 hours. DHIS2 audits breaking the glass along with the reason specified by the user. It is not possible to gain temporary access to a program that has been configured with an access level of CLOSED.

To break the glass for a TrackedEntity-Program combination, the following POST request can be used:

/api/33/tracker/ownership/override?trackedEntityInstance=DiszpKrYNg8
  &program=eBAyeGv0exc&reason=patient+showed+up+for+emergency+care

Převod vlastnictví trasovače¶

It is possible to transfer the ownership of a TrackedEntity-Program from one organisation unit to another. This will be useful in case of patient referrals or migrations. Only a user who has Ownership access (or temporary access by breaking the glass) can transfer the ownership. To transfer ownership of a TrackedEntity-Program to another organisation unit, the following PUT request can be used:

/api/33/tracker/ownership/transfer?trackedEntityInstance=DiszpKrYNg8
  &program=eBAyeGv0exc&ou=EJNxP3WreNP

Úroveň přístupu¶

DHIS2 treats Tracker data with an extra level of protection. In addition to the standard feature of metadata and data protection through sharing settings, Tracker data are shielded with additional access level protection mechanisms. Currently, there are four access levels that can be configured for a Program: Open, Audited, Protected, and Closed.

Tyto úrovně přístupu se spouštějí pouze tehdy, když se uživatelé pokusí o interakci s daty programu, konkrétně s daty pro zápisy a události. Odlišná konfigurace přístupové úrovně pro Program je určitým stupněm otevřenosti (nebo uzavřenosti) dat programu. Všimněte si, že všechna ostatní nastavení sdílení jsou stále respektována a úroveň přístupu je pouze další vrstvou řízení přístupu. Zde je krátký popis čtyř úrovní přístupu, které lze pro Program nakonfigurovat.

1. Open: This access level is the least restricted among the access levels. Data inside an OPEN program can be accessed and modified by users if the Owner organisation unit falls under the user's search scope. With this access level, accessing and modifying data outside the capture scope is possible without any justification or consequence.
2. Auditováno: Toto je stejné jako úroveň otevřeného přístupu. Rozdíl je v tom, že systém automaticky přidá záznam auditního protokolu k datům, ke kterým přistupuje konkrétní uživatel.
3. Chráněno: Tato úroveň přístupu je mírně omezenější. K datům uvnitř CHRÁNĚNÉHO programu mohou uživatelé přistupovat pouze v případě, že organizační jednotka vlastníka spadá do rozsahu zachycení uživatele. Uživatel, který má v oboru vyhledávání pouze organizační jednotku Owner, však může získat dočasné vlastnictví rozbitím skla. Uživatel musí poskytnout odůvodnění, proč přistupuje k daným datům. Systém poté vloží protokol o zdůvodnění i auditu přístupu a poskytne uživateli dočasný přístup na 3 hodiny. Pamatujte, že při rozbití skla zůstane organizační jednotka vlastníka nezměněna a pouze uživatel, který rozbil sklo, získá dočasný přístup.
4. Zavřeno: Toto je nejvíce omezená úroveň přístupu. Data zaznamenaná v rámci programů nakonfigurovaných s úrovní přístupu ZAVŘENO nebudou přístupná, pokud organizační jednotka vlastníka nespadá do rozsahu zachycení uživatele. V této konfiguraci také není možné rozbít sklo nebo získat dočasné vlastnictví. Upozorňujeme, že je stále možné převést vlastnictví na jinou organizační jednotku. Pouze uživatel, který má přístup k datům, může převést vlastnictví kombinace TrackedEntity-Program na jinou organizační jednotku. Pokud je vlastnictví převedeno, je aktualizována organizační jednotka vlastníka.