Goals/Scope
- To connect the requisition and stock management service
Background
OpenLMIS 3.1.0 works as described below. The Requisition service and Stock service have totally separate data about adjustments and stock-on-hand. So the following is proposing ways to connect them.
Requisition | ≉ | Stock |
|---|---|---|
| Monthly/periodic report | Can be entered monthly or in real-time | |
| Adjustments, transfers, and SOH as of period end date, but adjustments and transfers don't each have a date | No Match in Data Model | Adjustments (with different list of reasons in Stock service), physical inventories (SOH as of a date), future: issues/transfers |
Requisition:
- Requisition service has data submitted monthly/periodically.
- Has adjustments, but not recorded by Lot and not with a date.
- Has a stock-on-hand number for the end of the reporting period (similar to a Physical Inventory).
- Has transfers/issues/receiving, but all of that is "one-sided", meaning it records the local facility's perspective on what they received in, issued for use, or transferred out, but there is no data connection to the other facilities involved or to PODs or orders. If Facility A transfers 100 units to Facility B, each facility will record that adjustment on their Requisition form at the end of the month, and those two transactions will not be connected to each other in a machine-readable way.
- Requisition forms may be skipped or facilities may miss a period.
- Emergency Requisitions may also have some adjustments and an SOH balance recorded, but that data may have overlap with the Regular Requisition submitted at the end of the month/period.
Stock:
- Stock service has data that can be recorded in real-time or can be entered at the end of a month/period.
- Has adjustments, including with Lot and Date.
- Has physical inventories that capture a stock-on-hand number on a Date.
- Physical inventories may be skipped or facilities may miss a period. (no enforcement currently)
- Future: May have transfers/issues/receiving. The current system in development has a "one-sided" way to capture these, and a "two-sided" issuing/receiving process is a top feature we hope to achieve for the 3.1 release.
There is NO MATCH in OpenLMIS 3.1.0 between the Requisition and Stock service. Their data models are entirely different for the stock adjustments and stock-on-hand numbers. They both can refer to the same catalog of products, the same facilities and same programs, but the stock data itself is totally different. They have two different APIs for configuring Reasons and getting lists of valid reasons.
Usage Scenarios
Malawi 2017
Using the Requisition service in OpenLMIS 3.x.x, and Stock service is not present or not enabled (maybe not even in docker-compose file). So they are using a monthly R&R process, but not conducting physical inventories and not using "electronic bin cards" in the OpenLMIS stock service. They are likely doing bin cards and inventories on paper only.
Malawi Future
Turn on the Stock service to begin recording real-time adjustments on the "electronic bin card" and doing physical inventories in OpenLMIS.
- There are a few open questions about moving from Malawi 2017 to Malawi Future scenario: When they turn on Stock service, would they begin using it one program at a time, one facility at a time, or perhaps only for selected products but not all products in a program?
- When they turn on Stock service, would they want any of their historical Adjustments that were recorded on past Requisition forms to be visible within the Stock UI? Which ones? Why (what use will this serve?)
Mozambique 2017
Using two installations of OpenLMIS v1/v2, one for informed push with the Distribution Form (SELV; see https://openlmis.atlassian.net/wiki/display/OP/Program+Data+Example%3A+SIIL+and+SELV+Distribution+Form, especially the EPI tabs), and another to power the ESMS tablet app for stock management.
- Is there any overlap between these two installations in terms of programs and facilities?
Mozambique Future
Migrate both to one installation of OpenLMIS 3.
- Do we know any more? Would the ESMS app use only the Requisition service of OpenLMIS 3, or only the Stock service, or use both? The SELV Distribution Form does not exist in OpenLMIS 3 yet. That informed push functionality would likely be built into OpenLMIS 3.3 during the Vaccines work. Even then, Mozambique may still have a "gap" to migrating to version 3 that will be identified during the Gap Analysis project.
Modes of Operation
- Requisition Only (currently supported; e.g., Malawi 2017)
- Stock Only (Question: would any countries use this mode? Maybe they would use the Stock service in OpenLMIS 3.3 as part of Vaccines without using the Requisition service?)
- Both Requisition and Stock (experimental; would be used by Malawi Future)
Assumptions
- Implementers will want to utilize the requisition and stock management services at the same time
User Stories
| # | Title | User Story | Label | Importance | JIRA tickets |
|---|---|---|---|---|---|
| Phase 0 | |||||
| 1 | Make stock adjustments reason specific | Phase Zero: update data models to prepare for connecting Stock and Requisition |
| ||
| 2 | Change Physical Inventory to include reasons for discrepancy | Phase Zero: update data models to prepare for connecting Stock and Requisition |
| ||
| Phase 1 | |||||
| 3 | Add date field to Requisition form | Phase 1: Simple connection of requisition and stock |
| ||
| 4 | Change Requisition adjustment reasons to come from Stock Service (including data migration) | Phase 1: Simple connection of requisition and stock |
| ||
| 5 | Requisition service requires Stock service be active | Phase 1: Simple connection of requisition and stock |
| ||
| 6 | Deprecate all Adjustment Reasons endpoints in RefData | Phase 1: Simple connection of requisition and stock |
| ||
| 7 | Requisition form info gets pushed into Stock Physical Inventory | Phase 1: Simple connection of requisition and stock |
| ||
| 8 | Document the simple Requisition-Stock connection | Phase 1: Simple connection of requisition and stock |
| ||
| Phase 2 | |||||
| 9 | In Requisition Template, add radio button option to choose Simple or Advanced connection to Stock service | This is a new radio button with two choices: "Requisition only" and "Connect to Stock Management". Text under the Stock Management option needs to say it is not available offline. This is a new radio button If the OpenLMIS Stock service of at least version 1.0.0-beta is installed and available at its API (check version API endpoint), then we allow the radio button to be chosen; otherwise it is disabled. Changing this radio button setting saves/persists this setting as part of the Requisition Template for this program only. Use existing API endpoints for retrieving and saving requisition template. Permissions for changing this setting are the same as for changing any of the Requisition Template. When you try to initiate a requisition with this setting enabled, the setting should be part of the Requisition object that gets initiated and sent to API consumers (e.g., so that the UI can do something special in a later ticket if this setting is set to use Stock). If later on the Stock service becomes disabled, then when you try to initiate or edit a requisition from a template that uses the stock service, the Requisition service throws an error with a helpful message and the UI displays that. (EG, "Stock service is not found. OpenLMIS Stock Management service is required by this requisition's template.") | Phase 2: Advanced Requisition-Stock connection | ||
| 10 | Add Advanced Adjustments modal that comes from the Stock UI | on requisitions where 'Advanced Connect to Stock Management' is selected. We want the advanced modal to actually live in the Stock UI repo. It will mostly match the design and functionality of the existing Adjustments and Issue and Receive screens in the Stock Management UI. So Requisition UI now depends on Stock UI: add that dependency programmatically or at least in the documentation, and perhaps add error checking for if stock UI does not provide/define the modal it should give a friendly error (it could mean you are using a newer Requisition UI with an older Stock UI version that is not compatible). The default date of the first adjustment will be the ending date of the period. Similar to the Stock UI existing adjustments screen, after that the default date of the new adjustment rows added in the modal will be the previous date the user had picked for the previous adjustment. The date validation checker must limit users to only picking dates within the start date-end date range of the Requisition Period for Regular Requisitions. For Emergency requisitions there is no limit (though as before, we do not expect users to enter adjustments during Emergency requisitions). The Product is pre-selected depending on the Requisition form row, so that part of the stock UI we do not need, but we do need the Lot select field to appear for any product that has one or more active Lots defined. | Phase 2: Advanced Requisition-Stock connection | ||
| 11 | Refactor simple adjustments modal out of Requisition UI component and into Stock UI component | Maybe—TBD. This was originally discussed when there was only going to be an Advanced version, not a simple one; at that time we planned that the Advanced UI would be owned by the Stock Management UI component. | Phase 2: Advanced Requisition-Stock connection | ||
| Phase 3 | |||||
| 12 | Prompt user to initiate requisition | Upon finishing a Physical Inventory (in Stock), prompt user to initiate a Requisition | Phase 3: Requisition pulls data from Stock Service | ||
| 13 | Generated Requisition / Automatic Requisition / User-friendly enhancements | When a user initiates a Requisition at a facility and program that uses OpenLMIS Stock Management to conduct regular inventories and record adjustments/transfers, then the Requisition will get filled out with a lot of helpful time-saving data based on the latest stock data. Opening and Closing balance come from stock-on-hand values as of period start and end dates. Adjustments pulls all the adjustment transactions that are currently recorded during the period start-end date range. Received quantity totals up all receipts recorded during that date range. In short, the benefit is a nearly 'automatic' requisition form is filled out for you at the end of the period, as long as you are logging transactions in stock management during the period. TBD whether this would always happen or would be a setting you can turn on/off in the program's requisition template. | Phase 3: Requisition pulls data from Stock Service | ||
Diagrams
Transitioning Between Modes
Some transitions are likely, and will be important for OpenLMIS to support. Meanwhile, other transitions are unlikely or may be difficult to support.
Big arrows show the most likely transitions. Small arrows are less likely. Some transitions without arrows are not supported.
Dependencies
| Description | Link |
|---|---|
Open Questions
Below is a list of questions to be addressed as a result of this requirements document:
| # | Question | Outcome | Status |
|---|---|---|---|
| 1 | Which modes can be active inside one OpenLMIS system in parallel? I expect some programs may use one mode, while others use a different mode. Both can live in one OpenLMIS installation in parallel. What about per facility type (or per individual facility)? Is it possible that a Program may have one mode, but some facilities may participate in a different mode? | ||
| 2 | Question: Would a transition between these modes happen per-program or per-facility or facility type? (Either way, the transitions could be complex. Transitioning per-product would be even more difficult.) |
Notes
Phase Zero:
(new alternative #4 added July 7, 2017 from Josh, Mary Jo and Brandon)
(our discussion here was about how the Stock-Requisition connection really divides the Requisition Form into 3 parts: Blue is the Requisition Columns that are now owned by Stock service; Red is the columns such as Requested Quantity and Approved Quantity owned by Requisition; and Green is Program Data (future). These 3 parts are really separate entities "stapled together" when a requisition goes for approval. If the Requisition is Rejected, there are 3 ideas for what happens next with the different parts. Perhaps the blue part is read-only (because it was already submitted to stock service; and because we really don't expect the facility to conduct ANOTHER physical inventory for the same period dates as they already submitted last time). Or maybe there are cases where the blue needs to be revised or re-done. Corrections might be preferable to starting from scratch. There are usability questions about how an end-user would understand what happens if they had to totally re-do a new physical inventory blue part. We also may want to change the Rejection UI so when someone rejects a requisition, they can be clear about which parts they are rejecting (the blue? red? green?).
(additional notes from 16 June 2017 meeting with Josh, Brandon, Mary Jo)
(additional notes from 7 July 2017 meeting with Josh, Brandon, Mary Jo)
Out of Scope
Drop support for the simple version of Stock connection (to be determined if this will be done at a later date):
This would force all users/implementations to use the more advanced version of the UI the offers Lots, Comments, Sources/Destinations, Dates per adjustment/transfer. This would impact live country implementations, such as Malawi that has currently opted to keep the Simple version (because they are doing data entry from paper that has none of the granular details). We would probably need to provide a warning/error message when this version upgrade is applied that warns admins. The benefit is that it makes the product easier to support if we have fewer configuration options to maintain in perpetuity. Ultimately we want to encourage countries to move towards professionalization and more transactional, timely entry of this data.