Physical Inventory validation prevents entering past-dated Physical Inventories

Because Physical Inventories now require reasons to account for the entire quantity, this Physical Inventory validation makes it impossible to enter past Physical Inventories if there are any new inventories or adjustments for a given product in stock management.

This prevents receiving data out-of-order, which happens with some Requisition approvals. This validation is also a concern for offline use and asynchronous data (if different clients/apps sync data after the fact).

Scenario
Here are 3 months of Physical Inventory stock on hand data:

• 31 January: 100 SOH (reason is +100 Facility Return)

• 28 February: 15 SOH (reason is -85 Expired)

• 31 March: 80 SOH (reason is +65 Facility Return)

Steps to Reproduce

1. Log in as 'srmanager1'
   (actually easiest to use 'vsrmanager1' on demo-v3.openlmis.org after using administrator account to change vsrmanager1 home facility to an unused facility in Cuamba; it is easiest to use demo-v3.openlmis.org since ALL Physical Inventory submissions are broken in the latest build currently by OLMIS-3769)

2. Navigate to Stock Management > Physical Inventory

3. Click Start (for Essential Meds with srmanager1 / EPI with vsrmanager1)

4. Add a new product that is not already on the Physical Inventory (does not already have any stock card). Use any new product and lot and click Add.

5. Enter January Current Stock (SOH 100 and use reason from scenario above).

6. Click Submit, which opens the Modal.

7. In 'Choose Occurred Date' modal, select 31-Jan-2017.

8. Click confirm. Success! January Physical Inventory is recorded.

9. Next we will enter March Physical Inventory....(basically we will repeat steps 2-8 for March)

   1. Navigate to Stock Management > Physical Inventory

   2. Click Start

   3. Your product should already appear (now that it has a stock card)

   4. Enter March Current Stock (SOH 80 and use reason from scenario above, namely +65 Facility Return).

   5. Fixed by OLMIS-3921, so no longer an error here. ERROR: The row has an error. The validation requires you to account for the full quantity changed from the last-known 'Stock on Hand' (100) to the 'Current Stock' (80). In other words, because you did not log February Physical Inventory, now you are forced to make up fake data to enter your March inventory. (You must enter some -85 adjustment, eg Expired.) There is something wrong with our design if the system is forcing you to make up bad data to record a real-world scenario.

   6. Click Submit, which opens the Modal.

   7. In 'Choose Occurred Date' modal, select 31-Mar-2017. March is now recorded.

10. Next we will enter February Physical Inventory....(basically we will repeat steps 2-8 one last time)

    1. Navigate to Stock Management > Physical Inventory

    2. Click Start

    3. Your product should already appear (now that it has a stock card)

    4. Notice that the Stock on Hand column says 80. But we are entering February Physical Inventory (a future improvement would be a way to show 100 from end of January). But the system provides no way to say I am entering for a past date and show the balance as of that date. A future possible feature could allow users to pick a date at the start of entering stock records so the system shows Stock On Hand as of that past date.

    5. Enter February Current Stock (SOH 15 and use reason from scenario above, namely -85 Expired).

    6. Fixed by OLMIS-3921, so no longer an error here. ERROR: The row has an error. The validation requires you to account for the quantity changed from the March 'Stock on Hand' (80) to the 'Current Stock' (15). (So you must also enter some made-up +20 adjustment, eg Facility return to be able to submit.)

    7. ERROR: "Physical inventory failed to submit". Screenshot attached. In Inspector you will see the Stock Service validation error:

A few points about this final error:

• Because of the strict reason-quantity validations, it is impossible to add historical physical inventory data.

  • That is definitely bad for offline users or asynchronous data. The whole system breaks down unless data is always received in order.

  • This is also bad for doing data entry from paper records. If you are trying to digitize a past physical inventory, this validation will stop you.

  • This is also the root cause of OLMIS-3505, where stock data is coming in from Requisition forms out-of-order.

• You made up extra reason quantities to pass the UI validation, but still the back-end validation does not allow it.

  • In our scenario, the stock never went negative. So why is the validation about going negative giving an error?

  • Also, the error message does not help you know what is wrong. Even if you use dev tools, the error message "15 subtract 20" is confusing because you never had any adjustment that was -20. You had a +20. The 15 represents the current stock on hand, that you are trying to insert (for February). The 20 is the auto-calculated adjustment between your SoH from January and March (100 -> 80 ie. -20)

  • Issue is caused by error in QuantityValidator. Stock on Hand is calculated there two times (once to get previous SOH, second time for validate all stock card line items). First call to StockCardLineItem.calculateStockOnHand set reason field and change quantity field (in our case to 100 - 80 = 20) that in second SOH calculations is subtracted from February SOH that's why we see "15 subtract 20".

  • Calling StockCardLineItem.calculateStockOnHand two times on the same object just can't work. That's why "shallow copy" of stock card is always done before calculation. The problem is that quantity field have different meaning for physical inventory (it means SOH) and for other events (it means adjustments). Also because reason field is assigned to stock card line item during calculations, second calculation think that line item is "other event", not PI, which has different calculations (treat quantity field as adjustment).

Proposed solution:

• We can delete the first calculations since I think we don't really need previous SOH value in validator (currently it's used only to prevent from validating wrong stock adjustments quantities if SOH is null but I think it will be enough to just check if stock card has any line items instead of checking if SOH is not null).

Background
When Stock Management was first created for OpenLMIS 3.1.0, it was designed so you could select a date in order to enter stock data from the past. The design of occurredDate in stock was to allow users to enter data with a past date. That originally worked for Physical Inventories, which did not have Reasons in 3.1.0. So users could enter the scenario at the top (3 months of SOH values, even if you put in January, then March, then February). But when we added Reasons and required all the adjustments to add up, this has prevented the ability to enter past/historical physical inventory data. This also causes problems for Offline usage (including possible mobile apps) and for asynchronous receipt of data (if one newer record syncs to server before an older record).

Acceptance Criteria/Desired Behavior

• Allow users to submit these 3 physical inventories out or order without giving the error. This was the desired behavior that was also the goal in after Product Committee input.