This page provides acts as the software requirement specification for the This page provides acts as the software requirement specification for the OpenLMIS and OpenSRP integration for the minimum viable product integration for stock management.
...
Commodity Type: Classification of commodity. An example in OpenLMIS is product code BCG20. BCG20 is a 20 dose vial of BCG. When we order items in OpenLMIS, we don't care which trade item is sent, we just need the specific commodity type.
Dispensing Unit: A dispensing unit is the basic unit that a patient receives when the clinician or pharmacist provides them a product. Product inventory and usage is generally tallied and reported in dispensing units, as part of the requisitioning process.
Lot: A collection of trade items of the same type that were all manufactured at the same time from a single manufacturer. Each lot has an identification number and expiration date. Each lot has passed laboratory to test composition before release to the market.
Net Content: The amount of dispensing units contained in each pack
Program: A program is an independently funded project that is implemented in OpenLMIS and OpenSRP. Each Program has a specific set of Orderables, a complex configuration including Requisition Form settings and Program-specific user permissions, and a network of Facilities that are participating in the Program.
Trade item: An item meant for trade that commonly has a specific manufacturer and are defined outside of OpenLMIS. An example of a trade item in OpenLMIS is product code Intervax BCG 20. This is a trade item that is branded by Intervax and fulfills the BCG20 commodity type that would be ordered.
...
- OpenLMIS GET Endpoints:
- Reference Data Service
- CommodityTypes - Returns an array of all commodityTypes in the system
- CommodityTypes/{id} - Returns a specific commodity type
- facilities/minimal - Returns an array of facilities with id and name only
- facilities/{id} - Returns a specific facility
- geographicLevels - Returns an array of geographicLevels
- programs - Returns an array of all programs
- programs/{id} - Returns a specific program
- stockAdjustmentReasons - Returns an array of stockAdjustmentReasons
- stockAdjustmentReasons/{id} - Returns a specific stock adjustment reason
- tradeItems - Returns an array of tradeItems
- tradeItems/{id} - Returns a specific tradeItem
- Stock Management Service
- stockCardLineItemReasons - Returns an array of stockCardLineItemReasons
- stockCardLineItemReasons/{id} - Returns a specific stock card line item reason
- stockCards - Returns an array of stock cards, result is an intersection of user rights and request parameters.
- stockCards/{id} - Returns a specific stock card
- validDestinations - Get a list of valid destinations of a program and a facility type.
- validReasons - Return a list of valid reasons based on program and facility type.
- Reference Data Service
- OpenLMIS POST Endpoints:
- Stock Management Service
- stockEvents - Create a new stock event with one or more orderables
- Stock Management Service
- OpenSRP GET Endpoints:
- stockresource/getall - Returns a list of stock events
- OpenSRP POST Endpoints:
- stockresource/add - Add a stock event to the OpenSRP server
There are a number of resources that may need to be created in OpenSRP server. Below is a list of items that may need to be created:
- GET a list of locations by geographic hierarchy
- GET a list of programs, trade items and commodity types
- GET a list of reasons
- POST additions and updates to programs, trade items and commodity types
- POST additions and updates to reasons
...
Feature Stock Management-1: Allow for the dynamic population of the stock landing view based on server side configuration of programs, commodity types and trade items (Workflow 1).
Stock Card View
Once a user touches the trade item from the landing view, they are directed to the Stock Card View. This view is the primary area where stock is managed for a particular trade item. This view will not change significantly but the information on it will be populated from the trade item and lot metadata that is imported from OpenLMIS (Workflow 1).
Changes to be made:
- Stock Control > OPV: The text "OPV" will be populated based on the trade item name that's imported by OpenLMIS
- OPV Stock: This will be populated based on the trade item name
- 13 vials: The number of vials will be populated based on the metadata from the trade item information imported by OpenLMIS, including the unit of measure
- (New) Number of Doses: We will add an item approximating the number of doses available based on the metadata that's imported from OpenLMIS
- (New) Lot and Expiration Date: Display the lot and expiration date information if activated
- Note: stock numbers are in vials: This item in the bottom will be populated based on the unit of measure for the trade item.
...
Stock Card View - Received
...
When the user touches the "received" button on the screen above, they will be redirected to a page to enter new orderables that were receiveda stock event that receives an individual trade item, crediting the stock on hand (Workflow 2).
Changes to be made:
- OPV Stock Received: The blue header text "OPV" will be dynamically populated based on the name of the orderabletrade item
- Date OPV stock received: The text "OPV stock" will be dynamically populated based on the name of the orderable. No functionality will removed and it will just say "Date received". No functionality will change on this widget
- Reason: This is populated from a list of valid stock card line item reasons from OpenSRP server (originally from OpenLMIS).
- Received from: This radio button will change to two fields:
- Location: A location hierarchy widget will be available based on the OpenLMIS OpenSRP locations. We require We require the OpenLMIS locations in this widget because they may have a number of dispensaries that are not captured in the OpenMRS/DHIS2 location hierarchy.CHW: A list of CHWs will be available in a single select menu so users can choose a CHW when they are returning stock that was previously issuedNote that this assumes there is a one-to-one match between locations in OpenSRP and OpenLMIS.
- Other: This is a field that allows them to type in text if not from a location that's in the hierarchy.
- Vials OPV received: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the orderable imported from OpenLMIS
- (new) VVM: A radio button will be displayed with the VVM number (1-4)
...
- Note: We may have a problem here if another location tracks lots and the lot isn't available already on this device.
Navigation:
We will not change the navigation on this view.
Discussion: Do we need to account for open vials?
Stock Card View - Issued
When the user touches the "Issued" button from the Stock Card View - Current Stock View, they will be redirected to a page to enter a new orderables that were receivedstock event that debits the stock on hand (Workflow 2).
Changes to be made:
- OPV Stock Issued: The blue header text "OPV" will be dynamically populated based on the name of the orderabletrade item
- Date OPV stock issued: The The text "OPV stock" will be dynamically populated based on the name of the orderableremoved and it will just say "Date received". No functionality will change on this widget.
- Reason: This is populated from a list of valid stock card line item reasons from OpenSRP server (originally from OpenLMIS).
- Issued to: This radio button will change to two fields:
- Location: A location hierarchy widget will be available based on the OpenLMIS OpenSRP locations. We require We require the OpenLMIS locations in this widget because they may have a number of dispensaries that are not captured in the OpenMRS/DHIS2 location hierarchy.CHW: A list of CHWs will be available in a single select menu so users can choose a CHW to allocate stock toNote that this assumes there is a one-to-one match between locations in OpenSRP and OpenLMIS.
- Other: This is a field that allows them to type in text if not from a location that's in the hierarchy.
- Vials OPV issued: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the orderable trade item imported from OpenLMIS
- (new) VVM: A radio button will be displayed with the VVM number (1-4)
- Wasted Vials: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS
- (new) Wasted Reason: If the "Wasted Vials" field is populated, a new "Wasted Reason" field will display with a radio button that's populated by the OpenLMIS program specific adjustment metadata. If the users are able to enter a free text reason, this radio button will include an "other" option that will toggle the next field(new) Wasted Reason Free Text Field: This field will be displayed if the orderable includes a Boolean operator stating that users can enter a free text reason for wastage
- Note: The suggested number of vials will be based on the number of children immunized today by commodity type. It's possible that this calculation will be inaccurate if there are multiple lots for a particular commodity type that were used for a particular day. Maybe we can perform a smarter calculation here based on the total stock on hand for this trade item and lot compared to the number of children immunized today minus any other trade item debits that also happened today to this same location.
Navigation:
We will not change the navigation on this view.
Discussion:
...
...
Stock Card View - Loss/Adjustment
When the user touches the "IssuedLoss/Adjustment" button from the Stock Card View - Current Stock View, they will be redirected to a page to enter losses and adjustments.an adjustment stock event which is either a debit or credit (Workflow 3).
Changes to be made:
- OPV Stock Loss/Adjustment: The blue header text "OPV" will be dynamically populated based on the name of the orderabletrade item
- Date OPV stock loss/adjustment: The The text "OPV stock" will be dynamically populated based on the name of the orderableremoved and it will just say "Date received". No functionality will change on this widget.
- Reason for OPV adjustment: The text "OPV" will be dynamically populated based on the name of the orderable. Additional items will be added to the radio button:
- Wastage
- Expiration
- VVM/CCE Failure
- If Wastage is selected display the following fields
- (new) Wasted Reason: This field will display with a radio button that's populated by the OpenLMIS program specific adjustment metadata. If the users are able to enter a free text reason, this radio button will include an "other" option that will toggle the next field
- (new) Wasted Reason Free Text Field: This field will be displayed if the orderable includes a Boolean operator stating that users can enter a free text reason for wastage
- Vials OPV adjustment: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the orderable
- Vials OPV adjustment: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the trade item imported from OpenLMIS
- Business Logic Change: If Wastage, Expiration or VVM/CCE failure are selected, only negative integers will be able to be saved.
...
We will not change the navigation on this view.Discussion: Do we need to add any other reasons for adjustment? Should this be a dynamic field?
Stock Card View - Stock Planning
When the user touches the "Stock Planning" tab from the Stock Card View - Current Stock View, the following tab will open.
Changes to be made:
...
This view needs to be reviewed for value to the end user. We're not sure if it adds value at the trade item and lot level. It would be a much better view at the commodity type level.
Changes to be made:
- Stock Control > OPV:
- The text "OPV" will be dynamically populated based on the name of the trade item
- Units will be displayed in parenthesis based on the metadata populated from OpenLMIS
- OPV Planning: The text "OPV" will be dynamically populated based on the name of the orderabletrade item
- 3 month OPV stock levels:
- The text "OPV" will be dynamically populated based on the name of the orderabletrade item.
- The business logic for this graph will have to change: The y-axis will only display whole numbers, not decimals
- 3 month OPV stock used:
- The text "OPV" will be dynamically populated based on the name of the orderabletrade item.
- Units will be displayed instead of the text "vials" in the table based on the metadata populated from OpenLMIS
- Current OPV stock:
- The text "OPV" will be dynamically populated based on the name of the orderabletrade item
- Units will be displayed instead of the text "vials" in the table based on the metadata populated from OpenLMIS
- Number of active children: no changes to this section
- Due OPV next month Mar 2018:
- The text "OPV" will be dynamically populated based on the name of the orderablecommodity type
- Units will be displayed instead of the text "vials" in the table based on the metadata populated from OpenLMIS
- The business logic will have to change based on the orderable number of doses available by commodity type that is populated by OpenLMIS
- For example:
- If we are viewing oral syringesrota 1, the calculation is 1 syringe dose per child.Open container policies need to be added in this calculation. OPV, for example, has approximately a 28 day open container policy, allowing 1 vial to be used over the entire month, but if it's a different type of Rota, it may be a 2 vial dose.
- For example:
- Average OPV waste rate: The text "OPV" will be dynamically populated based on the name of the orderabletrade item
Navigation:
We will not change the navigation on this view.Discussion: Who is the target audience for this view? Does this view need to be augmented with any other information like wastage reasons?
Underlying Business Logic Changes
Currently, the business logic involved in consumption, wastage and prediction are all hardcoded based on the stockType. We will need to add the feature to dynamically define the stock card business logic that's run on the Android client based on the number of doses per vial for each trade item. This business logic needs to be scoped for each commodity type of orderable that is part of the vaccine program. This business logic , along with other information, needs to can be defined in the server and synced to the Android Client.
Discussion:
- Does OpenLMIS provide any business logic as a service that can be consumed at the "orderable level"?
- Can we scope a specific sample set of vaccines that we will target in the MVP?
- Which business logic is OpenLMIS specific and which is OpenSRP specific (orderable vs. consumption)?
I'm wary of dynamic business logic, would this look like a set of algerbraic functions that all must be satisfied?
...
based on the information we get from the OpenLMIS APIs.
Bulk Orderable Update
---START HERE---
The current stock control view focuses on single stock card transactions one orderable at a time. We will add a new area to the Android client that allows dispensary technicians to make changes to multiple orderables. This user interface is targeted at store managers who need to issue, adjust or receive multiple orderables in a single transaction. Examples include issuing multiple orderables to a single third party, stock take adjustments, large wastage adjustments and receive a shipment.
...