Commodity Dispensing

The Ministry of Health staff conducted visits to health facilities to understand the workflow related to the dispensing of commodities. The most common workflow is as follows:

1. 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 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”. 
2. 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
3. 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.  
4. The hospital store manager collects the requested stocks from the shelves and gives these to the medical staff.
5. 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
6. 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”
 

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. However, many acting HSMs are currently not meeting these qualification requirements due to recruitment challenges. 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.

A recent assessment found problems of missing data, incorrect data, arithmetical errors, and duplicate data among others. The general lack of on the job training appears to have a negative impact on HSMs understanding of the data collection tools and data quality issues.

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

Beyond the fundamental requirements, you should address at least two of the use cases  and their corresponding requirements described below. The minimum requirements described for each is what needs to be implemented as a minimum in order for your solution to be considered as having addressed the use case. Think carefully about which one of these requirements goes well together and could comprise a coherent whole.

1. Store management

Every month, the store manager receives a new delivery of commodities to replenish the hospital store. When this happens the HSMs need 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 shipments of dozens of different commodities are received at the store
• the data set “Life-Saving Commodities” should be updated, and a stock replenishment “transaction” should be recorded

2. Stock level monitoring

With stock replenishments only happening once per month, it is important for the HSMs to ensure as much as possible that stocks last through to the 14th every month. Currently, this is done based on the HSMs experience with how much of each commodity is typically dispensed, and the stock balance at any given time. Based on this, they may restrict the amount they allow to be dispensed at a given time. With an electronic stock dispensing system, data is available to provide some decision support to the HSMs when doing such assessments. For example looking at the quantities and the number of dispenses happening in previous periods, stock balance trends, days until next replenishment (14th of the month) etc.

Minimum requirements:

• Provide the HSMs with decision support functionality that helps assess how much of a commodity can be dispensed at a particular day without risking stock-outs

3. Requests commodities from other health facilities (orgunits)

When a health facility is out or critically low on stock, they may request an urgent transfer of commodities from nearby facilities, which we consider here as other health facilities within the same health district (sharing organization unit “parent”). Since all health facilities use the same online information system, it is possible to analyze the current stock balance of other facilities, so that HSMs know where they could request transfers. Since the number of commodities could be large, the solution should ensure that this information is presented in a targeted manner.

Minimum requirements: 

• provide HSMs with an overview of available stock in nearby health facilities, to help identify where there is potential for receiving a direct transfer

4. Improved management of commodity recipients

Entering the name and department of the medical staff to which commodities are dispensed as free text can be inefficient, and makes later analysis of the data difficult since there could be differences in how names and departments are spelled. Because medical staff to which commodities are dispensed are often in a hurry, it is important that new registrations do not introduce unnecessary delays.

Minimum requirements:

• develop a solution that allows medical staff 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 (fundamental requirement)

5. Stock recounts

At regular intervals, the HSMs 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 HSMs 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

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). 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).

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