1.67 Tracked entity instance management

Tracked entity instances have full CRUD (create, read, update, delete) support in the Web-API. Together with the API for enrollment most operations needed for working with tracked entity instances and programs are supported.

/api/26/trackedEntityInstances

1.67.1 Creating a new tracked entity instance

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",
    "coordinates": "[1, 1]",
    "attributes": [ {
        "attribute": "attribute-id",
        "value": "attribute-value"
    } ]
}

Note

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

Note

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

For getting the IDs for relationship , 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 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"
    }
  ]
}

To push this to the server you can use the cURL command like this:

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

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

1.67.2 Updating a tracked entity instance

For updating a tracked entity instance, the payload is the 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>

1.67.3 Deleting a tracked entity instance

To delete a tracked entity instance you can make a request to the URL identifiying the tracked entity instance with the HTTP DELETE method. The URL is equal to the one above used for update.

1.67.4 Enrolling a tracked entity instance into a program

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

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/enrollments/<enrollment-id>/cancelled

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

/api/enrollments/<enrollment-id>/completed

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

/api/enrollments/<enrollment-id>

1.67.5 Update strategies

Two update strategies for tracked entity instance 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.

Available tracker strategies
Parameter Description
CREATE Create only, this is the default behavior.
CREATE_AND_UPDATE Try and match the ID, if it exist then update, if not create.

To change the parameter, please use the strategy parameter:

POST /api/trackedEntityInstances?strategy=CREATE_AND_UPDATE

1.67.6 Create and enroll tracked entity instances

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

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

1.67.7 Generated tracked entity instance attributes

Tracked entity instance attributes that is using automatic generation of unique values has three endpoints that is 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. You can read more about working with TextPattern here . All existing patterns will be converted to a valid TextPattern when upgrading to 2.29.

Note

As of 2.29, all these endpoint 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.

1.67.7.0.1 Finding required values

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/trackedEntityAttributes/Gs1ICEQTPlG/requiredValues

{
    "REQUIRED": [
        "ORG_UNIT_CODE"
    ],
    "OPTIONAL": [
        "RANDOM"
    ]
}
1.67.7.0.2 Generate value endpoint

Online web apps and other clients that wants 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/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"
}
1.67.7.0.3 Generate and reserve value endpoint

The generate and reserve endpoint is used by offline clients that needs 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/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"
    }
]
1.67.7.0.4 Reserved values

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

1.67.7.0.5
Reserved values
Property Description
ownerObject The metadata type referenced when generating and reserving the value. Currently only TRACKEDENTITYATTRIBUTE is supported.
ownerUid The uid of the metadata object referenced when generating and reserving the value.
key A partially generated value where generated segments are not yet added.
value The fully resolved value reserved. This is the value you send to the server when storing data.
created The timestamp when the reservation was made
expiryDate The timestamp when the reservation will no longer be reserved

Expired reservations are removed daily. If a pattern changes, values that was 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.

1.67.7.1 Image attributes

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/29/trackedEntityInstances/ZRyCnJ1qUXS/zDhUuAYrxNC/image?height=200&width=200
  > image.jpg

1.67.7.2 Tracked entity instance query

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

/api/29/trackedEntityInstances
1.67.7.2.1 Request syntax
Tracked entity instances query parameters
Query parameter Description
filter Attributes to use as a filter for the query. Param can be repeated any number of times. Filters can be applied to a dimension on the format <attribute-id>:<operator>:<filter>[:<operator>:<filter>]. Filter values are case-insensitive and can be repeated together with operator any number of times. Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN.
ou Organisation unit identifiers, separated by “;”.
ouMode The mode of selecting organisation units, can be SELECTED | CHILDREN | DESCENDANTS | ACCESSIBLE | CAPTURE | ALL. Default is SELECTED, which refers to the selected organisation units only. See table below for explanations.
program Program identifier. Restricts instances to being enrolled in the given program.
programStatus Status of the instance for the given program. Can be ACTIVE | COMPLETED | CANCELLED.
followUp Follow up status of the instance for the given program. Can be true | false or omitted.
programStartDate Start date of enrollment in the given program for the tracked entity instance.
programEndDate End date of enrollment in the given program for the tracked entity instance.
trackedEntity Tracked entity identifier. Restricts instances to the given tracked instance type.
page The page number. Default page is 1.
pageSize The page size. Default size is 50 rows per page.
totalPages Indicates whether to include the total number of pages in the paging response (implies higher response time).
skipPaging Indicates whether paging should be ignored and all rows should be returned.
lastUpdatedStartDate Filter for events which were updated after this date.
lastUpdatedEndDate Filter for events which were updated up until this date.

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

Organisation unit selection modes
Mode Description
SELECTED Organisation units defined in the request.
CHILDREN The selected organisation units and the immediate children, i.e. the organisation units at the level below.
DESCENDANTS The selected organisation units and and all children, i.e. all organisation units in the sub-hierarchy.
ACCESSIBLE The data view organisation units associated with the current user and all children, i.e. all organisation units in the sub-hierarchy. Will fall back to data capture organisation units associated with the current user if the former is not defined.
CAPTURE The data capture organisation units associated with the current user and all children, i.e. all organisation units in the sub-hierarchy.
ALL All organisation units in the system. Requires the ALL authority.

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.

  • Filter items can only be specified once.

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

api/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 descendants organisation unit query mode:

api/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 us used as a filter:

api/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/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/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/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu
&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

To specify program enrollment dates as part of the query:

api/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/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/trackedEntityInstances.json?filter=zHXD5Ve1Efw:EQ:A&ou=O6uvpzGd5pu
&ouMode=DESCENDANTS&page=2&pageSize=3

You can use a range of operators for the filtering:

Filter operators
Operator Description
EQ Equal to
GT Greater than
GE Greater than or equal to
LT Less than
LE Less than or equal to
NE Not equal to
LIKE Like (free text match)
IN Equal to one of multiple values separated by “;”
1.67.7.2.2 Response format

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

  • json (application/json)

  • jsonp (application/javascript)

  • xml (application/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=*):

{
    "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": "Mother maiden name",
                    "displayName": "Mother maiden name",
                    "attribute": "o9odfev2Ty5",
                    "type": "string",
                    "value": "Gabriel"
                },
                {
                    "code": "National identifier",
                    "displayName": "National identifier",
                    "attribute": "AuPLng5hLbE",
                    "type": "string",
                    "value": "465700042"
                },
                {
                    "code": "Occupation",
                    "displayName": "Occupation",
                    "attribute": "A4xFHyieXys",
                    "type": "string",
                    "value": "Biophysicist"
                },
                {
                    "code": "Company",
                    "displayName": "Company",
                    "attribute": "kyIzQsj96BD",
                    "type": "string",
                    "value": "Sav-A-Center"
                },
                {
                    "code": "Vehicle",
                    "displayName": "Vehicle",
                    "attribute": "VHfUeXpawmE",
                    "type": "string",
                    "value": "2008 Citroen Picasso"
                },
                {
                    "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"
                }
            ]
        }
    ]
}

1.67.7.3 Tracked entity instance grid query

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/29/trackedEntityInstances/query
1.67.7.3.1 Request syntax
Tracked entity instances query parameters
Query parameter Description
query Query string. Attribute query parameter can be used to define which attributes to include in the response. If no attributes but a program is defined, the attributes from the program will be used. If no program is defined, all attributes will be used. There are two formats. The first is a plan query string. The second is on the format <operator>:<query>. Operators can be EQ | LIKE. EQ implies exact matches on words, LIKE implies partial matches on words. The query will be split on space, where each word will form a logical AND query.
attribute Attributes to be included in the response. Can also be used a filter for the query. Param can be repeated any number of times. Filters can be applied to a dimension on the format <attribute-id>:<operator>:<filter>[:<operator>:<filter>]. Filter values are case-insensitive and can be repeated together with operator any number of times. Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN. Filters can be omitted in order to simply include the attribute in the response without any constraints.
filter Attributes to use as a filter for the query. Param can be repeated any number of times. Filters can be applied to a dimension on the format <attribute-id>:<operator>:<filter>[:<operator>:<filter>]. Filter values are case-insensitive and can be repeated together with operator any number of times. Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN.
ou Organisation unit idenfiers, separated by “;”.
ouMode The mode of selecting organisation units, can be SELECTED | CHILDREN | DESCENDANTS | ACCESSIBLE | ALL. Default is SELECTED, which refers to the selected organisation units only. See table below for explanations.
program Program identifier. Restricts instances to being enrolled in the given program.
programStatus Status of the instance for the given program. Can be ACTIVE | COMPLETED | CANCELLED.
followUp Follow up status of the instance for the given program. Can be true | false or omitted.
programStartDate Start date of enrollment in the given program for the tracked entity instance.
programEndDate End date of enrollment in the given program for the tracked entity instance.
trackedEntity Tracked entity identifer. Restricts instances to the given tracked instance type.
eventStatus Status of any event associated with the given program and the tracked entity instance. Can be ACTIVE | COMPLETED | VISITED | SCHEDULED | OVERDUE | SKIPPED.
eventStartDate Start date of event associated with the given program and event status.
eventEndDate End date of event associated with the given program and event status.
skipMeta Indicates whether meta data for the response should be included.
page The page number. Default page is 1.
pageSize The page size. Default size is 50 rows per page.
totalPages Indicates whether to include the total number of pages in the paging response (implies higher response time).
skipPaging Indicates whether paging should be ignored and all rows should be returned.

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

Organisation unit selection modes
Mode Description
SELECTED Organisation units defined in the request.
CHILDREN Immediate children, i.e. only the first level below, of the organisation units defined in the request.
DESCENDANTS All children, i.e. at only levels below, e.g. including children of children, of the organisation units defined in the request.
ACCESSIBLE All descendants of the data view organisation units associated with the current user. Will fall back to data capture organisation units associated with the current user if the former is not defined.
ALL All organisation units in the system. Requires authority.

Note that you can specify attributes with filters for constraining the instances to return, or attributes without filters in order to include the attribute in the response without any constraints. Attributes will be included in the response, while filters will only be used as criteria.

Certain rules apply to which attributes are defined when no attributes are specified in the request:

  • If not specifying a program, the attributes defined to be displayed in lists with no program will be included in the response.

  • If specifying a program, the attributes linked to the program 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.

  • A query cannot be specified together with filters.

  • Attribute items can only be specified once.

  • Filter items can only be specified once.

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

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

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

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

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

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

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

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

A query where the attributes to include in the response are specified:

/api/26/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/26/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 us used as a filter:

/api/26/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/26/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/26/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/26/trackedEntityInstances/query.json?filter=zHXD5Ve1Efw:EQ:A
  &ou=O6uvpzGd5pu&ouMode=DESCENDANTS&program=ur1Edk5Oe2n

To specify program enrollment dates as part of the query:

/api/26/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/26/trackedEntityInstances/query.json?attribute=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/26/trackedEntityInstances/query.json?attribute=zHXD5Ve1Efw:EQ:A
  &ou=O6uvpzGd5pu&ouMode=DESCENDANTS&page=2&pageSize=3

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

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

You can use a range of operators for the filtering:

Filter operators
Operator Description
EQ Equal to
GT Greater than
GE Greater than or equal to
LT Less than
LE Less than or equal to
NE Not equal to
LIKE Like (free text match)
IN Equal to one of multiple values separated by “;”
1.67.7.3.2 Response format

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

  • json (application/json)

  • jsonp (application/javascript)

  • xml (application/xml)

  • csv (application/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"]
    ]
}

1.67.7.4 Tracked entity instance filters

To create, read, update and delete tracked entity instance filters you can interact with the /api/trackedEntityInstanceFilters resource.

/api/29/trackedEntityInstanceFilters
1.67.7.4.1 Create and update a tracked entity instance filter definiton

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 defintions are used in the Tracker Capture app to display relevant predefined “Working lists” in the tracker user interface.

Payload
Payload values Description Example
name Name of the filter. Required.
description A description of the filter.
sortOrder The sort order of the filter. Used in Tracker Capture to order the filters in the program dashboard.
style Object containing css style. ( “color”: “blue”, “icon”: “fa fa-calendar”}
program Object containing the id of the program. Required. { “id” : “uy2gU8kTjF”}
enrollmentStatus The TEIs enrollment status. Can be none(any enrollmentstatus) or ACTIVE|COMPLETED|CANCELED
followup When this parameter is true, the filter only returns TEIs that has an enrollment with status followup.
enrollmentCreatedPeriod Period object containing a period which the enrollment must be created. See Period definition table below. { “periodFrom”: -15, “periodTo”: 15}
eventFilters A list of eventFilters. See Event filters definition table below. [{“programStage”: “eaDH9089uMp”, “eventStatus”: “OVERDUE”, “eventCreatedPeriod”: {“periodFrom”: -15, “periodTo”: 15}}]
Event filters definition
programStage Which programStage the TEI needs an event in to be returned. “eaDH9089uMp”
eventStatus The events status. Can be none(any event status) or ACTIVE|COMPLETED|SCHEDULED|OVERDUE ACTIVE
eventCreatedPeriod Period object containing a period in which the event must be created. See Period definition delow. { “periodFrom”: -15, “periodTo”: 15}
Period definition
periodFrom Number of days from current day. Can be positive or negative integer. -15
periodTo Number of days from current day. Must be bigger than periodFrom. Can be positive or negative integer. 15
1.67.7.4.2 Tracked entity instance filters query

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

Tracked entity instance filters query paramateres
Query parameter Description
program Program identifier. Restricts filters to the given program.