Case 1 - Commodity Dispensing

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:

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

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

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