1. About the DHIS2 instance
The DHIS2 instance for your group project can be found at
<BASE_URL>: https://research.im.dhis2.org/in5320g<NUMBER>
Where <NUMBER> must be replaced with your group number.
For example <BASE_URL>= https://research.im.dhis2.org/in5320g50
Note: This is NOT the same instance as https://data.research.dhis2.org/in5320, which you interacted with in a compulsory course assignment.
You can use these credentials for your instance: User: in5320 Password: P1@tform
You can change the password for your groups' DHIS2 instance after logging in: dhis-web-user-profile/#/account
PS: please note that from time to time, added files may be purged from these instances, which means that you may sometimes have to reupload your app to the instance.
2. DHIS2 data models
DHIS2 has a two-part data model: Data Sets by year, month, week etc. and Tracker Events with data collected on a specific date. In addition, the raw data can be processed by the Analytics API, to provide aggregates along a range of dimensions.
Data collected through the input fields of a data collection form (“data set”), are in DHIS2 linked to three basic dimensions: periods (“when?”), organisation units aka orgunits or simply OU (“where?”) and data elements (“what?”). For periods, the ISO format is used, so that October 2023 becomes “202310”. Your instance contains baseline yearly data for schools, but only for 2020. In relation to your project, this 2020 data can be understood as a yearly school survey which can be used as a baseline for comparison with school inspection data.
For organisation units, the name, uid, or code can be used (though name is seldom used by applications such as those you are developing here, and not all organisation units have code - so in practice you should use the uid). Organisation units are organized hierarchically. This means that an organisation unit can have child organization units and so on. The lowest level can be schools (or even classrooms), while higher levels can be administrative units such as clusters, districts or regions.
3. Useful API documentation
The DHIS2 documentation has a newly implemented AI assistant. Look for the “Ask AI” button in the bottom right corner.
New Tracker - DHIS2 Documentation
Metadata object filters - filtering relevant objects from API endpoints
Metadata field filter - including/excluding relevant properties of objects
dataStore - for storing arbitrary data (should only be used as a last resort)
4. Example API endpoints relevant to the case
Assume that your School Inspector is responsible for Jambalaya Cluster (Jj1IUjjPaWf). The schools are “children” of the cluster node in the orgunit hierarchy/tree.
To list assigned data sets and programs for each school in Jambalaya, nested field filters can be used:
BASE_URL/api/organisationUnits/Jj1IUjjPaWf?fields=name,children[name,id,geometry,dataSets[name,id],programs[name,id]]
The DHIS2 form for school inspection events at AYR Child Learning Center in the Kanifing district in the Gambia can be found at
BASE_URL/dhis-web-capture/index.html#/?orgUnitId=oXTcmBQ3JjJ&programId=UxK2o06ScIe
*You are free to use the screenshot above for inspiration when developing data collection interfaces for your application. However, we encourage you to think critically and creatively around design, terminology, workflow, etc. while taking the provided School Inspection in Edutopia case description and context carefully into consideration.
To get organisation unit (OU) info - e.g. Banjul District (uid RlPlK44dtoo):
BASE_URL/api/organisationUnits/RlPlK44dtoo
To find the OUs in Albion Cluster (plNY03ITg7K) that have geographical coordinates:
BASE_URL/api/organisationUnits?fields=name,geometry&filter=parent.id:eq:plNY03ITg7K&filter=geometry:!null:all
4.1 Identifying forms/data sets and its content
List all programs:
BASE_URL/api/programs
Access all properties of one particular program (excluding the list of assigned orgunits - long and not necessarily relevant if orgunit is already identified)
BASE_URL/api/programs/[program_uid]?fields=*,!organisationUnits
List all data sets:
BASE_URL/api/dataSets
Baseline survey data that we will use for reference exists only for 2020 and can be found in the “EMIS - Primary Tool” data set (uid x0V4c4DxJHE)
Access all properties of one particular data set (excluding the list of assigns orgunits - long and not necessarily relevant if orgunit is already identified)
BASE_URL/api/dataSets/[dataset_uid]?fields=*,!organisationUnits
dataSetElements is a list of all data elements in the data set. The field filter can be used to include their name etc in the listing:
BASE_URL/api/dataSets/x0V4c4DxJHE?fields=dataSetElements[dataElement[id,name,domainType,valueType]]
4.2 Reading aggregate data values
The number of learners in a given school is broken down by grade level (1-7), gender (M/F), and age groups: < 6,6,7,…….13, >13. Thus, the raw data exist in a matrix format along 3 dimensions (category combos), which can be accessed individually. However, the analytics endpoint can sum up all of these cell values.
So for the lower basic school Campama LBS (Banjul) (IT3x07NwCxd), we can try the following:
BASE_URL/api/analytics.json?dimension=dx:ue3QIMOAC7G&dimension=pe:2020&dimension=ou:IT3x07NwCxd
This results in a long response (mostly metadata), with the final part containing the total value (which comes to 142)
"rows": [
[
"ue3QIMOAC7G",
"2020",
"IT3x07NwCxd",
"142"
]
4.3 Events
BASE_URL/api/tracker/events?orgUnit=oXTcmBQ3JjJ&program=UxK2o06ScIe&fields=event,orgUnitName,eventDate,dataValues[dataElement,value]
Sending event
Event payload
{
"events": [
{
"program": "program_uid",
"programStage": "program_stage_uid",
"orgUnit": "org_unit_uid",
"eventDate": "2024-10-14",
"status": "COMPLETED",
"dataValues": [
{
"dataElement": "data_element_uid",
"value": "some_value"
}
]
}
]
}
This can then be POSTed to the api/tracker/events endpoint (or to the older api/events endpoint)
Event analytics: 1.35. Event analytics (dhis2.org)