Analytics
Analytics#
To access analytical, aggregated data in HRHIS4 you can work with the analytics resource. The analytics resource is powerful as it lets you query and retrieve data aggregated along all available data dimensions. For instance, you can ask the analytics resource to provide the aggregated data values for a set of data elements, periods and organisation units. Also, you can retrieve the aggregated data for a combination of any number of dimensions based on data elements and organisation unit group sets.
Request query parameters#
The analytics resource lets you specify a range of query parameters:
The dimension query parameter defines which dimensions should be included in the analytics query. Any number of dimensions can be specified. The dimension parameter should be repeated for each dimension to include in the query response. The query response can potentially contain aggregated values for all combinations of the specified dimension items.
The filter parameter defines which dimensions should be used as filters for the data retrieved in the analytics query. Any number of filters can be specified. The filter parameter should be repeated for each filter to use in the query. A filter differs from a dimension in that the filter dimensions will not be part of the query response content, and that the aggregated values in the response will be collapsed on the filter dimensions. In other words, the data in the response will be aggregated on the filter dimensions, but the filters will not be included as dimensions in the actual response. As an example, to query for certain data elements filtered by the periods and organisation units you can use the following URL:
The aggregationType query parameter lets you define which aggregation operator should be used for the query. By default, the aggregation operator defined for data elements included in the query will be used. If your query does not contain any data elements but does include data element groups, the aggregation operator of the first data element in the first group will be used. The order of groups and data elements is undefined. This query parameter allows you to override the default and specify a specific aggregation operator. As an example, you can set the aggregation operator to "count" with the following URL:
The measureCriteria query parameter lets you filter out ranges of data records to return. You can instruct the system to return only records where the aggregated data value is equal, greater than, greater or equal, less than or less or equal to certain values. You can specify any number of criteria on the following format, where criteria and value should be substituted with real values:
As an example, the following query will return only records where the data value is greater or equal to 6500 and less than 33000:
Similar to measureCriteria, the preAggregationMeasureCriteria query parameter lets you filter out data, only before aggregation is performed. For example, the following query only aggregates data where the original value is within the criteria defined:
The startDate and endDate parameters can be used to specify a custom date range to aggregate over. When specifying a date range you can not specify relative nor fixed periods as dimension or filter. The date range will filter the analytics response. You can use it like this:
In order to have the analytics resource generate the data in the shape of a ready-made table, you can provide the tableLayout parameter with true as value. Instead of generating a plain, normalized data source, the analytics resource will now generate the data in a table layout. You can use the columns and rows parameters with dimension identifiers separated by semi-colons as values to indicate which ones to use as table columns and rows. The column and rows dimensions must be present as a data dimension in the query (not a filter). Such a request can look like this:
The order parameter can be used for analytics resource to generate ordered data. The data will be ordered in ascending (or descending) order of values. An example request for ordering the values in descending order is:
Dimensions and items#
HRHIS4 features a multi-dimensional data model with several fixed and dynamic data dimensions. The fixed dimensions are the data element, period (time) and organisation unit dimension. You can dynamically add dimensions through categories, data element group sets and organisation unit group sets. The table below displays the available data dimensions in HRHIS4. Each data dimension has a corresponding dimension identifier, and each dimension can have a set of dimension items:
It is not necessary to be aware of which objects are used for the various dynamic dimensions when designing analytics queries. You can get a complete list of dynamic dimensions by visiting this URL in the Web API:
The base URL to the analytics resource is /api/analytics. To request
specific dimensions and dimension items you can use a query string on
the following format, where dim-id and dim-item should be substituted with real values:
As illustrated above, the dimension identifier is followed by a colon while the dimension items are separated by semi-colons. As an example, a query for two data elements, two periods and two organisation units can be done with the following URL:
To query for data broken down by category option combinations instead of data element totals you can include the category dimension in the query string, for instance like this:
When selecting data elements you can also select all data elements in a group as items by using the DE_GROUP-groupid syntax:
When selecting data set reporting rates, the syntax contains a data set identifier followed by a reporting rate metric:
To query for organisation unit group sets and data elements you can use the following URL. Notice how the group set identifier is used as a dimension identifier and the groups as dimension items:
To query for data elements and categories you can use this URL. Use the category identifier as a dimension identifier and the category options as dimension items:
To query using relative periods and organisation units associated with the current user you can use a URL like this:
When selecting organisation units for a dimension you can select an
entire level optionally constrained by any number of boundary
organisation units with the LEVEL-<level> syntax. Boundary refers to a
top node in a sub-hierarchy, meaning that all organisation units at the
given level below the given boundary organisation unit in the hierarchy
will be included in the response, and is provided as regular organisation unit
dimension items. The level value can either be a numerical level or refer to the identifier
of the organisation unit level entity. A simple query for all org units at level three:
A query for level three and four with two boundary org units can be specified like this:
When selecting organisation units you can also select all organisation units in an organisation unit group to be included as dimension items using the OU_GROUP-groupid syntax. The organisation units in the groups can optionally be constrained by any number of boundary organisation units. Both the level and the group items can be repeated any number of times:
You can utilize identifier schemes for the metadata part of the analytics response with the outputIdScheme property like this. You can use ID, code and attributes as identifier scheme:
A few things to be aware of when using the analytics resource are listed below.
Data elements, indicator, data set reporting rates, program data elements and program indicators are part of a common data dimension, identified as "dx". This means that you can use any of data elements, indicators and data set identifiers together with the "dx" dimension identifier in a query.
For the category, data element group set and organisation unit group set dimensions, all dimension items will be used in the query if no dimension items are specified.
For the period dimension, the dimension items are ISO period identifiers and/or relative periods. Please refer to the section above called "Date and period format" for the period format and available relative periods.
For the organisation unit dimension, you can specify the items to be the organisation unit or sub-units of the organisation unit associated with the user currently authenticated for the request using the keys
USER_ORGUNITorUSER_ORGUNIT_CHILDRENas items, respectively. You can also specify organisation unit identifiers directly, or a combination of both.For the organisation unit dimension, you can specify the organisation hierarchy level and the boundary unit to use for the request on the format
LEVEL-<level>-<boundary-id>; as an exampleLEVEL-3-ImspTQPwCqdimplies all organisation units below the given boundary unit at level 3 in the hierarchy.For the organisation unit dimension, the dimension items are the organisation units and their sub-hierarchy - data will be aggregated for all organisation units below the given organisation unit in the hierarchy.
You cannot specify dimension items for the category option combination dimension. Instead, the response will contain the items which are linked to the data values.
The dx dimension#
The dx dimension is a special dimension which can contain all of the
following data types.
Items from all of the various dx types can be combined in an analytics
request. An example looks like this:
The group syntax can be used together with any other item as well. An example looks like this:
Data element operands can optionally specify attribute option combinations and use wildcards e.g. to specify all category option combination values:
Tip
A great way to learn how to use the analytics API is to use the HRHIS4 pivot table app. You can play around with pivot tables using the various dimensions and items and click Download > Plain data source > JSON to see the resulting analytics API calls in the address bar of your Web browser.
Response formats#
The analytics response containing aggregate data can be returned in
various representation formats. As usual, you can indicate interest in a
specific format by appending a file extension to the URL, through the
Accept HTTP header or through the format query parameter. The
default format is JSON. The available formats and content-types are
listed below.
json (application/json)
jsonp (application/javascript)
xml (application/xml)
csv (application/csv)
html (text/html)
html+css (text/html)
xls (application/vnd.ms-excel)
As an example, to request an analytics response in XML format you can use the following URL:
The analytics responses must be retrieved using the HTTP GET method. This allows for direct linking to analytics responses from Web pages as well as other HTTP-enabled clients. To do functional testing we can use the cURL library. By executing this command against the demo database you will get an analytics response in JSON format:
The JSON response will look like this:
The response represents a table of dimensional data. The headers array gives an overview of which columns are included in the table and what the columns contain. The column property shows the column dimension identifier, or if the column contains measures, the word "Value". The meta property is true if the column contains dimension items or false if the column contains a measure (aggregated data values). The name property is similar to the column property, except it displays "value" in case the column contains a measure. The type property indicates the Java class type of column values.
The height and width properties indicate how many data columns and rows are contained in the response, respectively.
The metaData periods property contains a unique, ordered array of the periods included in the response. The metaData ou property contains an array of the identifiers of organisation units included in the response. The metaData names property contains a mapping between the identifiers used in the data response and the names of the objects they represent. It can be used by clients to substitute the identifiers within the data response with names in order to give a more meaningful view of the data table.
The rows array contains the dimensional data table. It contains columns with dimension items (object or period identifiers) and a column with aggregated data values. The example response above has a data/indicator column, a period column and a value column. The first column contains indicator identifiers, the second contains ISO period identifiers and the third contains aggregated data values.
Constraints and validation#
There are several constraints to the input parameters you can provide to the analytics resource. If any of the constraints are violated, the API will return a 409 Conflict response and a response message looking similar to this:
The httpStatus and httpStatusCode fields indicate the HTTP status and
status code per the HTTP specification. The messsage field provides a
human-readable description of the validation error. The errorCode field
provides a machine-readable code which can be used by clients to handle
validation errors. The possible validation errors for the aggregate analytics
API are described in the table below.
| Error code | Message |
|---|---|
| E7100 | Query parameters cannot be null |
| E7101 | At least one dimension must be specified |
| E7102 | At least one data dimension item or data element group set dimension item must be specified |
| E7103 | Dimensions cannot be specified as dimension and filter simultaneously |
| E7104 | At least one period as dimension or filter, or start and dates, must be specified |
| E7105 | Periods and start and end dates cannot be specified simultaneously |
| E7106 | Start date cannot be after end date |
| E7107 | Start and end dates cannot be specified for reporting rates |
| E7108 | Only a single indicator can be specified as filter |
| E7109 | Only a single reporting rate can be specified as filter |
| E7110 | Category option combos cannot be specified as filter |
| E7111 | Dimensions cannot be specified more than once |
| E7112 | Reporting rates can only be specified together with dimensions of type |
| E7113 | Assigned categories cannot be specified when data elements are not specified |
| E7114 | Assigned categories can only be specified together with data elements, not indicators or reporting rates |
| E7115 | Data elements must be of a value and aggregation type that allow aggregation |
| E7116 | Indicator expressions cannot contain cyclic references |
| E7117 | A data dimension 'dx' must be specified when output format is DATA_VALUE_SET |
| E7118 | A period dimension 'pe' must be specified when output format is DATA_VALUE_SET |
| E7119 | An organisation unit dimension 'ou' must be specified when output format is DATA_VALUE_SET |
Data value set format#
The analytics dataValueSet resource allows for returning aggregated data in the data value set format. This format represents raw data values, as opposed to data which has been aggregated along various dimensions. Exporting aggregated data as regular data values is useful for data exchange between systems when the target system contains data of finer granularity compared to what the destination system is storing.
As an example, one can specify an indicator in the target system to summarize data for multiple data elements and import this data for a single data element in the destination system. As another example, one can aggregate data collected at organisation unit level 4 in the target system to level 2 and import that data in the destination system.
You can retrieve data in the raw data value set format from the dataValueSet resource:
The following resource representations are supported:
json (application/json)
xml (application/xml)
When using the data value set format, exactly three dimensions must be specified as analytics dimensions with at least one dimension item each:
Data (dx)
Period (pe)
Organisation unit (ou)
Any other dimension will be ignored. Filters will be applied as with regular analytics requests. Note that any data dimension type can be specified, including indicators, data elements, data element operands, data sets and program indicators.
An example request which aggregates data for specific indicators, periods and organisation units and returns it as regular data values in XML looks like this:
A request which aggregates data for data element operands and uses CODE as output identifier scheme looks like the below. When defining the output identifier scheme, all metadata objects part of the response are affected:
When using attribute-based identifier schemes for export there is a risk of producing duplicate data values. The boolean query parameter duplicatesOnly can be used for debugging purposes to return only duplicates data values. This response can be used to clean up the duplicates:
Raw data format#
The analytics rawData resource allows for returning the data stored in the analytics data tables without any aggregation being performed. This is useful for clients which would like to perform aggregation and filtering on their own without having to denormalize data in the available data dimensions themselves.
The following resource representations are supported:
json (application/json)
csv (application/csv)
This resource follows the syntax of the regular analytics resource. Only a subset of the query parameters are supported. Additionally, a startDate and endDate parameter are available. The supported parameters are listed in the table below.
The dimension query parameter defines which dimensions (table columns) should be included in the response. It can optionally be constrained with items. The filter query parameter defines which items and dimensions (table columns) should be used as a filter for the response.
For the organisation unit dimension, the response will contain data associated with the organisation unit and all organisation units in the sub-hierarchy (children in the tree). This is different compared to the regular analytics resource, where only the explicitly selected organisation units are included.
To retrieve a response with specific data elements, specific periods, specific organisation units and all data for two custom dimensions you can issue a request like this:
The startDate and endDate parameters allow for fetching data linked to any period between those dates. This avoids the need for defining all periods explicitly in the request:
The filter parameter can be used to filter a response without including that dimension as part of the response, this time in CSV format:
The outputIdScheme parameter is useful if you want human readable data responses as it can be set to NAME like this:
The response from the rawData resource will look identical to the regular analytics resource; the difference is that the response contains raw, non-aggregated data, suitable for further aggregation by third-party systems.
Debugging#
When debugging analytics requests it can be useful to examine the data value source of the aggregated analytics response. The analytics/debug/sql resource will provide an SQL statement that returns the relevant content of the datavalue table. You can produce this SQL by doing a GET request with content type "text/html" or "text/plain" like below. The dimension and filter syntax are identical to regular analytics queries:
Event analytics#
The event analytics API lets you access aggregated event data and query events captured in HRHIS4. This resource lets you retrieve events based on a program and optionally a program stage, and lets you retrieve and filter events on any event dimensions.
Dimensions and items#
Event dimensions include data elements, attributes, organisation units and periods. The aggregated event analytics resource will return aggregated information such as counts or averages. The query analytics resource will simply return events matching a set of criteria and does not perform any aggregation. You can specify dimension items in the form of options from option sets and legends from legend sets for data elements and attributes which are associated with such. The event dimensions are listed in the table below.
Request query parameters#
The analytics event API lets you specify a range of query parameters.
Event query analytics#
The analytics/events/query resource lets you query for captured events. This resource does not perform any aggregation, rather it lets you query and filter for information about events.
You can specify any number of dimensions and any number of filters in a query. Dimension item identifiers can refer to any of data elements, person attributes, person identifiers, fixed and relative periods and organisation units. Dimensions can optionally have a query operator and a filter. Event queries should be on the format described below.
For example, to retrieve events from the "Inpatient morbidity and mortality" program between January and October 2016, where the "Gender" and "Age" data elements are included and the "Age" dimension is filtered on "18", you can use the following query:
To retrieve events for the "Birth" program stage of the "Child programme" program between March and December 2016, where the "Weight" data element, filtered for values larger than 2000:
Sorting can be applied to the query for the event date of the event and any dimensions. To sort descending on the event date and ascending on the "Age" data element dimension you can use:
Paging can be applied to the query by specifying the page number and the page size parameters. If page number is specified but page size is not, a page size of 50 will be used. If page size is specified but page number is not, a page number of 1 will be used. To get the third page of the response with a page size of 20 you can use a query like this:
Filtering#
Filters can be applied to data elements, person attributes and person identifiers. The filtering is done through the query parameter value on the following format:
As an example, you can filter the "Weight" data element for values greater than 2000 and lower than 4000 like this:
You can filter the "Age" data element for multiple, specific ages using the IN operator like this:
You can specify multiple filters for a given item by repeating the operator and filter components, all separated with semi-colons:
The available operators are listed below.
Response formats#
The default response representation format is JSON. The requests must be using the HTTP GET method. The following response formats are supported.
json (application/json)
jsonp (application/javascript)
xls (application/vnd.ms-excel)
As an example, to get a response in Excel format you can use a file extension in the request URL like this:
You can set the hierarchyMeta query parameter to true in order to include names of all ancestor organisation units in the meta-section of the response:
The default response JSON format will look similar to this:
The headers section of the response describes the content of the query result. The event unique identifier, the program stage identifier, the event date, the organisation unit name, the organisation unit code and the organisation unit identifier appear as the first six dimensions in the response and will always be present. Next comes the data elements, person attributes and person identifiers which were specified as dimensions in the request, in this case, the "Gender" and "Age" data element dimensions. The header section contains the identifier of the dimension item in the "name" property and a readable dimension description in the "column" property.
The metaData section, ou object contains the identifiers of all organisation units present in the response mapped to a string representing the hierarchy. This hierarchy string lists the identifiers of the ancestors (parents) of the organisation unit starting from the root. The names object contains the identifiers of all items in the response mapped to their names.
The rows section contains the events produced by the query. Each row represents exactly one event.
In order to have the event analytics resource generate the data in the shape of a ready-made table, you can provide rows and columns parameters with requested dimension identifiers separated by semi-colons as values to indicate which ones to use as table columns and rows. Instead of generating a plain, normalized data source, the event analytics resource will now generate the data in table layout. The column and rows dimensions must be present as a data dimension in the query (not a filter). Such a request can look like this:
Event aggregate analytics#
The /analytics/events/aggregate resource lets you retrieve aggregated
numbers of events captured in HRHIS4. This resource lets you retrieve
aggregate data based on a program and optionally a program stage, and
lets you filter on any event dimension.
The events aggregate resource does not return the event information itself, rather the aggregate numbers of events matching the request query. Event dimensions include data elements, person attributes, person identifiers, periods and organisation units. Aggregate event queries should be on the format described below.
For example, to retrieve aggregate numbers for events from the "Inpatient morbidity and mortality" program between January and October 2016, where the "Gender" and "Age" data elements are included, the "Age" dimension item is filtered on "18" and the "Gender" item is filtered on "Female", you can use the following query:
To retrieve data for fixed and relative periods instead of start and end date, in this case, May 2016 and last 12 months, and the organisation unit associated with the current user, you can use the following query:
In order to specify "Female" as a filter for "Gender" for the data response, meaning "Gender" will not be part of the response but will filter the aggregate numbers in it, you can use the following syntax:
To specify the "Bo" organisation unit and the period "2016" as filters, and the "Mode of discharge" and Gender" as dimensions, where "Gender" is filtered on the "Male" item, you can use a query like this:
To create a "top 3 report" for "Mode of discharge" you can use the limit and sortOrder query parameters similar to this:
To specify a value dimension with a corresponding aggregation type you can use the value and aggregationType query parameters. Specifying a value dimension will make the analytics engine return aggregate values for the values of that dimension in the response as opposed to counts of events.
To base event analytics aggregation on a specific data element or attribute
of value type date or date time you can use the timeField parameter:
To base event analytics aggregation on a specific data element or attribute
of value type organisation unit you can use the orgUnitField parameter:
Ranges / legend sets#
For aggregate queries, you can specify a range / legend set for numeric data element and attribute dimensions. The purpose is to group the numeric values into ranges. As an example, instead of generating data for an "Age" data element for distinct years, you can group the information into age groups. To achieve this, the data element or attribute must be associated with the legend set. The format is described below:
An example looks like this:
Response formats#
The default response representation format is JSON. The requests must be using the HTTP GET method. The response will look similar to this:
Note that the max limit for rows to return in a single response is 10 000. If the query produces more than the max limit, a 409 Conflict status code will be returned.
Event clustering analytics#
The analytics/events/cluster resource provides clustered geospatial event data. A request looks like this:
The cluster response provides the count of underlying points, the center
point and extent of each cluster. If the includeClusterPoints query
parameter is set to true, a comma-separated string with the identifiers
of the underlying events is included. A sample response looks like this:
Event count and extent analytics#
The analytics/events/count resource is suitable for geometry-related requests for retrieving the count and extent (bounding box) of events for a specific query. The query syntax is equal to the events/query resource. A request looks like this:
The response will provide the count and extent in JSON format:
Constraints and validation#
There are several constraints to the input parameters you can provide to the event analytics resource. If any of the constraints are violated, the API will return a 409 Conflict response and a response message looking similar to this:
The possible validation errors for the event analytics API are described in the table below.
| Error code | Message |
|---|---|
| E7200 | At least one organisation unit must be specified |
| E7201 | Dimensions cannot be specified more than once |
| E7202 | Query items cannot be specified more than once |
| E7203 | Value dimension cannot also be specified as an item or item filter |
| E7204 | Value dimension or aggregate data must be specified when aggregation type is specified |
| E7205 | Start and end date or at least one period must be specified |
| E7206 | Start date is after end date |
| E7207 | Page number must be a positive number |
| E7208 | Page size must be zero or a positive number |
| E7209 | Limit is larger than max limit |
| E7210 | Time field is invalid |
| E7211 | Org unit field is invalid |
| E7212 | Cluster size must be a positive number |
| E7213 | Bbox is invalid, must be on format: 'min-lng,min-lat,max-lng,max-lat' |
| E7214 | Cluster field must be specified when bbox or cluster size are specified |
| E7215 | Query item cannot specify both legend set and option set |
| E7216 | Query item must be aggregateable when used in aggregate query |
Enrollment analytics#
The enrollment analytics API lets you access aggregated event data and query enrollments with their event data captured in HRHIS4. This resource lets you retrieve data for a program based on program stages and data elements - in addition to tracked entity attributes. When querying event data for a specific programstages within each enrollment, the data element values for each program stage will be returned as one row in the response from the api. If querying a data element in a program stage that is repeatable, the newest data element value will be used for that data element in the api response.
Dimensions and items#
Enrollment dimensions include data elements, attributes, organisation units and periods. The query analytics resource will simply return enrollments matching a set of criteria and does not perform any aggregation.
Enrollment query analytics#
The analytics/enrollments/query resource lets you query for captured enrollments. This resource does not perform any aggregation, rather it lets you query and filter for information about enrollments.
You can specify any number of dimensions and any number of filters in a query. Dimension item identifiers can refer to any of the data elements in program stages, tracked entity attributes, fixed and relative periods and organisation units. Dimensions can optionally have a query operator and a filter. Enrollment queries should be on the format described below.
For example, to retrieve enrollments in the from the "Antenatal care" program from January 2019, where the "First name" is picked up from attributes, "Chronic conditions" and "Smoking" data elements are included from the first program stage, and "Hemoglobin value" from the following program stage, and only women that have "Cronic conditions" would be included, you can use the following query:
To retrieve enrollments in the from the "Antenatal care" program from last month (relative to the point in time the query is executed), where the "Chronic conditions" and "Smoking" data elements are included from the first program stage, and "Hemoglobin value" from the followup program stage, only including smoking women with hemoglobin less than 20:
Sorting can be applied to the query for the enrollment and incident dates of the enrollment:
Paging can be applied to the query by specifying the page number and the page size parameters. If page number is specified but page size is not, a page size of 50 will be used. If page size is specified but page number is not, a page number of 1 will be used. To get the second page of the response with a page size of 10 you can use a query like this:
Filtering#
Filters can be applied to data elements, person attributes and person identifiers. The filtering is done through the query parameter value on the following format:
As an example, you can filter the "Weight" data element for values greater than 2000 and lower than 4000 like this:
You can filter the "Age" attribute for multiple, specific ages using the IN operator like this:
You can specify multiple filters for a given item by repeating the operator and filter components, all separated with semi-colons:
The available operators are listed below.
Request query parameters#
The analytics enrollment query API lets you specify a range of query parameters.
Response formats#
The default response representation format is JSON. The requests must be using the HTTP GET method. The following response formats are supported.
- json (application/json)
- xml (application/xml)
- xls (application/vnd.ms-excel)
- csv (application/csv)
- html (text/html)
- html+css (text/html)
As an example, to get a response in Excel format you can use a file extension in the request URL like this:
The default response JSON format will look similar to this:
The headers section of the response describes the content of the query result. The enrollment unique identifier, the tracked entity instance identifier, the enrollment date, the incident date, geometry, latitude, longitude, the organisation unit name and the organisation unit code appear as the first dimensions in the response and will always be present. Next comes the data elements, and tracked entity attributes which were specified as dimensions in the request, in this case, the "WHOMCH Chronic conditions" and "WHOMCH smoking" data element dimensions. The header section contains the identifier of the dimension item in the "name" property and a readable dimension description in the "column" property.
The metaData section, ou object contains the identifiers of all organisation units present in the response mapped to a string representing the hierarchy. This hierarchy string lists the identifiers of the ancestors (parents) of the organisation unit starting from the root. The names object contains the identifiers of all items in the response mapped to their names.
The rows section contains the enrollments produced by the query. Each row represents exactly one enrollment.
Support of analytics across tracked entity instance relationships with program indicators#
The non-aggregation enrollment analytics API also supports linking Program Indicators to Relationship Types, in order to show the result of a calculation of a specific Program Indicator applied to the related entities of the listed Tracked Entity Instance.
For the Program Indicator/Relationship Type link to work, the /api/analytics/enrollments/query API requires an additional dimension which must include the chosen Relationship Type UID and the chosen Program Indicator UID:
For example, to retrieve a list of enrollments from the "WHO RMNCH Tracker" program for January 2019 and display the count of Malaria Cases linked to that Enrollment by "Malaria case linked to person" type of relationship, you can use the following query
The API supports using program indicators which are not associated to the "main" program (that is the program ID specified after /query/).
Org unit analytics#
The org unit analytics API provides statistics on org units classified by org unit group sets, i.e. counts of org units per org unit group within org unit group sets.
The API requires at least one organisation unit and at least one organisation unit group set. Multiple org units and group sets can be provided separated by a semicolon.
Request query parameters#
The org unit analytics resource lets you specify a range of query parameters:
The response will contain a column for the parent org unit, columns for each org unit group set part of the request and a column for the count. The statistics include the count of org units which are part of the sub-hierarchy of the org units specified in the request. The response contains a metadata section which specifies the name of each org unit and org unit group part of the response referenced by their identifiers.
The default response is normalized with a single count column. The response can be rendered in a table layout by specifying at least one org unit group set using the columns query parameter.
Response formats#
The org unit analytics endpoint supports the following representation formats:
- json (application/json)
- csv (application/csv)
- xls (application/vnd.ms-excel)
- pdf (application/pdf)
Examples#
To fetch org unit analytics for an org unit and org unit group set:
To fetch org unit analytics data for two org units and two org unit group sets:
To fetch org unit analytics data in table mode with one group set rendered as columns:
Data set report#
Data set reports can be generated through the web api using the
/dataSetReport resource. This resource generates reports on data set
and returns the result in the form of an HTML table.
Request query parameters#
The request supports the following parameters:
The data set report resource accepts GET requests only. The response content type is application/json and returns data in a grid. This endpoint works for all types of data sets, including default, section and custom forms.
An example request to retrieve a report for a data set and org unit for 2018 looks like this:
To get a data set report with a filter you can use the filter parameter. In this case, the filter is based on an org unit group set and two org unit groups:
Response formats#
The data set report endpoint supports output in the following formats. You can retrieve a specific endpoint using the file extension or Accept HTTP header.
- json (application/json)
- pdf (application/pdf)
- xls (application/vnd.ms-excel)
Custom forms#
A dedicated endpoint is available for data sets with custom HTML forms. This endpoint returns the HTML form content with content type text/html with data inserted into it. Note that you can use the general data set report endpoint also for data sets with custom forms; however, that will return the report in JSON format as a grid. This endpoint only works for data sets with custom HTML forms.
The syntax for this endpoint is otherwise equal to the general data set report endpoint. To retrieve a custom HTML data set report you can issue a request like this:
Data usage analytics#
The usage analytics API lets you access information about how people are using HRHIS4 based on data analysis. When users access favorites, an event is recorded. The event consists of the user name, the UID of the favorite, when the event took place, and the type of event. The different types of events are listed in the table.
The usage analytics API lets you retrieve aggregated snapshots of usage analytics based on time intervals. The API captures user views (for example the number of times a chart or pivot table has been viewed by a user) and saved analysis favorites (for example favorite charts and pivot tables). HRHIS4 will capture nightly snapshots which are then aggregated at request.
Request query parameters#
The usage analytics (data statistics) API supports two operations:
POST: creates a view event
GET: retrieves aggregated statistics
Create view events (POST)#
The usage analytics API lets you create event views. The dataStatisticsEventType parameter describes what type of item was viewed. The favorite parameter indicates the identifier of the relevant favorite.
URL that creates a new event view of charts:
A successful save operation returns an HTTP status code 201. The table below shows the supported types of events.
Retrieve aggregated usage analytics report (GET)#
The usage analytics (data statistics) API lets you specify certain query parameters when asking for an aggregated report.
The startDate and endDate parameters specify the period for which snapshots are to be used in the aggregation. You must format the dates as shown above. If no snapshots are saved in the specified period, an empty list is sent back. The parameter called interval specifies what type of aggregation will be done.
API query that creates a query for a monthly aggregation:
Retrieve top favorites#
The usage analytics API lets you retrieve the top favorites used in HRHIS4, and by user.
The API query can be used without a username, and will then find the top favorites of the system.
If the username is specified, the response will only contain the top favorites of that user.
Response format#
You can return the aggregated data in a usage analytics response in several representation formats. The default format is JSON. The available formats and content types are:
json (application/json)
xml (application/xml)
html (text/html)
API query that requests a usage analytics response in XML format:
You must retrieve the aggregated usage analytics response with the HTTP GET method. This allows you to link directly from Web pages and other HTTP-enabled clients to usage analytics responses. To do functional testing use the cURL library.
Execute this command against the demo database to get an usage analytics response in JSON format:
The JSON response looks like this:
Retrieve statistics for a favorite#
You can retrieve the number of view for a specific favorite by using the favorites resource, where {favorite-id} should be substituted with the identifier of the favorite of interest:
The response will contain the number of views for the given favorite and look like this:
Geospatial features#
The geoFeatures resource lets you retrieve geospatial information from HRHIS4. Geospatial features are stored together with organisation units. The syntax for retrieving features is identical to the syntax used for the organisation unit dimension for the analytics resource. It is recommended to read up on the analytics api resource before continuing to read this section. You must use the GET request type, and only JSON response format is supported.
As an example, to retrieve geo features for all organisation units at level 3 in the organisation unit hierarchy you can use a GET request with the following URL:
To retrieve geo features for organisation units at a level within the boundary of an organisation unit (e.g. at level 2) you can use this URL:
The semantics of the response properties are described in the following table.
GeoJSON#
To export GeoJSON, you can simply add .geosjon as an extension to the endpoint /api/organisationUnits, or you can use the Accept header application/json+geojson.
Two parameters are supported: level (defaults to 1) and parent
(defaults to root organisation units). Both can be included multiple times.
Some examples follow.
Get all features at level 2 and 4:
Get all features at level 3 with a boundary organisation unit:
Generating resource and analytics tables#
HRHIS4 features a set of generated database tables which are used as a basis for various system functionality. These tables can be executed immediately or scheduled to be executed at regular intervals through the user interface. They can also be generated through the Web API as explained in this section. This task is typically one for a system administrator and not consuming clients.
The resource tables are used internally by the HRHIS4 application for various analysis functions. These tables are also valuable for users writing advanced SQL reports. They can be generated with a POST or PUT request to the following URL:
The analytics tables are optimized for data aggregation and used currently in HRHIS4 for the pivot table module. The analytics tables can be generated with a POST or PUT request to:
"Data Quality" and "Data Surveillance" can be run through the monitoring task, triggered with the following endpoint:
This task will analyse your validation rules, find any violations and persist them as validation results.
These requests will return immediately and initiate a server-side process.