Whotopia has implemented DHIS2 to support health commodity consumption reporting throughout the public health system. Every month, personnel at each hospital’s- or health clinic’s pharmacy department - the “hospital medical store” - fill in data on commodity consumption, end-balance, and how much to be ordered for the next period as shown in Figure 1. The reports are used by warehouses to determine how many medicines and other medical equipment are to be shipped to hospitals and clinics for the next month. As an increasing number of health facilities have access to desktop computers or tablets, the Ministry now wants an application where health workers can register information on the dispensing of commodities. That is, each time someone comes to collect a certain amount of a commodity, the personnel at the pharmacy store should be able to register the transaction in the application. The application should keep track of these transactions by using the DHIS2 API to store the number of commodities left and automatically update the “Consumption” and “End balance” in the data set shown in Figure 1.
Figure 1: The form for consumption reporting in DHIS2
Existing workflow for dispensing commodities
HISP Whotopia is collaborating with the Ministry of Health and conducted visits to health facilities to understand the workflow related to the dispensing of commodities. The workflow is as follows:
- Medical staff enters the hospital store and requests the hospital store manager for a certain amount of one or several commodities. The number requested is always in number of packs - not singular quantities of the commodity. For instance, medical staff may request seven packs of “Misoprostol”, and two packs of “Magnesium Sulfate”, but never one tablet of “Misoprostol”.
- The hospital store manager checks the stock balance of the requested stocks on a paper-based “stock-balance” form which includes the balance of all available commodities (Figure 2).
Figure 2: Stock Balance Sheet - If the stock is too low on one or several of the requested commodities to serve the request, the hospital store manager negotiates with the medical staff to agree on a reasonable number of commodities given what’s available. The hospital store manager must take into consideration how much stock they have, and how long it is until the next delivery of commodities (shipment of commodities are delivered to the health facilities on the 14th of every month). For instance, if the medical staff requests twenty packs of Misoprostol, the current stock balance is eighteen, and it is two weeks to the next shipment delivery date, the hospital store manager will argue for a much lower number to be dispensed than if a new shipment were to arrive in a couple of days.
- The hospital store manager collects the requested stocks from the shelves and gives these to the medical staff.
- The hospital store manager registers the transaction in a paper-based “transaction” registry (Figure 3), including a) the date and time, b) what commodities and the number dispensed c) the name of the hospital store manager dispensing the commodity, and d) the name and department of the medical staff collecting the commodities.
Figure 3: Commodity dispensing registry - The hospital store manager calculates the updated stock balance and updates the paper-based “stock-balance” form (Figure 2).
Consumption reporting and ordering of commodities
Every month, the hospital store manager fills out and submits the consumption and order form (Figure 1), based on the numbers registered in the “stock-balance” forms filled out during the month.
When a shipment of new commodities arrives
The hospital store manager must update the “stock-balance” form (Figure 2) by adding the number of received stocks with the existing stock balance for each stock.
Dealing with stockouts
The hospitals in Whotopia only get a shipment of commodities on the 14th of every month. When suffering from stock-outs, it is not possible to request commodities besides the standard delivery on the 14th. However, the hospital store managers may attempt to contact the staff at other hospitals to see if they have abundant quantities. As articulated by a hospital store manager:
“People may call from nearby hospitals if they suffer from stock-outs. Then, I check if we have more than we probably need for the remaining time before the next shipment from the main warehouse. If that is the case, I may send a certain amount of stock to the ones suffering from stock-outs”
Infrastructural conditions at the hospitals
All hospitals that are to use the dispensing application have desktop computers or tablets, and electricity available. Internet connectivity may, however, fluctuate throughout the day, sometimes being lost for several hours.
End-user profile
The primary end-user, in this case, is the hospital store manager (HSM). HSMs are typically educated in pharmacy and health logistics and are responsible for the daily operations of the main hospital stores. Their work includes managing the storage of commodities, keeping track of stocks, stock-outs, dispensing of commodities to the other departments at the hospital, and ordering and receiving shipments of stocks from the regional warehouses. There are significant differences in the digital literacy of the HSMs. Some have extensive experience with the use of Microsoft Excel and similar statistical software and use smartphones and tablets as part of their daily life. Others have limited experience with the use of digital technologies and are more accustomed to paper-based information systems.
“What is important for me is that I can run a well-organized hospital store and be able to provide commodities efficiently upon the request of others at the hospital. This means that it is important for me to keep a good and systematic overview of the current stock balances, and past transactions. Sometimes, we are subject to a review from the ministry of health, which means that I must be able to quickly offer statistics of my current stock balance” - HSM at a hospital in Whotopia
Fundamental requirements
In this case, your group is to design and develop a web-based DHIS2 app that supports hospital store managers in registering the dispensing of commodities. You should use the information about workflows and the end-user collected by HISP Whotopia as a basis for the way you design your solution, attempting to build a solution that supports their work in a way that makes sense. As a bare minimum, your solution should address the following fundamental requirements:
- Users should be able to register when a commodity is dispensed
- The data set “Life-Saving Commodities” in the DHIS2 instance should be updated accordingly (adding to the consumption, and subtracting from the end-balance of the current month)
- The application should retrieve the listed commodities from the “Life-Saving Commodities” data set. If new commodities are added to the data set, these should be available in your application.
Beyond these, it is up to your group to ideate, prototype, and decide how you will design and develop a solution that can support the process of dispensing commodities, and potentially relevant associated activities.
Technical starting point
Background
Data values, such as those collected through the input fields of a data collection form (data set), are in DHIS2 linked to three key dimensions: periods (“when?”), organisation units (“where?”) and data elements (“what?”). For periods, the ISO format is used, so that October 2021 becomes “202110”. 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).
Data elements are a bit more complicated, as they can be disaggregated (i.e. broken down into smaller entities) by categories with options. Categories can be combined in category combinations, where the combination of the options of all included categories becomes category option combinations (or catoptioncombo). For the data element dimensions, data values are thus associated with both a data element (name, code, uid) and catoptioncombo (name, code, uid).
|
Object |
Description |
Example |
|
Data element |
The main definition of the data value, the “what?” of the data. |
Children |
|
Category |
Defines a breakdown/disaggregation of the data. |
Age |
|
Category options |
The different breakdowns (options) of a category |
0-11 months; 1+ year |
|
Category Combination |
The combination of one or more categories. |
Age and sex |
|
Category option combination |
The combined options of the categories in the category combination. |
0-11 months, female; 0-11 months, male; 1+ year, female; 1+ year, male |
Data elements in the “Life saving commodities” data set you’ll be working on in this case are disaggregated by the category combination “Commodities” (gbvX3pogf7p), which only consists of one category (also called “Commodities”), and the category option combinations thus have the same name and definition as the category options! However, they are different metadata objects with different identifiers, and it is the category option combinations that must be used when reading and submitting data. This is illustrated in the figure below.
(Whole data sets can also be disaggregated, meaning that data values can have yet another dimension (referred to as attributeOptionCombination), but this can be ignored for the purpose of this assignment.)
Storing data beyond the Life Saving Commodities data set
To store data that is not part of any data set, you may use the dataStore API endpoint. This endpoint allows developers to store arbitrary data linked to a namespace and key. Apps can reserve a specific nameSpace, which means that only users with access to that app can access the nameSpace. Non-reserved namespaces are accessible for any user. In this assignment, the dataStore can be used to store data on commodity transactions.
Note: use of the dataStore is not ideal for the large amounts of transactions/data that would be expected in a real implementation of this app, but it can be used for the purpose of this project.
Key API docs
-
Metadata object filters - filtering relevant objects from API endpoints
-
Metadata field filter - including/excluding relevant properties of objects
-
Reading data values - fetching data values for entire data sets
-
Sending data values - submitting multiple data values for one period and orgnaisation units (i.e. a data set)
-
Reading/sending individual data values - getting and setting individual data values
-
dataStore - for storing arbitrary data
Example API endpoints with relevance for the case
Identifying relevant organisation units
Fetch organisation unit(s) to which current user is assigned. End users involved in data entry will typically be “assigned” to a district or health facility, depending on their role. If assigned to a district, data entry is still generally done for individual health facilities, thus the “children” of the organisation unit district users are assigned to.
/api/me.json?fields=id,name,organisationUnits
To list forms (data sets) associated with an organisation unit:
/api/organisationUnits/[orgunit uid].json?fields=name,id,dataSets
To include “children” or the orgunit and their assigned data sets, nested field filters can be used:
/api/organisationUnits/[orguinit_uid].json?fields=name,id,dataSets[name,id],children[name,id,dataSets[name,id]]
Identifying forms/data sets and its content
List all data sets:
/api/dataSets.json
Access all properties of one particular data set (excluding the list of organisation units which can be very long and not necessarily relevant if orgunit is already identified)
/api/dataSets/[dataset_uid]?fields=*,!organisationUnits
dataSetElements is an array 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:
api/dataSets/[dataset_uid]?fields=dataSetElements[dataElement[name, *]]
It’s also possible to include categorycombo and catoptioncombos for the data elements in dataSetElements:
/api/dataSets/ULowA8V3ucd.json?fields=name,id,dataSetElements[dataElement[name,id,categoryCombo[name,id,categoryOptionCombos[name,id]]]
Reading data values
To fetch the current values for all fields in a data set, the dataValueSets endpoint can be used. For example, to get the data values for the “Life saving commodities” data set (ULowA8V3ucd), for the period October 2021 (202110) for the organisation unit “Faabu CHP” (ZpE2POxvl9P):
/api/dataValueSets.json?dataSet=ULowA8V3ucd&period=202110&orgUnit=ZpE2POxvl9P
To get the data values for a single data element (commodity), we can use the dataValues endpoint. To get the data values for “Female condom” (dY4OCwl0Y7Y) data element and “End balance” (J2Qf1jtZuj8) catoptioncombo, for the same period and organisation unit:
/api/dataValues.json?de=dY4OCwl0Y7Y&pe=202110&ou=ZpE2POxvl9P&co=J2Qf1jtZuj8
Sending data values
Multiple data values for a data set (e.g. “Life saving commodities”) can be submitted by POSTing a json-file to /api/dataValueSets. This object/file should be in the below format (described further here), using the same orgunit, period and dataset as above as an example:
{
"dataSet": "ULowA8V3ucd",
"resource":"dataValueSets",
"completeDate": "2021-11-04",
"type": "create",
"data": {
"orgUnit": "ImspTQPwCqd",
"period": "202106",
"dataValues": [
{
"dataElement": "dY4OCwl0Y7Y",
"categoryOptionCombo":
"J2Qf1jtZuj8",
"value": "12"
}
]}
}
To update a single data value, the dataValues endpoint is used. Here, the value is included as a parameter in the POST request, rather than as a separate json file/object:
/api/dataValues.json?de=dY4OCwl0Y7Y&pe=202110&ou=ZpE2POxvl9P&co=J2Qf1jtZuj8&value=12