Background

A few recent improvements to Stock Management are interacting in a way that stops users from entering historical Physical Inventory data. Because Requisitions now save Physical Inventory data in the Stock Management service, this now blocks users from approving Requisitions in some cases. This is causing production issues in the Malawi implementation.

Two recent improvements to Stock Management in 3.2.0 have caused this issue:

• Adding Reasons to Physical Inventory. This feature requires each physical inventory must also specify reasons that account for the entire change in quantity from the system's last-known stock-on-hand to the current stock the user is recording.
    OLMIS-2711 - Getting issue details... STATUS
• Pushing Requisition Stock Data into Stock Management: This feature sends some Requisition form columns, such as Stock on Hand and Total Received Quantity, into the Stock Management service as a Physical Inventory with reasons. This currently happens when any Requisition receives its final Approval.
    OLMIS-2834 - Getting issue details... STATUS

The connection of these features are causing the following issues:

• Requisitions cannot be approved out-of-order
    OLMIS-3505 - Getting issue details... STATUS
• Physical Inventories cannot be past-dated if newer data exists
    OLMIS-3808 - Getting issue details... STATUS

This is causing a production issue for the Malawi implementation with Requisition approvals, so the community has been asked to quickly identify a solution.

The proposed solution below is for community discussion and input. This is a planned topic for the Product Committee meeting on 19 Dec 2017.

Two-part solution (proposed)

The two-part solution below will allow Requisitions to be approved out of order. It will also have other benefits that improve the design and the timeliness of data.

1A. Allow Physical Inventory without requiring reasons for the entire quantity change (API only)

Remove the current validations from the Stock Management API that requires any Physical Inventory to include reasons that account for the entire quantity change. Under this proposal, we will remove the validations from the API, but the UI will still require those validations. That means that other services using the Stock Management API directly will have the flexibility to submit a past-dated or out-of-order Physical Inventory – this includes the Requisitions from the Requisition service. The UI, however, will still require reason quantities to account for the entire quantity from the system's last-known stock-on-hand.

When viewing a Stock Card, if the adjustment quantities do not fully account for the difference, a row showing "Overstock" or "Understock" will appear (similar to how version 3.1.0 worked before physical inventories used reasons).

Pros:

• API: Helps allow Requisition approvals out of order.
• API: Allows offline clients or apps to sync data, even if Stock Management service has received newer adjustments or inventories.
• UI: Continues to enforce a complete set of reason quantities; forcing users to enter full set of reasons could lead to better data. UI will continue to work best for entering "live" transactional data in chronological order.

Cons:

• UI: Stock Management UI will not support entering a past Physical Inventory.
• The API having different flexibility than the UI could be confusing to implementers/stakeholders (end-users would not know).

Alternative 1B: Allow Physical Inventory without requiring reasons for the entire quantity change (both API and UI)

Remove the validations from the API, plus also remove the from the Physical Inventory screen of the UI. In either the API or Stock Management UI, it would now be possible to submit data for a past Physical Inventory.

Pros: 

• API – same Pros as regular #1 above
• UI: Allow more flexibility to enter a past Physical Inventory in the Stock Management UI.
• More consistency between API and UI; easier for QA and documentation and understanding of implementers.

Cons:

• UI: Less enforcement for data quality. Users would be able to enter partial quantities for reasons but leave some of the quantities "unaccounted for".

Alternative 1C: same as 1A, but make a separate API endpoint for submitting these Physical Inventories

(Suggestion from the comments below. Pros: same as 1A; Cons: Potential for duplicate code/added complexity)

2A. Requisitions Send Data to Stock Management at Authorized Step

Change the Requisition-Stock connection to send this data at the Authorized Step, which is sooner than the Approval Step currently used. This essentially means the Stock columns on the Requisition form get sent to the Stock Card when the form "leaves the facility" (after being Submitting and Authorized) and before the multi-step Approval workflow happens. Currently, data is synced at the final Approval, which can happen weeks or months later. That can mean a long delay before old data reaches the Stock Cards currently.

Once the stock data is sent, it can no longer be edited. So this would also change how Rejected Requisitions work. Rejected Requisitions would still go back to the start of the workflow, BUT the Requisition columns which were already synced to Stock Management would be read-only, not editable. Current behavior allows Rejected Requisitions to edit any columns. The columns impacted are: Beginning Balance, Received Quantity, Consumed Quantity, Losses and Adjustments, and Current Balance. Other columns would still be editable, such as Requested Quantity and Explanation. If they needed to change the stock columns, they could Delete the Requisition and re-initiate a new one; that would start a fresh "physical inventory" where the fields would be editable, although extra data entry would be required. (See alternatives below for other ways to address Rejected requisitions.)

Pros: 

• More timely data will appear on Stock Cards.
• Data will go to Stock Management service in chronological order.
  Note: The Requisition service already forces Regular Requisitions to be Authorized in order by Period. EG, you cannot initiate May until April has been Authorized–this is already enforced by the Requisition service and UI. So by sending the data at Authorized step, we benefit from this existing rule to help keep the Stock data more timely and chronological.

Cons:

• Rejected Requisitions would have certain stock columns be read-only (5 columns listed above). This would reduce the flexibility of the facility to revise their requisition. EG, if it was Rejected because the approvers did not like the reported stock information; note that usually approvers reject a requisition because of the requested amounts, which would still be editable. If they really needed to change the read-only stock columns, they could Delete and Initiate a new Requisition.

Alternative 2B: Rejected Requisitions still allow editing the stock columns, and when they are re-Authorized they submit a new Physical Inventory

Under this alternative, Requisitions would still send data to Stock Management at the Authorized Step (same as 2A), but Rejected Requisitions would also allow editing the 5 stock columns. The fields would not become read-only. When the Requisition moves to Authorized status again, the Requisition service would submit it again as an entirely new, second Physical Inventory.

Pros: 

• Compared to option #2, this allows more flexibility for editing all columns.
• Compared to option #2, this prevents the need for users to Delete and Re-Initiate a requisition, causing extra data entry.

Cons:

• Stock Card data would show double entries dated the same date (end of the Requisition period). Adjustments, for example, would appear twice. The final closing balance will be correct, but the duplicated data may be confusing to users. The stock card would reflect the fact that two different physical inventories were reported for the period. (Future feature improvements could make the Stock Card view more clear to identify which requisition the data came from.)

Alternative 2C: Rejected Requisitions Go to Authorized Status

Under this alternative, Requisitions would still send data to Stock Management at the Authorized Step (same as 2A), but we would change the workflow for Rejected Requisitions. Rejected Requisitions would go directly back to Authorized Status, not allowing edits by the facility, but still allowing changes to the Approved Quantity and Explanation. (This would be a significant change that might not be acceptable for existing country users, such as in Tanzania and Zambia.)

Long-Term Approach: Add Support for Reversals to Allow Corrections to Stock Data

In the longer term, we hope to add a significant new feature to Stock Management: support for Reversals of data. This is a strategy selected during design of the Stock service, but never implemented because of the time and effort required. This would allow the Requisition service to "reverse" the data submitted if a Requisition was Rejected. After that, it would be possible to re-submit new, corrected data. This feature, while it may be appealing, would take significant time and effort and would reduce the time remaining for other vaccines features. By using the Reversal mechanism, Rejected Requisitions could still allow editing of all the Stock columns.

Having Reversals in place could be used in combination with 2A/B/C to allow users to edit all the fields after a Rejection, and use the Reversal mechanism to reverse and re-submit Stock Card entries with improved data quality.

Pros: 

• Compared to option #2, this allows more flexibility for editing all columns, even on Rejected Requisitions.
• Reversals may have future benefits to the users of Stock Management (to allow other sorts of corrections).

Cons:

• Significant effort required. This will prolong the timeline to fix the overall issue, and it will take away resources from other vaccines features.

Questions

• Would validations in the service API be different from the UI?
  Answer: Yes, under proposal #1 above. But Alternate #1 would make API and UI match.
• How does removing the reason validations change Requisitions?
  Answer: No impact on Requisitions (other than now users can approve requisitions out-of-order). The Requisition form itself still has its own internal column validations which will still remain in place. Those validations require that the Requisition Form must balance out in its reporting of stock levels during that reporting period (Beginning Balance + Received Quantity - Consumed Quantity +/- Losses and Adjustments = Current Balance).
• Would we still have validations about going below zero?
  Answer: Yes. Stock Management still has other validations that no sequence of stock events can ever make a stock-on-hand quantity go negative. That will remain in place.
• Would #1 alone solve things for now without #2?
  Answer: Yes, I believe it would. However, we suggest doing #1 and #2 together now to get better data flowing sooner into Stock Management and get to the better technical design we have always intended.
• What about Emergency Requisitions?
  Answer: They would follow the same new rules proposed in #1 and #2. When they are Authorized, they also send Physical Inventory data to Stock Management service. And when they are Rejected, they would also work just like Regular requisitions in the options for #2. As a separate matter, other aspects of Emergency Requisitions are currently being evaluated in OLMIS-3587.