Stock Management in Whotopia
Insufficient health services make large parts of the population of Whotopia vulnerable. Almost half of all health facilities in Whotopia are short on essential drugs. Discrepancies between drug distribution and actual use have led to critical stock-outs in some health facilities while there is overstocking and wastage in other facilities. This has hampered the government’s effort to minimize morbidity and mortality from curable diseases such as malaria and tuberculosis.
Whotopia has implemented DHIS2 to support logistics management. Every month, each clinic’s pharmacy department - the “medical store” - fills in data on commodity consumption, end-balance, and estimate how much to be ordered for the next period as shown in Figure 1. The reports are used by regional warehouses to determine the quantity of medicines and other commodities to ship to clinics the next month.
As an increasing number of clinics have access to desktop computers or tablets, the Ministry of Health now wants a DHIS2 application for stock management. That is, each time someone collects a certain amount of a commodity; the personnel at the store should 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
Stock management workflow
Whotopia Ministry of Health staff visited clinics to document existing stock management workflows. The most common workflow is as follows:
- Medical personnel enters the medical store and requests a certain amount of one or more commodities from the store manager. The request is always in the 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 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 balance is too low for one or more of the requested commodities, the store manager negotiates with the medical personnel to agree on a reasonable number of commodities. The store manager should take into consideration how much stock is left, and how long it is until the next delivery of commodities (commodities are delivered to clinics on the 14th of every month). For example, if the medical personnel requests twenty packs of Misoprostol, the current stock balance is eighteen, and it is two weeks to the next shipment delivery date, the store manager will suggest a much lower number to be dispensed than if a new shipment were to arrive in a couple of days.
- The store manager collects the requested stocks from the shelves and gives these to the medical personnel.
- The 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 store manager dispensing the commodity, and d) the name and department of the medical personnel receiving 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 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 store manager must update the “stock-balance” form (Figure 2) by adding the number of received stocks to the existing stock balance for each stock.
Dealing with stock-outs
The clinics 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 store managers may attempt to contact the store managers at other clinics to learn if they have surplus stocks. As articulated by a hospital store manager:
“People may call from nearby clinic 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 regional warehouse. If that is the case, I send a certain amount of stock to the ones suffering from stock-outs”
Infrastructural conditions
All clinics that will use the stock management application have desktop computers or tablets. Stable electricity is accessible through the power grid or from generators. However, internet connectivity fluctuates throughout the day, Sometimes connectivity is lost for several hours. The most frequently mentioned challenges to using computers and tables is inconsistent network access and the high cost of mobile data.
Store manager profile
The primary end-user is the store manager. Store managers are typically educated in pharmacy and logistics and are responsible for the daily operations of the medical stores. However, some acting store managers are currently not meeting the qualification requirements. Some medical stores are managed by staff at the clinic that are not formally trained pharmacists nor logistics experts. At some clinics it has been difficult to recruit qualified staff, while at others there is not sufficient funding to employ a dedicated store manager.
Their store managers work includes managing the storage of commodities, keeping track of stocks, stock-outs, dispensing of commodities, and ordering and receiving shipments of stocks from the regional warehouses.
A recent assessment carried out by the Ministry of Health found problems of missing data, incorrect data, arithmetical errors, and duplicate data. The general lack of on the job training appears to have a negative impact on store managers understanding of the data collection tools and data quality issues.
There are significant differences in the digital literacy levels of the store managers. Some have extensive experience with the use of 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 medical store and be able to provide commodities efficiently. 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 balances” - Store manager at a clinic in Whotopia
Fundamental requirements
Your group is requested to design and develop a web-based DHIS2 app that supports the work of store managers. You should use the information about workflows, the context, and the end-user as a basis for how you design your solution. As a bare minimum, your solution must address the following three fundamental requirements:
- Store managers must be able to register when a commodity is dispensed, with the information described above
- The data set “Life-Saving Commodities” in the DHIS2 instance must be updated (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.
It is up to your group to ideate, prototype, and decide how you will design and develop a solution that can support stock management. However, in addition to the fundamental requirements, you must implement at least two of the requirements described in the next section, called “additional requirements”.
Additional requirements (implement at least two!)
Beyond the fundamental requirements, you should address at least two of the additional requirements described below. The minimum requirements described for each is what must be implemented. Consider carefully which requirements goes well together and would comprise a useful and coherent whole. When in doubt about the use context of the application, please record the assumptions you make in order to arrive at application design and development decisions.
1. Store management
Every month, the store manager receives a new delivery of commodities to replenish the medical store. The store manager needs to efficiently update the stock balance according to the exact quantities received of each commodity, and this information must be recorded.
Minimum requirements:
- develop an interface that supports efficiently updating stock balances when dozens of different commodities are received at the medical store
- the data set “Life-Saving Commodities” should be updated, and a stock replenishment “transaction” should be recorded
2. Stock level monitoring / prediction
It is important for the store manager to ensure that stocks last through to the 14th every month. Currently, this is done based on the store managers' personal experience with how much of each commodity is typically dispensed, and the stock balance at any given time. With a digital stock management application, data is available to provide some decision support to the store manager. For example, it is possible to look at the quantities and the frequencies of dispenses in previous periods, stock balance trends, days until next replenishment (14th of the month), etc.
Minimum requirements:
- Provide the store manager with decision support functionality that helps assess how much of a commodity can be dispensed at a particular time without high likelihood of stock-outs
3. Requests commodities from nearby clinics (other orgunits)
When a clinic is critically low on stock, they may request an urgent transfer of commodities from nearby clinics. Nearby clinics are other clinics within the same health district and they will are share the same "parent" organization unit. Since all clinics interact with the same database, it is possible to assess the current stock balance of nearby clinics, so that store manager knows from where they might request a transfer.
Minimum requirements:
- provide store managers with an overview of available stocks in nearby clinics, to help identify where there is potential for receiving a transfer
4. Improved management of commodity recipients
Entering the name and department of the medical personnel to which commodities are dispensed as free text can be inefficient, and makes later analysis of the data difficult. Because medical personnel are often in a hurry, it is important that new registrations of commodity recipients do not introduce unnecessary delays.
Minimum requirements:
- develop a solution that allows medical personnel and hospital departments to be stored/persisted in the database, to be used as “recipients” during commodity dispensing
- the functionality to persist names/departments should be integrated in the function to register when a commodity is dispensed (see fundamental requirement)
5. Stock recounts
At regular intervals, the store managers need to perform recounts of the actual stock at hand, to verify that the stock balance in DHIS2 (“Life-Saving commodities”) corresponds to the physical stock in the medical store. This involved the store manager physically counting the number of packs/items of each commodity in the store, one by one, and updating the “stock balance sheet” (figure 2). Since the recounts are only documented as updates in the stock balance form, it is difficult to analyze the data, for example to identify if certain commodities tend to systematically disappear from the store.
Minimum requirements:
- develop a solution tailored for a physical stock recount workflow
- the data set “Life-Saving Commodities” should be updated, and a stock recount “transaction” should be recorded for discrepancies
6. Sandbox mode
As the store managers profiles vary in terms of experience and digital literacy, the Ministry of Health would like the application to have a "sandbox" or training mode where the user can test the flow of the application and get more tips and guidance on how to use the application. Any changes to stock balances etc. made in the sandbox mode should not be stored permanently.
Minimum requirements:
- develop a sandbox mode that allows the user to test and experience the main workflows of the application and receive additional tips and guidance
- include user feedback that is beneficial for novice users but not deemed necessary for the day-to-day use of the application
7. Offline features (warning: can be relatively challenging to implement)
The stock management application will be used in a setting with intermittent internet connectivity. The Ministry of Health wants the application to support offline workflows in periods where internet connectivity is lost so that stock management work can continue to be carried out and data can be synchronized when internet connectivity is restored.
Minimum requirements:
- develop offline support for essential stock management workflows (see fundamental requirements) while making sure data integrity is not compromised
8. Analytics dashboard
Sometimes, in order to discover trends and patterns in commodity consumption or discrepancies in effective stock management, it is useful to look at statistics in the form of graphs, tables, charts or maps. An analytical summary can also be useful in the case of a sudden inspection conducted by the central unit at the Ministry of Health.
Minimum requirements:
- develop an analytics dashboard with visualization of relevant indicators pertaining to the stock management at the clinic. You should at the very least find good ways to represent the information mentioned as relevant in the case of a review / inspection.
9. Manage bulk operations
As most medical personnel require dispensing of more than one commodity at the same time, it is necessary to support a workflow where multiple commodities can be selected for dispensing, verified, and registered in one bulk operation.
Minimum requirements:
- develop support for bulk operations to verify and dispense multiple commodities
Technical starting point
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 2023 becomes “202310”. 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 based on the organizational structure of the organization it is supposed to represent. This means that an organisation unit can have child organization units and so on. The lowest level in the organisation unit hierarchy can be health facilities or hospitals, while higher levels can be administrative health units such as districts or regions.
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 2023 (202310) for the organisation unit “Faabu CHP” (ZpE2POxvl9P):
/api/dataValueSets.json?dataSet=ULowA8V3ucd&period=202310&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=202310&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": "2023-11-04",
"type": "create",
"data": {
"orgUnit": "ImspTQPwCqd",
"period": "202306",
"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=202310&ou=ZpE2POxvl9P&co=J2Qf1jtZuj8&value=12