1.31 Indicators

This section describes indicators and indicator expressions.

1.31.1 Aggregate indicators

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

/api/26/indicators

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

Indicator variables
Variable Object Description
#{<dataelement-id>.<categoryoptcombo-id>.<attributeoptcombo-id>} Data element operand Refers to a combination of an aggregate data element and a category option combination. Both category and attribute option combo ids are optional, and a wilcard "*" symbol can be used to indicate any value.
#{<dataelement-id>} Aggregate data element Refers to the total value of an aggregate data element across all category option combinations.
D{<program-id>.<dataelement-id> Program data element Refers to the value of a tracker data element within a program.
A{<program-id>.<attribute-id> Program tracked entity attribute Refers to the value of a tracked entity attribute within a program.
I{program-indicator-id> Program indicator Refers to the value of a program indicator.
R{<dataset-id>.<metric>} Reporting rate Refers to a reporting rate metric. The metric can be REPORTING_RATE, REPORTING_RATE_ON_TIME, ACTUAL_REPORTS, ACTUAL_REPORTS_ON_TIME, EXPECTED_REPORTS.
C{<constant-id>} Constant Refers to a constant value.
OUG{<orgunitgroup-id>} Organisation unit group Refers to the count of organisation units within an organisation unit group.

The syntax looks like this:

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

A corresponding example looks like this:

#{P3jJH5Tu5VC.S34ULMcHMca} + C{Gfd3ppDfq8E} + OUG{CXw2yu5fodb}

Note that for data element variables the category option combo identifier can be omitted. The variable will then represent the total for the data element, e.g. across all category option combos. Example:

#{P3jJH5Tu5VC} + 2

Data element operands can include any of category option combination and attribute option combination, and use wildcards to indicate any value:

#{P3jJH5Tu5VC.S34ULMcHMca} + #{P3jJH5Tu5VC.*.j8vBiBqGf6O} + #{P3jJH5Tu5VC.S34ULMcHMca.*}

An example which uses a program data element and a program attribute:

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

An example which combines program indicators and aggregate indicators:

I{EMOt6Fwhs1n} * 1000 / #{WUg3MYWQ7pt}

An example which uses a reporting rate looks like this:

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

Another example which uses actual data set reports:

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

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

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

1.31.2 Program indicators

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

/api/26/programIndicators

Program indicators can contain information collected in a program. Indicators have an expression which can contain references to data elements, attributes, constants and program variables. Variables which are allowed in expressions are described in the following table.

Program indicator variables
Variable Description
#{<programstage-id>.<dataelement-id>} Refers to a combination of program stage and data element id.
#{<attribute-id>} Refers to a tracked entity attribute.
V{<varible-id>} Refers to a program variable.
C{<constant-id>} Refers to a constant.

The syntax looks like this:

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

A corresponding example looks like this:

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

1.31.3 Expressions

Expressions are mathematical formulas which can contain references to data elements, constants and organisation unit groups. To validate and get the textual description of an expression you can make a GET request to the expressions resource:

/api/26/expressions/description?expression=<expression-string>

The response follows the standard JSON web message format. The status property indicates the outcome of the validation and will be “OK” if successful and “ERROR” if failed. The message property will be “Valid” if successful and provide a textual description of the reason why the validation failed if not. The description provides a textual description of the expression.

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Valid",
    "description": "Acute Flaccid Paralysis"
}