Target release
Epic	OLMIS-2839 - Getting issue details... STATUS
Document status	IN DEV
Document owner	Sam Im (Deactivated)
Technical Lead	Brandon Bowersox-Johnson, Mary Jo Kochendorfer (Deactivated)

Table of Contents

Goals/Scope

The requisition and stock management services connect so that stock information gathered on the Requisition form is passed to the stock cards. This facilitates an implementer's ability to leverage data collected in requisitions when turning on the stock management features.

Background

OpenLMIS 3.1.0 introduced the Stock Management service, but it did not inter-connect with the Requisition service to share any data. Reasons for adjustments on the Stock Management screens used a totally separate Reason list in Stock Management that was redundant with the one used by Requisition service from Reference Data.

OpenLMIS 3.2.0 inter-connected the Stock Management and Requisition services. Both services now share the same adjustment reason list in Stock Management. The Requisition service now sends a number of data elements into the stock cards after any requisition is approved:

(B) Total Received Quantity: maps to a Physical Inventory reason called 'Receipts' (this mapping is configured in the .env file)
(C) Total Consumed Quantity: maps to a Physical Inventory reason called 'Consumed'
(D) Total Losses and Adjustments: each adjustment maps to a Physical Inventory reason from the reason list; these are 'aggregate' numbers, a total for the whole period, not 'transactional' numbers with a different date for each
(E) Stock On Hand: maps to the Physical Inventory quantity (this field maps regardless of whether it is configured to be displayed on the Requisition template; the other fields above do not map into the stock card for requisitions that do not have those fields displayed; this is configured in the Requisition & Report Template by Program)

Overall, the Stock Management screens provide a much more granular way to record adjustments and inventories compared to the Requisition form. Stock Management screens support Lots (different quantities by Lot); different dates for every line item or adjustment reason; recording a source/destination for issues and transfers, including free text explanations; and VVM status capture for Vaccines. The Requisition form, on the other hand, does not support Lots, only uses one date for all line items and reasons, does not capture sources/destinations, and does not capture VVM status.

The Requisition template can be configured to collect a "Date physical stock count completed" field (see the sub-section Setting up Requisition Date Physical Stock Count Completed). When enabled, this date will be collected during Requisition submission and authorization, and it will be used as the stock card date for stock data gathered on the Requisition form. When it is disabled, the last day of the requisition period will be used as the date on stock cards.

The upgrade from prior versions to 3.2.0 requires a data migration which is documented on the 3.2.0 Release Notes. In addition, Stock Management service is now a required component for any implementations using the Requisition service.

Future versions of OpenLMIS, after 3.2.0, may continue to improve the Stock-Requisition data connections. They may also support features to auto-populate monthly requisition forms using data from stock management. See the later phases documented in Phase 2 and Phase 3 of the grid below.

Assumptions

Implementers may want to begin using the Stock Management "stock card" view to view stock data by product. They may also want to begin using the Stock Management screens to capture transactional, real-time stock activities including adjustments, transfers, issues, and physical inventories.

User Stories

#	Title	User Story	Label	JIRA tickets
Phase 0
1	Make stock adjustments reason specific		Phase Zero: update data models to prepare for connecting Stock and Requisition	OLMIS-2669 - Getting issue details... STATUS
2	Change Physical Inventory to include reasons for discrepancy		Phase Zero: update data models to prepare for connecting Stock and Requisition	OLMIS-2711 - Getting issue details... STATUS
Phase 1
3	Add date field to Requisition form		Phase 1: Simple connection of requisition and stock	OLMIS-2833 - Getting issue details... STATUS OLMIS-3023 - Getting issue details... STATUS
4	Change Requisition adjustment reasons to come from Stock Service (including data migration)		Phase 1: Simple connection of requisition and stock	OLMIS-2694 - Getting issue details... STATUS OLMIS-2830 - Getting issue details... STATUS
5	Deprecate all Adjustment Reasons endpoints in RefData		Phase 1: Simple connection of requisition and stock	OLMIS-2831 - Getting issue details... STATUS
6	Requisition service requires Stock service be active		Phase 1: Simple connection of requisition and stock	OLMIS-2671 - Getting issue details... STATUS
7	Requisition form info gets pushed into Stock Physical Inventory		Phase 1: Simple connection of requisition and stock	OLMIS-2834 - Getting issue details... STATUS
8	Document the simple Requisition-Stock connection		Phase 1: Simple connection of requisition and stock	OLMIS-2832 - Getting issue details... STATUS
Phase 1 Clean-Up
9	Bugs found in 3.2.0	See details in each ticket.		OLMIS-3148 - Getting issue details... STATUS OLMIS-3213 - Getting issue details... STATUS OLMIS-3215 - Getting issue details... STATUS OLMIS-3404 - Getting issue details... STATUS
10	Design issue: four special reasons appear as choices in Total Losses and Adjustments	See details in ticket.		OLMIS-3246 - Getting issue details... STATUS
11	Design issue: requiring all products versus allowing skipping some	The relaxed validations may be working fine as is (see history in the ticket). (Not a priority for v3.3)		OLMIS-3099 - Getting issue details... STATUS
12	Design issue: stock cards are not aware of Requisition data until final approval	This impacts users because they cannot truly use the Stock UI for transactional data entry, since no data from a Requisition form will appear there until weeks later when final approval status is reached. (Not a priority for v3.3)		OLMIS-3226 - Getting issue details... STATUS
13	Change Stock Management service to be optional	Currently Stock is Required by Requisition (per tickets above). We may change this so that Stock is optional. If Stock service is not installed, then Requisition service would not have the columns that connect to stock (opening balance, received quantity, losses & adjustments, consumed quantity, closing balance). Alternatively, those columns could switch to "reporting-only" columns that do not send data to Stock Management but still allow data capture on the requisition form. (Not a priority for v3.3)		OLMIS-3789 - Getting issue details... STATUS
14	Future Improvement: support changes in FTAP lists over time (this scope is being tracked elsewhere)			OLMIS-3282 - Getting issue details... STATUS may be achieved by OLMIS-3067 - Getting issue details... STATUS
15	Remove deprecated endpoints	The old Adjustment Reason endpoints were deprecated in 3.2.0. They can be removed in a future release. Timeline TBD. (Not a priority for v3.3)		OLMIS-3100 - Getting issue details... STATUS
16	Open Question: configuration	There is an issue in GitHub review about whether the .ENV file is the best way to configure which requisition columns map to which adjustment reasons. Needs architect input. (Not a priority for v3.3)
Phase 2
17	Create historical stock card events for pre-existing requisitions before version 3.2.0/Phase 1	The 3.2.0/Phase 1 functionality means that stock card events will be created for each new requisition going forward. However, the feature and migration work done in Phase 1 did not address creating stock events from any historical requisitions in the system before-hand. TBD: Is this feature necessary? It may only ever impact one country implementation. Or it might also be an issue for future implementations if they migrate in historical batches of Requisitions into the system (they will need to also migrate in historical stock events or the product will need a script to create stock events from historical requisition data).	Phase 2: Advanced Requisition-Stock connection
18	In Requisition Template, add configuration option to choose Simple or Advanced adjustments	Advanced version of the connection brings up the more detailed 'Losses and Adjustments' modal. This is the modal that the Stock Management UI already uses on the Stock Management > Adjustments screen. It is more powerful because it handles each Lot separately, it allows for a separate date for every single adjustment, it allows sources and destinations to be selected with dropdowns, and it allows free text entry for reasons that use free text. TBD: If the Advanced option is pulling in Lots with their latest quantities, and pulling in Sources/Destinations, will this Advanced version be available offline? This configuration setting for the "Total Losses and Adjustments" field is a new radio button or checkbox with two choices: "Simple" and "Advanced" (or "Enabled Advanced"). Changing this radio button setting saves/persists this setting as part of the Requisition Template for this program only. Add another field into existing API endpoints for retrieving and saving this requisition template/program setting. 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 Advanced).	Phase 2: Advanced Requisition-Stock connection
19	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. This will make Requisition UI depend 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). Details: 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
Phase 3
20	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	(This may become part of Re-Supply / Simple Requisition / Creating an Order)
21	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	(This is now part of the "Vaccine Stock-Based Requisition" epic in Re-Supply domain.)

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

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

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)

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.

Notes on pre-3.2.0 behavior

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.

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.

Browser not supported