Tracker (deprecated APIs)¶

Caution

Tracker has been re-implemented in DHIS2 2.36. The new endpoints are documented at Tracker.

Endpoints

• GET/POST/PUT/DELETE /api/trackedEntityInstance
• GET/POST/PUT/DELETE /api/enrollments
• GET/POST/PUT/DELETE /api/events
• GET/POST/PUT/DELETE /api/relationships

will be removed in version 42!

• If you plan to use the tracker endpoints use the new endpoints described in Tracker
• If you are still using the deprecated tracker endpoints in production, please 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.

Migrating to new tracker endpoints¶

The following sections highlight the important differences between the deprecated endpoints.

• GET/POST/PUT/DELETE /api/trackedEntityInstance
• GET/POST/PUT/DELETE /api/enrollments
• GET/POST/PUT/DELETE /api/events
• GET/POST/PUT/DELETE /api/relationships

and the newly introduced endpoints

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

Property names¶

API property names have changed so they are consistent across all the endpoints. The following table lists the old and new property names.

Note

Property assignedUser was a string before and is now an object of the following shape (type User):

{
   "assignedUser": {
     "uid": "ABCDEF12345",
     "username": "username",
     "firstName": "John",
     "surname": "Doe"
   }
}

Semicolon as separator for identifiers (UID)¶

Fields or query parameter accepting multiple values like UIDs are now consistently separated by comma instead of semicolon. This is to ensure UIDs are consistently separated by comma across all DHIS2 endpoints.

The following fields are affected

• event.attributeCategoryOptions (as well as an event returned as part of a relationship from/to)

Tracker import changelog (POST)¶

The previous tracker import endpoints

• POST/PUT/DELETE /api/trackedEntityInstance
• POST/PUT/DELETE /api/enrollments
• POST/PUT/DELETE /api/events
• POST/PUT/DELETE /api/relationships

are replaced by the new endpoint

• POST /api/tracker

Tracker Import describes how to use this new endpoint.

Tracker export changelog (GET)¶

In addition to the changed names shown in Property names some request parameters have been changed as well.

The following tables list the differences in old and new request parameters for GET endpoints.

Request parameter changes for GET /api/tracker/trackedEntities¶

Request parameter changes for GET /api/tracker/enrollments¶

Request parameter changes for GET /api/tracker/events¶

Request parameter changes for GET /api/tracker/relationships¶

API Tracker Web¶

Tracker Web API consists of 3 endpoints that have full CRUD (create, read, update, delete) support. The 3 endpoints are /api/trackedEntityInstances, /api/enrollments and /api/events and they are responsible for tracked entity instance, enrollment and event items.

Gerenciamento de instância de entidade rastreada¶

Tracked entity instances have full CRUD support in the API. Together with the API for enrollment most operations needed for working with tracked entity instances and programs are supported.

/ api / 33 / trackedEntityInstances

Criar uma nova instância de entidade rastreada¶

For creating a new person in the system, you will be working with the trackedEntityInstances resource. A template payload can be seen below:

{
  "trackedEntity": "tracked-entity-id",
  "orgUnit": "org-unit-id",
  "geometry": "<Geo JSON>",
  "attributes": [{
    "attribute": "attribute-id",
    "value": "attribute-value"
  }]
}

The field "geometry" accepts a GeoJson object, where the type of the GeoJson have to match the featureType of the TrackedEntityType definition. An example GeoJson object looks like this:

{
  "type": "Point",
  "coordinates": [1, 1]
}

The "coordinates" field was introduced in 2.29, and accepts a coordinate or a polygon as a value.

For getting the IDs for relationship and attributes you can have a look at the respective resources relationshipTypes, trackedEntityAttributes. To create a tracked entity instance you must use the HTTP POST method. You can post the payload the following URL:

/ api / trackedEntityInstances

For example, let us create a new instance of a person tracked entity and specify its first name and last name attributes:

{
  "trackedEntity": "nEenWmSyUEp",
  "orgUnit": "DiszpKrYNg8",
  "attributes": [
    {
      "attribute": "w75KJ2mc4zz",
      "value": "Joe"
    },
    {
      "attribute": "zDhUuAYrxNC",
      "value": "Smith"
    }
  ]
}

Para enviar isso para o servidor, você pode usar o comando cURL desta forma:

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

To create multiple instances in one request you can wrap the payload in an outer array like this and POST to the same resource as above:

{
  "trackedEntityInstances": [
    {
      "trackedEntity": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "value": "Joe"
        },
        {
          "attribute": "zDhUuAYrxNC",
          "value": "Smith"
        }
      ]
    },
    {
      "trackedEntity": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "value": "Jennifer"
        },
        {
          "attribute": "zDhUuAYrxNC",
          "value": "Johnson"
        }
      ]
    }
  ]
}

The system does not allow the creation of a tracked entity instance (as well as enrollment and event) with a UID that was already used in the system. That means that UIDs cannot be reused.

Atualizar uma instância de entidade rastreada¶

For updating a tracked entity instance, the payload is equal to the previous section. The difference is that you must use the HTTP PUT method for the request when sending the payload. You will also need to append the person identifier to the trackedEntityInstances resource in the URL like this, where <tracked-entity-instance-identifier> should be replaced by the identifier of the tracked entity instance:

/ api / trackedEntityInstances / <tracked-entity-instance-id>

The payload has to contain all, even non-modified, attributes and relationships. Attributes or relationships that were present before and are not present in the current payload any more will be removed from the system. This means that if attributes/relationships are empty in the current payload, all existing attributes/relationships will be deleted from the system. From 2.31, it is possible to ignore empty attributes/relationships in the current payload. A request parameter of ignoreEmptyCollection set to true can be used in case you do not wish to send in any attributes/relationships and also do not want them to be deleted from the system.

It is not allowed to update an already deleted tracked entity instance. Also, it is not allowed to mark a tracked entity instance as deleted via an update request. The same rules apply to enrollments and events.

Excluir uma instância de entidade rastreada¶

In order to delete a tracked entity instance, make a request to the URL identifying the tracked entity instance with the DELETE method. The URL is equal to the one above used for update.

Criar e inscrever instâncias de entidades rastreadas¶

It is also possible to both create (and update) a tracked entity instance and at the same time enroll into a program.

{
  "trackedEntity": "tracked-entity-id",
  "orgUnit": "org-unit-id",
  "attributes": [{
    "attribute": "attribute-id",
    "value": "attribute-value"
  }],
  "enrollments": [{
    "orgUnit": "org-unit-id",
    "program": "program-id",
    "enrollmentDate": "2013-09-17",
    "incidentDate": "2013-09-17"
   }, {
    "orgUnit": "org-unit-id",
    "program": "program-id",
    "enrollmentDate": "2013-09-17",
    "incidentDate": "2013-09-17"
   }]
}

You would send this to the server as you would normally when creating or updating a new tracked entity instance.

curl -X POST -d @tei.json -H "Content-Type: application/json"
  -u user:pass "http://server/api/33/trackedEntityInstances"

Exemplo completo de carga útil, incluindo: instância de entidade rastreada, inscrição e evento¶

It is also possible to create (and update) a tracked entity instance, at the same time enroll into a program and create an event.

{
  "trackedEntityType": "nEenWmSyUEp",
  "orgUnit": "DiszpKrYNg8",
  "attributes": [
    {
      "attribute": "w75KJ2mc4zz",
      "value": "Joe"
    },
    {
      "attribute": "zDhUuAYrxNC",
      "value": "Rufus"
    },
    {
      "attribute": "cejWyOfXge6",
      "value": "Male"
    }
  ],
  "enrollments": [
    {
      "orgUnit": "DiszpKrYNg8",
      "program": "ur1Edk5Oe2n",
      "enrollmentDate": "2017-09-15",
      "incidentDate": "2017-09-15",
      "events": [
        {
          "program": "ur1Edk5Oe2n",
          "orgUnit": "DiszpKrYNg8",
          "eventDate": "2017-10-17",
          "status": "COMPLETED",
          "storedBy": "admin",
          "programStage": "EPEcjy3FWmI",
          "coordinate": {
            "latitude": "59.8",
            "longitude": "10.9"
          },
          "dataValues": [
            {
              "dataElement": "qrur9Dvnyt5",
              "value": "22"
            },
            {
              "dataElement": "oZg33kd9taw",
              "value": "Male"
            }
          ]
        },
        {
          "program": "ur1Edk5Oe2n",
          "orgUnit": "DiszpKrYNg8",
          "eventDate": "2017-10-17",
          "status": "COMPLETED",
          "storedBy": "admin",
          "programStage": "EPEcjy3FWmI",
          "coordinate": {
            "latitude": "59.8",
            "longitude": "10.9"
          },
          "dataValues": [
            {
              "dataElement": "qrur9Dvnyt5",
              "value": "26"
            },
            {
              "dataElement": "oZg33kd9taw",
              "value": "Female"
            }
          ]
        }
      ]
    }
  ]
}

You would send this to the server as you would normally when creating or updating a new tracked entity instance.

curl -X POST -d @tei.json -H "Content-Type: application/json"
  -u user:pass "http://server/api/33/trackedEntityInstances"

Atributos de instância de entidade rastreada gerados¶

Tracked entity instance attributes that are using automatic generation of unique values have three endpoints that are used by apps. The endpoints are all used for generating and reserving values.

In 2.29 we introduced TextPattern for defining and generating these patterns. All existing patterns will be converted to a valid TextPattern when upgrading to 2.29.

Note

As of 2.29, all these endpoints will require you to include any variables reported by the requiredValues endpoint listed as required. Existing patterns, consisting of only #, will be upgraded to the new TextPattern syntax RANDOM(<old-pattern>). The RANDOM segment of the TextPattern is not a required variable, so this endpoint will work as before for patterns defined before 2.29.

Encontrando os valores necessários¶

A TextPattern can contain variables that change based on different factors. Some of these factors will be unknown to the server, so the values for these variables have to be supplied when generating and reserving values.

This endpoint will return a map of required and optional values, that the server will inject into the TextPattern when generating new values. Required variables have to be supplied for the generation, but optional variables should only be supplied if you know what you are doing.

GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/requiredValues

{
  "REQUIRED": [
    "ORG_UNIT_CODE"
  ],
  "OPTIONAL": [
    "RANDOM"
  ]
}

Gerar valor-limite¶

Online web apps and other clients that want to generate a value that will be used right away can use the simple generate endpoint. This endpoint will generate a value that is guaranteed to be unique at the time of generation. The value is also guaranteed not to be reserved. As of 2.29, this endpoint will also reserve the value generated for 3 days.

If your TextPattern includes required values, you can pass them as parameters like the example below:

The expiration time can also be overridden at the time of generation, by adding the ?expiration=<number-of-days> to the request.

GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/generate?ORG_UNIT_CODE=OSLO

{
  "ownerObject": "TRACKEDENTITYATTRIBUTE",
  "ownerUid": "Gs1ICEQTPlG",
  "key": "RANDOM(X)-OSL",
  "value": "C-OSL",
  "created": "2018-03-02T12:01:36.680",
  "expiryDate": "2018-03-05T12:01:36.678"
}

Gerar e reservar valor final¶

The generate and reserve endpoint is used by offline clients that need to be able to register tracked entities with unique ids. They will reserve a number of unique ids that this device will then use when registering new tracked entity instances. The endpoint is called to retrieve a number of tracked entity instance reserved values. An optional parameter numberToReserve specifies how many ids to generate (default is 1).

If your TextPattern includes required values, you can pass them as parameters like the example below:

Similar to the /generate endpoint, this endpoint can also specify the expiration time in the same way. By adding the ?expiration=<number-of-days> you can override the default 60 days.

GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/generateAndReserve?numberToReserve=3&ORG_UNIT_CODE=OSLO

[
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "B-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  },
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "Q-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  },
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "S-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  }
]

Valores reservados¶

Reserved values are currently not accessible through the api, however, they are returned by the generate and generateAndReserve endpoints. The following table explains the properties of the reserved value object:

¶

Expired reservations are removed daily. If a pattern changes, values that were already reserved will be accepted when storing data, even if they don't match the new pattern, as long as the reservation has not expired.

Atributos de imagem¶

Working with image attributes is a lot like working with file data values. The value of an attribute with the image value type is the id of the associated file resource. A GET request to the /api/trackedEntityInstances/<entityId>/<attributeId>/image endpoint will return the actual image. The optional height and width parameters can be used to specify the dimensions of the image.

curl "http://server/api/33/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/image?height=200&width=200"
  > image.jpg

The API also supports a dimension parameter. It can take three possible values (please note capital letters): SMALL (254x254), MEDIUM (512x512), LARGE (1024x1024) or ORIGINAL. Image type attributes will be stored in pre-generated sizes and will be furnished upon request based on the value of the dimension parameter.

curl "http://server/api/33/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/image?dimension=MEDIUM"

File attributes¶

Working with file attributes is a lot like working with image data values. The value of an attribute with the file value type is the id of the associated file resource. A GET request to the /api/trackedEntityInstances/<entityId>/<attributeId>/file endpoint will return the actual file content.

curl "http://server/api/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/file

Consulta de instância de entidade rastreada¶

To query for tracked entity instances you can interact with the /api/trackedEntityInstances resource.

/ api / 33 / trackedEntityInstances

Sintaxe de solicitação¶

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

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

The query is case insensitive. The following rules apply to the query parameters.

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

• Only one of the program and trackedEntity parameters can be specified (zero or one).

• If programStatus is specified then program must also be specified.

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

• If programStartDate or programEndDate is specified then program must also be specified.

• Os itens do filtro só podem ser especificados uma vez.

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

/api/33/trackedEntityInstances.json?ou=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:

/api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A
  & filter = AMpUYgxuCaE & ou = DiszpKrYNg8; yMCshbaVExv

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

/api/33/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A
  & filter = AMpUYgxuCaE: LIKE: Road & ou = DiszpKrYNg8

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

api / 33 / trackedEntityInstances.json? ou = DiszpKrYNg8 & program = ur1Edk5Oe2n
  & filter = lw1SqmMlnfh: GT: 150: LT: 190

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

api / 33 / trackedEntityInstances.json? ou = 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:

api / 33 / trackedEntityInstances.json? filter = zHXD5Ve1Efw: EQ: A & ou = O6uvpzGd5pu
  & ouMode = DESCENDANTS & program = ur1Edk5Oe2n

Para especificar as datas de inscrição no programa como parte da consulta:

api / 33 / trackedEntityInstances.json? filter = zHXD5Ve1Efw: EQ: A & ou = O6uvpzGd5pu
  & program = ur1Edk5Oe2n & programStartDate = 2013-01-01 & programEndDate = 2013-09-01

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

api / 33 / trackedEntityInstances.json? filter = zHXD5Ve1Efw: EQ: A & ou = 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:

api / 33 / trackedEntityInstances.json? filter = zHXD5Ve1Efw: EQ: A & ou = O6uvpzGd5pu
  & ouMode = DESCENDANTES & page = 2 & pageSize = 3

Você pode usar uma variedade de operadores para a filtragem:

Formato de resposta¶

This resource supports JSON, JSONP, XLS and CSV resource representations.

• json (aplicativo/json)

• jsonp (aplicativo / javascript)

• xml (aplicativo/xml)

The response in JSON/XML is in object format and can look like the following. Please note that field filtering is supported, so if you want a full view, you might want to add fields=* to the query:

{
  "trackedEntityInstances": [
    {
      "lastUpdated": "2014-03-28 12:27:52.399",
      "trackedEntity": "cyl5vuJ5ETQ",
      "created": "2014-03-26 15:40:19.997",
      "orgUnit": "ueuQlqb8ccl",
      "trackedEntityInstance": "tphfdyIiVL6",
      "relationships": [],
      "attributes": [
        {
          "displayName": "Address",
          "attribute": "AMpUYgxuCaE",
          "type": "string",
          "value": "2033 Akasia St"
        },
        {
          "displayName": "TB number",
          "attribute": "ruQQnf6rswq",
          "type": "string",
          "value": "1Z 989 408 56 9356 521 9"
        },
        {
          "displayName": "Weight in kg",
          "attribute": "OvY4VVhSDeJ",
          "type": "number",
          "value": "68.1"
        },
        {
          "displayName": "Email",
          "attribute": "NDXw0cluzSw",
          "type": "string",
          "value": "LiyaEfrem@armyspy.com"
        },
        {
          "displayName": "Gender",
          "attribute": "cejWyOfXge6",
          "type": "optionSet",
          "value": "Female"
        },
        {
          "displayName": "Phone number",
          "attribute": "P2cwLGskgxn",
          "type": "phoneNumber",
          "value": "085 813 9447"
        },
        {
          "displayName": "First name",
          "attribute": "dv3nChNSIxy",
          "type": "string",
          "value": "Liya"
        },
        {
          "displayName": "Last name",
          "attribute": "hwlRTFIFSUq",
          "type": "string",
          "value": "Efrem"
        },
        {
          "code": "Height in cm",
          "displayName": "Height in cm",
          "attribute": "lw1SqmMlnfh",
          "type": "number",
          "value": "164"
        },
        {
          "code": "City",
          "displayName": "City",
          "attribute": "VUvgVao8Y5z",
          "type": "string",
          "value": "Kranskop"
        },
        {
          "code": "State",
          "displayName": "State",
          "attribute": "GUOBQt5K2WI",
          "type": "number",
          "value": "KwaZulu-Natal"
        },
        {
          "code": "Zip code",
          "displayName": "Zip code",
          "attribute": "n9nUvfpTsxQ",
          "type": "number",
          "value": "3282"
        },
        {
          "code": "National identifier",
          "displayName": "National identifier",
          "attribute": "AuPLng5hLbE",
          "type": "string",
          "value": "465700042"
        },
        {
          "code": "Blood type",
          "displayName": "Blood type",
          "attribute": "H9IlTX2X6SL",
          "type": "string",
          "value": "B-"
        },
        {
          "code": "Latitude",
          "displayName": "Latitude",
          "attribute": "Qo571yj6Zcn",
          "type": "string",
          "value": "-30.659626"
        },
        {
          "code": "Longitude",
          "displayName": "Longitude",
          "attribute": "RG7uGl4w5Jq",
          "type": "string",
          "value": "26.916172"
        }
      ]
    }
  ]
}

Consulta de grade de instância de entidade rastreada¶

To query for tracked entity instances you can interact with the /api/trackedEntityInstances/grid resource. There are two types of queries: One where a query query parameter and optionally attribute parameters are defined, and one where attribute and filter parameters are defined. This endpoint uses a more compact "grid" format, and is an alternative to the query in the previous section.

/ api / 33 / trackedEntityInstances / query

Sintaxe de solicitação¶

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

Note that you can specify "attribute" with filters or directly using the "filter" params for constraining the instances to return.

Certas regras se aplicam a quais atributos são retornados.

• If "query" is specified without any attributes or program, then all attributes that are marked as "Display in List without Program" is included in the response.

• If program is specified, all the attributes linked to the program will be included in the response.

• If tracked entity type is specified, then all tracked entity type attributes will be included in the response.

You can specify queries with words separated by space - in that situation the system will query for each word independently and return records where each word is contained in any attribute. A query item can be specified once as an attribute and once as a filter if needed. The query is case insensitive. The following rules apply to the query parameters.

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

• Only one of the program and trackedEntity parameters can be specified (zero or one).

• If programStatus is specified then program must also be specified.

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

• If programStartDate or programEndDate is specified then program must also be specified.

• If eventStatus is specified then eventStartDate and eventEndDate must also be specified.

• Uma consulta não pode ser especificada junto com filtros.

• Os itens de atributo só podem ser especificados uma vez.

• Os itens do filtro só podem ser especificados uma vez.

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

/api/33/trackedEntityInstances/query.json?ou=DiszpKrYNg8

A query on all attributes for a specific value and organisation unit, using an exact word match:

/api/33/trackedEntityInstances/query.json?query=scott&ou=DiszpKrYNg8

A query on all attributes for a specific value, using a partial word match:

/api/33/trackedEntityInstances/query.json?query=LIKE:scott&ou=DiszpKrYNg8

You can query on multiple words separated by the URL character for space which is %20, will use a logical AND query for each word:

/api/33/trackedEntityInstances/query.json?query=isabel%20may&ou=DiszpKrYNg8

Uma consulta em que os atributos a serem incluídos na resposta são especificados:

/api/33/trackedEntityInstances/query.json?query=isabel
  & attribute = dv3nChNSIxy & attribute = AMpUYgxuCaE & ou = DiszpKrYNg8

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

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  & attribute = AMpUYgxuCaE & ou = DiszpKrYNg8; yMCshbaVExv

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

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  & filter = AMpUYgxuCaE: LIKE: Road & ou = DiszpKrYNg8

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

/api/33/trackedEntityInstances/query.json?ou=DiszpKrYNg8&program=ur1Edk5Oe2n
  & filter = lw1SqmMlnfh: GT: 150: LT: 190

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

/api/33/trackedEntityInstances/query.json?ou=DiszpKrYNg8
  & attribute = 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:

/api/33/trackedEntityInstances/query.json?filter=zHXD5Ve1Efw:EQ:A
  & ou = O6uvpzGd5pu & ouMode = DESCENDANTES & program = ur1Edk5Oe2n

Para especificar as datas de inscrição no programa como parte da consulta:

/api/33/trackedEntityInstances/query.json?filter=zHXD5Ve1Efw:EQ:A
  & ou = O6uvpzGd5pu & program = ur1Edk5Oe2n & programStartDate = 2013-01-01
  & programEndDate = 2013-09-01

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

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  & ou = O6uvpzGd5pu & ouMode = DESCENDANTES & 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:

/api/33/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  & ou = O6uvpzGd5pu & ouMode = DESCENDANTES & page = 2 & pageSize = 3

To query for instances which have events of a given status within a given time span:

/api/33/trackedEntityInstances/query.json?ou=O6uvpzGd5pu
  &program=ur1Edk5Oe2n&eventStatus=COMPLETED
  &eventStartDate=2014-01-01&eventEndDate=2014-09-01

Você pode usar uma variedade de operadores para a filtragem:

Formato de resposta¶

This resource supports JSON, JSONP, XLS and CSV resource representations.

• json (aplicativo/json)

• jsonp (aplicativo / javascript)

• xml (aplicativo/xml)

• csv (aplicativo/csv)

• xls (application / vnd.ms-excel)

The response in JSON comes is in a tabular format and can look like the following. The headers section describes the content of each column. The instance, created, last updated, org unit and tracked entity columns are always present. The following columns correspond to attributes specified in the query. The rows section contains one row per instance.

{
  "headers": [{
    "name": "instance",
    "column": "Instance",
    "type": "java.lang.String"
  }, {
    "name": "created",
    "column": "Created",
    "type": "java.lang.String"
  }, {
    "name": "lastupdated",
    "column": "Last updated",
    "type": "java.lang.String"
  }, {
    "name": "ou",
    "column": "Org unit",
    "type": "java.lang.String"
  }, {
    "name": "te",
    "column": "Tracked entity",
    "type": "java.lang.String"
  }, {
    "name": "zHXD5Ve1Efw",
    "column": "Date of birth type",
    "type": "java.lang.String"
  }, {
    "name": "AMpUYgxuCaE",
    "column": "Address",
    "type": "java.lang.String"
  }],
  "metaData": {
    "names": {
      "cyl5vuJ5ETQ": "Person"
    }
  },
  "width": 7,
  "height": 7,
  "rows": [
    ["yNCtJ6vhRJu", "2013-09-08 21:40:28.0", "2014-01-09 19:39:32.19", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "21 Kenyatta Road"],
    ["fSofnQR6lAU", "2013-09-08 21:40:28.0", "2014-01-09 19:40:19.62", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "56 Upper Road"],
    ["X5wZwS5lgm2", "2013-09-08 21:40:28.0", "2014-01-09 19:40:31.11", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "56 Main Road"],
    ["pCbogmlIXga", "2013-09-08 21:40:28.0", "2014-01-09 19:40:45.02", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "12 Lower Main Road"],
    ["WnUXrY4XBMM", "2013-09-08 21:40:28.0", "2014-01-09 19:41:06.97", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "13 Main Road"],
    ["xLNXbDs9uDF", "2013-09-08 21:40:28.0", "2014-01-09 19:42:25.66", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "14 Mombasa Road"],
    ["foc5zag6gbE", "2013-09-08 21:40:28.0", "2014-01-09 19:42:36.93", "DiszpKrYNg8", "cyl5vuJ5ETQ", "A", "15 Upper Hill"]
  ]
}

Filtros de instância de entidade rastreada¶

To create, read, update and delete tracked entity instance filters you can interact with the /api/trackedEntityInstanceFilters resource. Tracked entity instance filters are shareable and follows the same pattern of sharing as any other metadata object. When using the /api/sharing the type parameter will be trackedEntityInstanceFilter.

/ api / 33 / trackedEntityInstanceFilters

Criar e atualizar uma definição de filtro de instância de entidade rastreada¶

For creating and updating a tracked entity instance filter in the system, you will be working with the trackedEntityInstanceFilters resource. The tracked entity instance filter definitions are used in the Tracker Capture app to display relevant predefined "Working lists" in the tracker user interface.

Consulta de filtros de instância de entidade rastreada¶

To query for tracked entity instance filters in the system, you can interact with the /api/trackedEntityInstanceFilters resource.

Gestão de matrículas¶

Enrollments have full CRUD support in the API. Together with the API for tracked entity instances most operations needed for working with tracked entity instances and programs are supported.

/ api / 33 / matrículas

Inscrever uma instância de entidade rastreada em um programa¶

For enrolling persons into a program, you will need to first get the identifier of the person from the trackedEntityInstances resource. Then, you will need to get the program identifier from the programs resource. A template payload can be seen below:

{
  "trackedEntityInstance": "ZRyCnJ1qUXS",
  "orgUnit": "ImspTQPwCqd",
  "program": "S8uo8AlvYMz",
  "enrollmentDate": "2013-09-17",
  "incidentDate": "2013-09-17"
}

This payload should be used in a POST request to the enrollments resource identified by the following URL:

/ api / 33 / matrículas

The different status of an enrollment are:

• ACTIVE: It is used meanwhile when the tracked entity participates on the program.
• COMPLETED: It is used when the tracked entity finished its participation on the program.
• CANCELLED: "Deactivated" in the web UI. It is used when the tracked entity cancelled its participation on the program.

For cancelling or completing an enrollment, you can make a PUT request to the enrollments resource, including the identifier and the action you want to perform. For cancelling an enrollment for a tracked entity instance:

/ api / 33 / matrículas / <enrollment-id> / cancelado

For completing an enrollment for a tracked entity instance you can make a PUT request to the following URL:

/ api / 33 / matrículas / <enrollment-id> / concluído

For deleting an enrollment, you can make a DELETE request to the following URL:

/ api / 33 / inscrições / <enrollment-id>

Consulta de instância de inscrição¶

To query for enrollments you can interact with the /api/enrollments resource.

/ api / 33 / matrículas

Sintaxe de solicitação¶

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

The query is case insensitive. The following rules apply to the query parameters.

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

• Only one of the program and trackedEntity parameters can be specified (zero or one).

• If programStatus is specified then program must also be specified.

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

• If programStartDate or programEndDate is specified then program must also be specified.

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

/api/33/enrollments.json?ou=DiszpKrYNg8

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

/api/33/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

Para especificar as datas de inscrição no programa como parte da consulta:

/api/33/enrollments.json?&ou=O6uvpzGd5pu&program=ur1Edk5Oe2n
  & programStartDate = 2013-01-01 & programEndDate = 2013-09-01

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

/api/33/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&trackedEntity=cyl5vuJ5ETQ

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

/api/33/enrollments.json?ouMode=ACCESSIBLE&trackedEntityInstance=tphfdyIiVL6

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

/api/33/enrollments.json?ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3

Formato de resposta¶

This resource supports JSON, JSONP, XLS and CSV resource representations.

• json (aplicativo/json)

• jsonp (aplicativo / javascript)

• xml (aplicativo/xml)

The response in JSON/XML is in object format and can look like the following. Please note that field filtering is supported, so if you want a full view, you might want to add fields=* to the query:

{
  "enrollments": [
    {
      "lastUpdated": "2014-03-28T05:27:48.512+0000",
      "trackedEntity": "cyl5vuJ5ETQ",
      "created": "2014-03-28T05:27:48.500+0000",
      "orgUnit": "DiszpKrYNg8",
      "program": "ur1Edk5Oe2n",
      "enrollment": "HLFOK0XThjr",
      "trackedEntityInstance": "qv0j4JBXQX0",
      "followup": false,
      "enrollmentDate": "2013-05-23T05:27:48.490+0000",
      "incidentDate": "2013-05-10T05:27:48.490+0000",
      "status": "ACTIVE"
    }
  ]
}

Eventos¶

Esta seção é sobre como enviar e ler eventos.

/ api / 33 / events

The different status of an event are:

• ACTIVE: If a event has ACTIVE status, it is possible to edit the event details. COMPLETED events can be turned ACTIVE again and vice versa.
• COMPLETED: An event change the status to COMPLETED only when a user clicks the complete button. If a event has COMPLETED status, it is not possible to edit the event details. ACTIVE events can be turned COMPLETED again and vice versa.
• SKIPPED: Scheduled events that no longer need to happen. In Tracker Capture, there is a button for that.
• SCHEDULE: If an event has no event date (but it has an due date) then the event status is saved as SCHEDULE.
• OVERDUE: If the due date of a scheduled event (no event date) has expired, it can be interpreted as OVERDUE.
• VISITED: (Removed since 2.38. VISITED migrate to ACTIVE). In Tracker Capture its possible to reach VISITED by adding a new event with an event date, and then leave before adding any data to the event - but it is not known to the tracker product team that anyone uses the status for anything. The VISITED status is not visible in the UI, and in all means treated in the same way as an ACTIVE event.

Enviando eventos¶

DHIS2 supports three kinds of events: single events with no registration (also referred to as anonymous events), single event with registration and multiple events with registration. Registration implies that the data is linked to a tracked entity instance which is identified using some sort of identifier.

To send events to DHIS2 you must interact with the events resource. The approach to sending events is similar to sending aggregate data values. You will need a program which can be looked up using the programs resource, an orgUnit which can be looked up using the organisationUnits resource, and a list of valid data element identifiers which can be looked up using the dataElements resource. For events with registration, a tracked entity instance identifier is required, read about how to get this in the section about the trackedEntityInstances resource. For sending events to programs with multiple stages, you will need to also include the programStage identifier, the identifiers for programStages can be found in the programStages resource.

A simple single event with no registration example payload in XML format where we send events from the "Inpatient morbidity and mortality" program for the "Ngelehun CHC" facility in the demo database can be seen below:

`xml

`

To perform some testing we can save the XML payload as a file called event.xml and send it as a POST request to the events resource in the API using curl with the following command:

curl -d @event.xml "https://play.dhis2.org/demo/api/33/events"
  -H "Content-Type:application/xml" -u admin:district

A mesma carga no formato JSON se parece com isto:

{
  "program": "eBAyeGv0exc",
  "orgUnit": "DiszpKrYNg8",
  "eventDate": "2013-05-17",
  "status": "COMPLETED",
  "completedDate": "2013-05-18",
  "storedBy": "admin",
  "coordinate": {
    "latitude": 59.8,
    "longitude": 10.9
  },
  "dataValues": [
    {
      "dataElement": "qrur9Dvnyt5",
      "value": "22"
    },
    {
      "dataElement": "oZg33kd9taw",
      "value": "Male"
    },
    {
      "dataElement": "msodh3rEMJa",
      "value": "2013-05-18"
    }
  ]
}

To send this you can save it to a file called event.json and use curl like this:

curl -d @event.json "localhost/api/33/events" -H "Content-Type:application/json"
  -u admin:district

We also support sending multiple events at the same time. A payload in XML format might look like this:

`xml

`

You will receive an import summary with the response which can be inspected in order to get information about the outcome of the request, like how many values were imported successfully. The payload in JSON format looks like this:

{
  "events": [
  {
    "program": "eBAyeGv0exc",
    "orgUnit": "DiszpKrYNg8",
    "eventDate": "2013-05-17",
    "status": "COMPLETED",
    "storedBy": "admin",
    "coordinate": {
      "latitude": "59.8",
      "longitude": "10.9"
    },
    "dataValues": [
      {
        "dataElement": "qrur9Dvnyt5",
        "value": "22"
      },
      {
        "dataElement": "oZg33kd9taw",
        "value": "Male"
      }
    ]
  },
  {
    "program": "eBAyeGv0exc",
    "orgUnit": "DiszpKrYNg8",
    "eventDate": "2013-05-17",
    "status": "COMPLETED",
    "storedBy": "admin",
    "coordinate": {
      "latitude": "59.8",
      "longitude": "10.9"
    },
    "dataValues": [
      {
        "dataElement": "qrur9Dvnyt5",
        "value": "26"
      },
      {
        "dataElement": "oZg33kd9taw",
        "value": "Female"
      }
    ]
  } ]
}

Você também pode usar GeoJson para armazenar qualquer tipo de geometria em seu evento. Um exemplo de carga útil usando GeoJson em vez das propriedades de latitude e longitude anteriores pode ser visto aqui:

{
  "program": "eBAyeGv0exc",
  "orgUnit": "DiszpKrYNg8",
  "eventDate": "2013-05-17",
  "status": "COMPLETED",
  "storedBy": "admin",
  "geometry": {
    "type": "POINT",
    "coordinates": [59.8, 10.9]
  },
  "dataValues": [
    {
      "dataElement": "qrur9Dvnyt5",
      "value": "22"
    },
    {
      "dataElement": "oZg33kd9taw",
      "value": "Male"
    },
    {
      "dataElement": "msodh3rEMJa",
      "value": "2013-05-18"
    }
  ]
}

As part of the import summary you will also get the identifier reference to the event you just sent, together with a href element which points to the server location of this event. The table below describes the meaning of each element.

Correspondência de unidades orgânicas¶

By default the orgUnit parameter will match on the ID, you can also select the orgUnit id matching scheme by using the parameter orgUnitIdScheme=SCHEME, where the options are: ID, UID, UUID, CODE, and NAME. There is also the ATTRIBUTE: scheme, which matches on a unique metadata attribute value.

Atualizando eventos¶

To update an existing event, the format of the payload is the same, but the URL you are posting to must add the identifier to the end of the URL string and the request must be PUT.

The payload has to contain all, even non-modified, attributes. Attributes that were present before and are not present in the current payload any more will be removed by the system.

It is not allowed to update an already deleted event. The same applies to tracked entity instance and enrollment.

curl -X PUT -d @updated_event.xml "localhost/api/33/events/ID"
  -H "Content-Type: application/xml" -u admin:district

curl -X PUT -d @updated_event.json "localhost/api/33/events/ID"
  -H "Content-Type: application/json" -u admin:district

Excluindo eventos¶

To delete an existing event, all you need is to send a DELETE request with an identifier reference to the server you are using.

curl -X DELETE "localhost/api/33/events/ID" -u admin:district

Atribuição de usuário a eventos¶

Um usuário pode ser atribuído a um evento. Isso pode ser feito incluindo a propriedade apropriada na carga útil ao atualizar ou criar o evento.

  "assignUser ":" <id> "

O id se refere ao if do usuário. Apenas um usuário pode ser atribuído a um evento por vez.

A atribuição de usuário deve ser habilitada no estágio do programa antes que os usuários possam ser atribuídos a eventos.

Obtendo eventos¶

To get an existing event you can issue a GET request including the identifier like this:

curl "http://localhost/api/33/events/ID" -H "Content-Type: application/xml" -u admin:district

Consultando e lendo eventos¶

This section explains how to read out the events that have been stored in the DHIS2 instance. For more advanced uses of the event data, please see the section on event analytics. The output format from the /api/events endpoint will match the format that is used to send events to it (which the analytics event api does not support). Both XML and JSON are supported, either through adding .json/.xml or by setting the appropriate Accept header. The query is paged by default and the default page size is 50 events, field filtering works as it does for metadata, add the fields parameter and include your wanted properties, i.e. ?fields=program,status.

** Nota **

Se a consulta não contém attributeCC nemattributeCos, o servidor retorna eventos para todos os combos de opções de atributos onde o usuário tem acesso de leitura.

Exemplos¶

Consulta para todos os eventos com filhos de uma determinada unidade organizacional:

/api/29/events.json?orgUnit=YuQRtpLP10I&ouMode=CHILDREN

Query for all events with all descendants of a certain organisation unit, implying all organisation units in the sub-hierarchy:

/api/33/events.json?orgUnit=O6uvpzGd5pu&ouMode=DESCENDANTS

Consulta para todos os eventos com um determinado programa e unidade organizacional:

/api/33/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

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

/api/33/events.json?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:

/api/33/events.json?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:

/api/33/events.json?orgUnit=DiszpKrYNg8
  & program = eBAyeGv0exc & trackedEntityInstance = gfVxE3ALA9m

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

/api/33/events.json?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:

/api/33/events.json?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc
  & trackedEntityInstance = gfVxE3ALA9m & startDate = 2014-01-01 & endDate = 2014-12-31

Query files associated with event data values. In the specific case of fetching an image file an additional parameter can be provided to fetch the image with different dimensions. If dimension is not provided, the system will return the original image. The parameter will be ignored in case of fetching non-image files e.g pdf. Possible dimension values are small(254 x 254), medium(512 x 512), large(1024 x 1024) or original. Any value other than those mentioned will be discarded and the original image will be returned.

/ api / 33 / events / files? eventUid = hcmcWlYkg9u & dataElementUid = C0W4aFuVm4P & dimension = small

Retrieve events with specified Organisation unit and Program, and use Attribute:Gq0oWTf2DtN as identifier scheme

/api/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&idScheme=Attribute:Gq0oWTf2DtN

Retrieve events with specified Organisation unit and Program, and use UID as identifier scheme for orgUnits, Code as identifier scheme for Program stages, and Attribute:Gq0oWTf2DtN as identifier scheme for the rest of the metadata with assigned attribute.

api/events.json?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&idScheme=Attribute:Gq0oWTf2DtN
  &orgUnitIdScheme=UID&programStageIdScheme=Code

Consulta de grade de eventos¶

In addition to the above event query end point, there is an event grid query end point where a more compact "grid" format of events are returned. This is possible by interacting with /api/events/query.json|xml|xls|csv endpoint.

/ api / 33 / events / query

Most of the query parameters mentioned in event querying and reading section above are valid here. However, since the grid to be returned comes with specific set of columns that apply to all rows (events), it is mandatory to specify a program stage. It is not possible to mix events from different programs or program stages in the return.

Returning events from a single program stage, also opens up for new functionality - for example sorting and searching events based on their data element values. api/events/query has support for this. Below are some examples

A query to return an event grid containing only selected data elements for a program stage

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  & dataElement = qrur9Dvnyt5, fWIAEtYVEGk, K6uUAvq500H & order = lastUpdated: desc
  & pageSize = 50 & page = 1 & totalPages = true

A query to return an event grid containing all data elements of a program stage

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  & includeAllDataElements = true

A query to filter events based on data element value

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  & filter = qrur9Dvnyt5: GT: 20: LT: 50

In addition to the filtering, the above example also illustrates one thing: the fact that there are no data elements mentioned to be returned in the grid. When this happens, the system defaults back to return only those data elements marked "Display in report" under program stage configuration.

We can also extend the above query to return us a grid sorted (asc|desc) based on data element value

/api/33/events/query.json?orgUnit=DiszpKrYNg8&programStage=Zj7UnCAulEk
  & filter = qrur9Dvnyt5: GT: 20: LT: 50 & order = qrur9Dvnyt5: desc

Filtros de eventos¶

To create, read, update and delete event filters you can interact with the /api/eventFilters resource.

/ api / 33 / eventFilters

Crie e atualize uma definição de filtro de evento¶

For creating and updating an event filter in the system, you will be working with the eventFilters resource. POST is used to create and PUT method is used to update. The event filter definitions are used in the Tracker Capture app to display relevant predefined "Working lists" in the tracker user interface.

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

Um exemplo de carga útil que pode ser usado para criar / atualizar um eventFilter é mostrado abaixo.

{
  "program": "ur1Edk5Oe2n",
  "description": "Simple Filter for TB events",
  "name": "TB events",
  "eventQueryCriteria": {
    "organisationUnit":"DiszpKrYNg8",
    "eventStatus": "COMPLETED",
    "eventDate": {
      "startDate": "2014-05-01",
      "endDate": "2019-03-20",
      "startBuffer": -5,
      "endBuffer": 5,
      "period": "LAST_WEEK",
      "type": "RELATIVE"
    },
    "dataFilters": [{
      "dataItem": "abcDataElementUid",
      "le": "20",
      "ge": "10",
      "lt": "20",
      "gt": "10",
      "in": ["India", "Norway"],
      "like": "abc"
    },
    {
      "dataItem": "dateDataElementUid",
      "dateFilter": {
        "startDate": "2014-05-01",
        "endDate": "2019-03-20",
        "type": "ABSOLUTE"
      }
    },
    {
      "dataItem": "anotherDateDataElementUid",
      "dateFilter": {
        "startBuffer": -5,
        "endBuffer": 5,
        "type": "RELATIVE"
      }
    },
    {
      "dataItem": "yetAnotherDateDataElementUid",
      "dateFilter": {
        "period": "LAST_WEEK",
        "type": "RELATIVE"
      }
    }],
    "programStatus": "ACTIVE"
  }
}

Recuperando e excluindo filtros de eventos¶

Um filtro de evento específico pode ser recuperado usando a seguinte API

GET /api/33/eventFilters/{uid}

Todos os filtros de eventos podem ser recuperados usando a seguinte API.

GET /api/33/eventFilters?fields=*

Todos os filtros de eventos para um programa específico podem ser recuperados usando a seguinte API

GET /api/33/eventFilters?filter=program:eq:IpHINAT79UW

Um filtro de evento pode ser excluído usando a seguinte API

DELETE / api / 33 / eventFilters / {uid}

Relacionamentos¶

Relacionamentos são links entre duas entidades no rastreador. Essas entidades podem ser instâncias de entidades, inscrições e eventos rastreados.

Existem vários terminais que permitem ver, criar, excluir e atualizar relacionamentos. O mais comum é o endpoint / api / trackedEntityInstances, onde você pode incluir relacionamentos na carga útil para criá-los, atualizá-los ou excluí-los se omiti-los - Semelhante a como você trabalha com inscrições e eventos no mesmo endpoint. Todos os endpoints do rastreador, / api / trackedEntityInstances, / api / inscrições e / api / events também listam seus relacionamentos, se solicitados no filtro de campo.

O ponto de extremidade padrão para relacionamentos é, entretanto, / api / relationships. Este terminal fornece todas as operações CRUD normais para relacionamentos.

You can view a list of relationships by trackedEntityInstance, enrollment or event:

GET /api/relationships?[tei={teiUID}|enrollment={enrollmentUID}|event={eventUID}]

Essa solicitação retornará uma lista de qualquer relacionamento que você tenha acesso para ver que inclua o trackedEntityInstance, inscrição ou evento que você especificou. Cada relacionamento é representado com o seguinte JSON:

{
  "relationshipType": "dDrh5UyCyvQ",
  "relationshipName": "Mother-Child",
  "relationship": "t0HIBrc65Rm",
  "bidirectional": false,
  "from": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "vOxUH373fy5"
    }
  },
  "to": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "pybd813kIWx"
    }
  },
  "created": "2019-04-26T09:30:56.267",
  "lastUpdated": "2019-04-26T09:30:56.267"
}

Você também pode visualizar relacionamentos especificados usando o seguinte endpoint:

GET /api/relationships/<id>

Para criar ou atualizar um relacionamento, você pode usar os seguintes endpoints:

POST / api / relationships
PUT / api / relationships

E use a seguinte estrutura de carga útil:

{
  "relationshipType": "dDrh5UyCyvQ",
  "from": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "vOxUH373fy5"
    }
  },
  "to": {
    "trackedEntityInstance": {
      "trackedEntityInstance": "pybd813kIWx"
    }
  }
}

Para excluir um relacionamento, você pode usar este ponto de extremidade:

  DELETE / api / relationships / <id>

Em nossas cargas úteis de exemplo, usamos um relacionamento entre trackedEntityInstances. Por causa disso, as propriedades "de" e "para" de nossas cargas úteis incluem objetos "trackedEntityInstance". Se o seu relacionamento inclui outras entidades, você pode usar as seguintes propriedades:

{
  "enrollment": {
    "enrollment": "<id>"
  }
}

{
  "event": {
    "event": "<id>"
  }
}

Relationship can be soft deleted. In that case, you can use the includeDeleted request parameter to see the relationship.

GET /api/relationships?tei=pybd813kIWx?includeDeleted=true

Estratégias de atualização¶

Two update strategies for all 3 tracker endpoints are supported: enrollment and event creation. This is useful when you have generated an identifier on the client side and are not sure if it was created or not on the server.

Para alterar o parâmetro, use o parâmetro de estratégia:

POST / api / 33 / trackedEntityInstances? Estratégia = CREATE_AND_UPDATE

Exclusão em massa do rastreador¶

Bulk deletion of tracker objects work in a similar fashion to adding and updating tracker objects, the only difference is that the importStrategy is DELETE.

Example: Bulk deletion of tracked entity instances:

{
  "trackedEntityInstances": [
    {
      "trackedEntityInstance": "ID1"
    }, {
      "trackedEntityInstance": "ID2"
    }, {
      "trackedEntityInstance": "ID3"
    }
  ]
}

curl -X POST -d @data.json -H "Content-Type: application/json"
  "http://server/api/33/trackedEntityInstances?strategy=DELETE"

Example: Bulk deletion of enrollments:

{
  "enrollments": [
    {
       "enrollment": "ID1"
    }, {
      "enrollment": "ID2"
    }, {
      "enrollment": "ID3"
    }
  ]
}

curl -X POST -d @data.json -H "Content-Type: application/json"
  "http://server/api/33/enrollments?strategy=DELETE"

Example: Bulk deletion of events:

{
  "events": [
    {
      "event": "ID1"
    }, {
      "event": "ID2"
    }, {
      "event": "ID3"
    }
  ]
}

curl -X POST -d @data.json -H "Content-Type: application/json"
  "http://server/api/33/events?strategy=DELETE"

Reutilização de identificadores e exclusão de itens por meio dos métodos POST e PUT¶

Tracker endpoints /trackedEntityInstances, /enrollments, /events support CRUD operations. The system keeps track of used identifiers. Therefore, an item which has been created and then deleted (e.g. events, enrollments) cannot be created or updated again. If attempting to delete an already deleted item, the system returns a success response as deletion of an already deleted item implies no change.

The system does not allow to delete an item via an update (PUT) or create (POST) method. Therefore, an attribute deleted is ignored in both PUT and POST methods, and in POST method it is by default set to false.

Parâmetros de importação¶

O processo de importação pode ser personalizado usando um conjunto de parâmetros de importação:

Importar / Exportar CSV¶

In addition to XML and JSON for event import/export, in DHIS2.17 we introduced support for the CSV format. Support for this format builds on what was described in the last section, so here we will only write about what the CSV specific parts are.

To use the CSV format you must either use the /api/events.csv endpoint, or add content-type: text/csv for import, and accept: text/csv for export when using the /api/events endpoint.

The order of column in the CSV which are used for both export and import is as follows:

Example of 2 events with 2 different data value each:

`csv EJNxP3WreNP, COMPLETED, <pid>, <psid>, <enrollment-id>, <ou>, 2016-01-01,2016-01-01 ,,, <de>, 1 ,,, EJNxP3WreNP, COMPLETED, <pid>, <psid>, <enrollment-id>, <ou>, 2016-01-01,2016-01-01 ,,, <de>, ,,, qPEdI1xn7k0, COMPLETED, <pid>, <psid>, <enrollment-id>, <ou>, 2016-01-01,2016-01-01 ,,, <de>, 3 ,, qPEdI1xn7k0, COMPLETED, <pid>, <psid>, <enrollment-id>, <ou>, 2016-01-01,2016-01-01 ,,, <de>, 4 ,, `

Estratégia de importação: SYNC¶

The import strategy SYNC should be used only by internal synchronization task and not for regular import. The SYNC strategy allows all 3 operations: CREATE, UPDATE, DELETE to be present in the payload at the same time.

Tracker Ownership Management¶

A new concept called Tracker Ownership is introduced from 2.30. There will now be one owner organisation unit for a tracked entity instance in the context of a program. Programs that are configured with an access level of PROTECTED or CLOSED will adhere to the ownership privileges. Only those users belonging to the owning org unit for a tracked entity-program combination will be able to access the data related to that program for that tracked entity.

Substituição de propriedade do rastreador: Quebre o vidro¶

It is possible to temporarily override this ownership privilege for a program that is configured with an access level of PROTECTED. Any user will be able to temporarily gain access to the program related data, if the user specifies a reason for accessing the tracked entity-program data. This act of temporarily gaining access is termed as breaking the glass. Currently, the 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 tracked entity program combination, you can issue a POST request as shown:

/ api / 33 / tracker / propriedade / override? trackedEntityInstance = DiszpKrYNg8
  & program = eBAyeGv0exc & reason = paciente + apareceu + para + emergência + atendimento

Tracker Ownership Transfer¶

It is possible to transfer the ownership of a tracked entity-program from one org unit to another. This will be useful in case of patient referrals or migrations. Only an owner (or users who have broken the glass) can transfer the ownership. To transfer ownership of a tracked entity-program to another organisation unit, you can issue a PUT request as shown:

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

Potenciais duplicados¶

As duplicatas potenciais são registros com os quais trabalhamos no recurso de desduplicação de dados. Devido à natureza do recurso de desduplicação, este terminal de API é um tanto restrito.

A potential duplicate represents a pair of records which are suspected to be a duplicate.

A carga útil de uma possível duplicata se parece com isto:

{
  "original": "<id>",
  "duplicate": "<id>",
  "status": "OPEN|INVALID|MERGED"
}

Você pode recuperar uma lista de possíveis duplicatas usando o seguinte endpoint:

GET /api/potentialDuplicates

You can inspect individual potential duplicate records:

GET /api/potentialDuplicates/<id>

Para criar uma nova duplicata potencial, você pode usar este endpoint:

POST / api / potencialDuplicates

The payload you provide must include IDs of Original and Duplicate TEIs.

{
  "original": "<id>",
  "duplicate": "<id>"
}

To update a potential duplicate status:

PUT /api/potentialDuplicates/<id>

Merging Tracked Entity Instances¶

Tracked entity instances can now be merged together if they are viable. To initiate a merge, the first step is to define two tracked entity instances as a Potential Duplicate. The merge endpoint will move data from the duplicate tracked entity instance to the original tracked entity instance, and delete the remaining data of the duplicate.

To merge a Potential Duplicate, or the two tracked entity instances the Potential Duplicate represents, the following endpoint can be used:

POST /api/potentialDuplicates/<id>/merge

The endpoint accepts a single parameter, "mergeStrategy", which decides which strategy to use when merging. For the AUTO strategy, the server will attempt to merge the two tracked entities automatically, without any input from the user. This strategy only allows merging tracked entities without conflicting data (See examples below). The other strategy, MANUAL, requires the user to send in a payload describing how the merge should be done. For examples and rules for each strategy, see their respective sections below.

Merge Strategy AUTO¶

The automatic merge will evaluate the mergability of the two tracked entity instances, and merge them if they are deemed mergable. The mergability is based on whether the two tracked entity instances has any conflicts or not. Conflicts refers to data which cannot be merged together automatically. Examples of possible conflicts are: - The same attribute has different values in each tracked entity instance - Both tracked entity instances are enrolled in the same program - Tracked entity instances have different types

If any conflict is encountered, an errormessage is returned to the user.

When no conflicts are found, all data in the duplicate that is not already in the original will be moved over to the original. This includes attribute values, enrollments (Including events) and relationships. After the merge completes, the duplicate is deleted and the potentialDuplicate is marked as MERGED.

When requesting an automatic merge like this, a payload is not required and will be ignored.

Merge Strategy MANUAL¶

The manual merge is suitable when the merge has resolvable conflicts, or when not all the data is required to be moved over during a merge. For example, if an attribute has different values in both tracked entity instances, the user can specify whether to keep the original value, or move over the duplicate's value. Since the manual merge is the user explicitly requesting to move data, there are some different checks being done here: - Relationship cannot be between the original and the duplicate (This results in an invalid self-referencing relationship) - Relationship cannot be of the same type and to the same object in both tracked entity instances (IE. between original and other, and duplicate and other; This would result in a duplicate relationship)

There are two ways to do a manual merge: With and without a payload.

When a manual merge is requested without a payload, we are telling the API to merge the two tracked entity instances without moving any data. In other words, we are just removing the duplicate and marking the potentialDuplicate MERGED. This might be valid in a lot of cases where the tracked entity instance was just created, but not enrolled for example.

Otherwise, if a manual merge is requested with a payload, the payload refers to what data should be moved from the duplicate to the original. The payload looks like this:

{
  "trackedEntityAttributes": ["B58KFJ45L9D"],
  "enrollments": ["F61SJ2DhINO"],
  "relationships": ["ETkkZVSNSVw"]
}

This payload contains three lists, one for each of the types of data that can be moved. trackedEntityAttributes is a list of uids for tracked entity attributes, enrollments is a list of uids for enrollments and relationships a list of uids for relationships. The uids in this payload have to refer to data that actually exists on the duplicate. There is no way to add new data or change data using the merge endpoint - Only moving data.

Additional information about merging¶

Currently it is not possible to merge tracked entity instances that are enrolled in the same program, due to the added complexity. A workaround is to manually remove the enrollments from one of the tracked entity instances before starting the merge.

All merging is based on data already persisted in the database, which means the current merging service is not validating that data again. This means if data was already invalid, it will not be reported during the merge. The only validation done in the service relates to relationships, as mentioned in the previous section.

Program Notification Template¶

Program Notification Template lets you create message templates which can be sent as a result of different type of events. Message and Subject templates will be translated into actual values and can be sent to the configured destination. Each program notification template will be transformed to either MessageConversation object or ProgramMessage object based on external or internal notificationRecipient. These intermediate objects will only contain translated message and subject text. There are multiple configuraiton parameters in Program Notification Template which are critical for correct working of notifications. All those are explained in the table below.

POST /api/programNotificationTemplates

{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}

Os campos são explicados na tabela a seguir.

NOTE: WEB_HOOK notificationRecipient is used only to POST http request to an external system. Make sure to choose HTTP delivery channel when using WEB_HOOK.

Retrieving and deleting Program Notification Template¶

The list of Program Notification Templates can be retrieved using GET.

GET /api/programNotificationTemplates

For one particular Program Notification Template.

GET /api/33/programNotificationTemplates/{uid}

To get filtered list of Program Notification Templates

GET /api/programNotificationTemplates/filter?program=<uid>
GET /api/programNotificationTemplates/filter?programStage=<uid>

Program Notification Template can be deleted using DELETE.

DELETE /api/33/programNotificationTemplates/{uid}

Program Messages¶

Program message lets you send messages to tracked entity instances, contact addresses associated with organisation units, phone numbers and email addresses. You can send messages through the messages resource.

/ api / 33 / messages

Enviando mensagens do programa¶

As mensagens do programa podem ser enviadas usando dois canais de entrega:

• SMS (SMS)

• Endereço de email (EMAIL)

As mensagens do programa podem ser enviadas para vários destinatários:

• Tracked entity instance: The system will look up attributes of value type PHONE_NUMBER or EMAIL (depending on the specified delivery channels) and use the corresponding attribute values.

• Organisation unit: The system will use the phone number or email information registered for the organisation unit.

• List of phone numbers: The system will use the explicitly defined phone numbers.

• List of email addresses: The system will use the explicitly defined email addresses.

Below is a sample JSON payload for sending messages using POST requests. Note that message resource accepts a wrapper object named programMessages which can contain any number of program messages.

POST / api / 33 / messages

{
  "programMessages": [{
    "recipients": {
      "trackedEntityInstance": {
        "id": "UN810PwyVYO"
      },
      "organisationUnit": {
        "id": "Rp268JB6Ne4"
      },
      "phoneNumbers": [
        "55512345",
        "55545678"
      ],
      "emailAddresses": [
        "johndoe@mail.com",
        "markdoe@mail.com"
      ]
    },
    "programInstance": {
      "id": "f3rg8gFag8j"
    },
    "programStageInstance": {
      "id": "pSllsjpfLH2"
    },
    "deliveryChannels": [
      "SMS", "EMAIL"
    ],
    "notificationTemplate": "Zp268JB6Ne5",
    "subject": "Outbreak alert",
    "text": "An outbreak has been detected",
    "storeCopy": false
  }]
}

Os campos são explicados na tabela a seguir.

A minimalistic example for sending a message over SMS to a tracked entity instance looks like this:

curl -d @message.json "https://play.dhis2.org/demo/api/33/messages"
  -H "Content-Type:application/json" -u admin:district

{
  "programMessages": [{
    "recipients": {
      "trackedEntityInstance": {
        "id": "PQfMcpmXeFE"
      }
    },
    "programInstance": {
      "id": "JMgRZyeLWOo"
    },
    "deliveryChannels": [
      "SMS"
    ],
    "text": "Please make a visit on Thursday"
  }]
}

Recuperando e excluindo mensagens do programa¶

A lista de mensagens pode ser recuperada usando GET.

GET /api/33/messages

To get the list of sent tracker messages, the below endpoint can be used. ProgramInstance or ProgramStageInstance uid has to be provided.

GET /api/33/messages/scheduled/sent?programInstance={uid}
GET /api/33/messages/scheduled/sent?programStageInstance={uid}

To get the list of all scheduled message

GET /api/33/messages/scheduled
GET /api/33/messages/scheduled?scheduledAt=2020-12-12

Uma mensagem específica também pode ser recuperada usando GET.

GET /api/33/messages/{uid}

A mensagem pode ser excluída usando DELETE.

DELETE / api / 33 / messages / {uid}

Consultando mensagens do programa¶

The program message API supports program message queries based on request parameters. Messages can be filtered based on below mentioned query parameters. All requests should use the GET HTTP verb for retrieving information.