Lot Management for Stock Management Service

What is a Lot in version 3?

A Lot object has the following:

• String lotCode (required—if the shipment really does not have a code, and only has an expiration date, then users could paste that date into this code field)
• Date expirationDate (optional)
  
• Date manufactureDate (optional)
• reference to a TradeItem (required) — this object gives us access to the Manufacturer name, etc, which will be helpful for display. (in V2 this was a reference to a product)
  
• boolean active flag — potentially a future feature to be able to set a Lot as inactive after it has gone out of circulation; or maybe this is connected to how you archive the lot instead of a DELETE endpoint
• UUID will get assigned to the Lot in ReferenceData, but it won't be visible to the user

This definition of Lot is similar to v2, with some modifications. See https://github.com/OpenLMIS/open-lmis/blob/master/modules/stock-management/src/main/java/org/openlmis/stockmanagement/domain/Lot.java for V2 domain object.

New Endpoints in ReferenceData

• GET /api/lots?... - search and return all matching Lots; optionally query by any TradeItemID, expirationDate, and/or lotCode*
• GET /api/lots/{id} - get a single Lot by its UUID, not searching by TradeItem
• POST /api/lots - create a new Lot with a TradeItemID, lotCode, and optional fields (listed above)
• PUT / api/lots/{id} - update or replace a Lot by UUID

*If the TradeItem has no Lots (meaning Stock Service should create stock cards by the trade item, not by Lots), there will be zero lots coming back from this endpoint. The endpoint GET /api/lots?tradeItemID=1234&active=true would return a 200 with empty response object {}. We don't return a 404 NOT FOUND for these situations.

Permissions

For now, the ability to GET lots is based on the same permissions as ability to get the trade items, namely ORDERABLES_MANAGE permission. And the ability to POST and PUT lots is based on ORDERABLES_MANAGE permission. This is a global, sysadmin permission—it applies to all programs and facilities with no granular rights at this time.

The Stock Management service will use a service-level token that will allow that service to hit any of the Lot endpoints.

For now, we expect the Stock Management UI will not need to hit the Lot endpoints directly. We expect the UI would query the Stock service, and the Stock service would provide the data including LotCode and ExpirationDate which it gets from the ReferenceData service. This is the pattern already used for the Requisition UI to query the Requisition Service to get Orderables data. The Orderables and Lots endpoints require administrative permissions that most end-users filling out a requisition or a stock inventory would not have.

Impact to Existing Endpoints

None. This work involves adding new endpoints into ReferenceData (referencedata-3.1.0), but does not change or break any existing endpoints. In particular, TradeItems endpoints already in ReferenceData would not return and Lot information inside them.

Process to Manage Lots

1. Lot Management UI screens (view, create, update) - within the Products admin area, in the TradeItem record, some section or modal to see the current Lots and to update any one of them, or add a new Lot
2. CSV uploads (desired)

Roles and Responsibilities

• Reference Data API Endpoints
  
  • Teams TOP/AYIC to implement Lot Management endpoints in Reference Data 3.1.0
• Lot Management UI screens (in ReferenceData UI)
  • Team ILL to design Lot Management UI screens
  • Teams TOP/AYIC to implement UI screens (maybe, pending budget/time priorities)
• Stock Management Service and UI
  
  • Team Panda is designing and implementing UI and stock endpoints (based on stock workshop scope for ref-distro 3.1 release)

Future Functionality (not in 3.1 scope)

• Audit Log: ability to see the history of when a Lot was created, edited (when and by whom), de-activated. The would show us the life-cycle of each Lot. To our knowledge, this feature is not captured in the current Roadmap; it's just an idea.
• CSV uploads (we have other tickets in Roadmap for CSV uploads, but uploading Lots are not yet their own ticket)
• Potentially look into allowing allowing end users to add in lots/tradeItems. 3.1 aims to achieve lot management centrally.

Process to Configure Lot Feature

Why we need lot feature?

Being able to track lots provides us with two new pieces of data: lot number and expiry date. Other fields may be added, but for now we are focusing on these two. The lot number data allows decision makers to track orderables/products at the lot level and also allows warehouse managers to recall orderables if there is an issue for a specific lot. The Expiry date data will not only provide the storeroom managers with the information on when orderables have or will expire (reduce wastage) but also allows the decision makers to implement the FEFO process.

How do we balance the usability and technical implementation of turning on and off lots?

Open Question : Would an implementor want to restrict all stock information to ONLY be tracked within lots? This means a TradeItem by itself couldn't have a SOH amount, but rather it would summarize all the stock amounts across the associated lots. This means all storerooms must associate all stock to a lot.

Open Question : Would an implementor want to track stock both within and without lots? This means a TradeItem could have a SOH amount plus the stock amounts across lots. This means storerooms could make movements against a tradeItem without an associated lot.  

Usability requires our system provide the flexibility for end users to track products at tradeitem level or the lot level or both. Meaning, a tradeitem can has its own stock card while lots under this tradeitem can have its stock card as well. It is up for end users to create stock events on which stock card. 

Since we do not have a real user yet, it is very hard to make that decision. Instead, we come up with three options which can be discussed broadly with more stakeholders. 

Let us consider below user case of turning on lots after stock management tracking has been in place without lots:

When a country implement the OpenLMIS version 3.x, MOH decides not to use lot feature so all products are tracked by trade item or commodity type. Below is an example of the SOH summary in one facility.

Facility HC - HIV program

Let us take Drug A as an example. There are at least two lots belong to Drug A existing in Facility HC, their lot number are lot2 and lot3 and their SOH are 20 and 60 respectively. There is also 20 that were donated and do not have a blessed lot number. However, the storeroom can not record 20 and 60 separately because the system does not have lot information yet. In order to track Drug A, the storeroom manager creates a stock card for Drug itself and the SOH is the summary of lot2, lot3 and the donation. 

Later, the MOH decides to track stock at the lot level and system admin adds three lots (lot1, lot2, lot3) for Drug A. After sync with the server, store room manager in facility HC is able to choose three lots under Drug A for HIV program for creating stock events. 

If so,  how will the system deal with the stock card of Drug A?

Open Question : Is it reasonable to assume that when the MOH decides to track lots that they load up lots that have already been distributed? Do we have any information on how an implementer would want to start rolling out lot management? If using lots, would we want to enforce that all items with lots MUST fall within the approved lots?

Product Committee please review the following three solutions and let us know which you have questions on, which you prefer and why.

Solution 1: Mandatory SOH balance check & deactivate original stock card

Before creating stock cards for lot2 and lot3, store room manager must balance the Drug A’s SOH correctly to lot2 and lot3 SOH summary. In this case, the system will provide a UI for storeroom manager to input the initial SOH of lot2 (20) and lot3 (60) and that initial SOH summary must equal with Drug A current SOH (80). This validation is mandatory and storeroom manager is not allowed to create new stock events until he records all the lot information and pass the validation check. After he passes the validation check, then the system will deactivate the stock card of Drug A and storeroom manager will not record stock event for Drug A’s stock card. This would not allow an allocation of the 20 that was donated since it would not have an approved lot amount. The user would need to make an adjustment to remove the 20 from the SOH.

Open Question : Would it be acceptable to only track the movements of products within the approved lots and not support items coming in from unapproved ways or purchases?

The SOH summary page will change to:

Facility HC - HIV program

Solution 2: Freely record lot & hide original stock card

There is no balance validation check between Drug A SOH and its lot SOH summary but when a lot stock card is created under an existing Drug then the existing stock card of that Drug become invisible for end user. In this case, storeroom manager can choose lot2 or lot3 to create stock event and the initial SOH quantity can be any positive integer and there is no validation check whether the SOH summary of lot2 and lot3 matches Drug A SOH (100). However, after the stock card of lot2 or lot3 is created then Drug A’ s stock card become invisible for storeroom manager and its SOH remains 100 until a decision is made on how to deal with those stock amounts. A user would not need to make an adjustment to remove the 20 since it would be ignored

Open Question : Would it be acceptable to only track the movements of products within the approved lots and not support items coming in from unapproved ways or purchases?

The SOH summary page will change to:

Facility HC - HIV program

The original 100 for Drug A is now invisible.

Solution 3: Keep both lot and original stock cards

There is no mandatory balance validation check between Drug A SOH and its lot SOH summary. Storeroom manager can create stock event on either Drug’s original stock card or the lot’s stock card but the original stock card is independent from lots’ stock card. In the case, there will be three stock cards for Drug A in the system: Drug A' No Lot defined' stock card, Lot2 stock card, Lot3 stock card. Essentially we do not assume the stock on hand belongs to Lot2 and Lot3. IF it does, then the end user must make adjustments to the DrugA No Lot defined SOH reduces to the appropriate level.

Open Question : this puts a lot of responsibility on the storeroom managers. They would be responsible for 'balancing' out the stock. Would it be okay if stock is tracked without lots and lots? Would we want to have a workflow to help them balance or should they do it on their own through adjustments?

The SOH summary changes to:

Facility HC - HIV program

Which solution do you think is best and why?

Archived NOTES

Technical Option1: technical preferred - mixed policy and usability

The lot feature is always on but the system allows end users to choose either tradeitem or lot to create stock event. In other words, we provide the lot function to user but we leave the validation to end users as well. 

The UI layout will always support lot feature. To be more exact, even if a country does not use lot to track stock events, they will still see the lot number, expiry date column when they performance a physical inventory. 

Technical Option 2: TW preferred - usability focused 

System Administrator can turn on/off lot feature at central level. That configuration applies globally, which means if the feature is on then all facilities lot feature is on. 

The lot feature turn on/off configuration only determines the UI page layout. 

If the lot feature is on then the UI layout will use the lot supported design e.g. lot number column, expiry date column and expand table on adjustment page, physical inventory page and SOH summary page. 

If the lot feature is off then the UI layout will use the design does not support lot e.g. no lot number, expiry date column nor the expand table structure. Moreover, System administrator cannot add new lot or storeroom manager view lot from client side. 

As for the validation, we will leave it to the end users to confirm. Meaning, we will not check the balance between the trade item stock card’s SOH and the SOH summary of all lots belong to that trade item.

Technical Option 3: Donor preferred (maybe) - policy focused

The default setting of lot feature is off but System Administrator can turn it on. However, if the lot feature is on, system administrator can not turn if off. 

When the lot feature is on then system administrator must input all lots and ensure the trade item SOH quantity are correctly break down to lot level. For example, there is a trade item A and its SOH is 100 when lot feature is off. Later when system administrator turn on the lot feature then he inputs lot1, lot2, lot3 under trade item A. End user cannot make new stock events unless they break the quantity of trade item A into these three lots correctly. Meaning, the SOH summary of lot1, lot2, lot3 must equal to 100 (the SOH of tradeitem A). After the trade item A is break down to lot level then the stock card of trade item A will be deactivated and end users are only allowed to create new stock events of lot1,lot2,lot3 stock cards. 

Technical Option 4: Like Option 1 with easier UI (suggested by Brandon)

This part is same as Option 1: "The lot feature is always on but the system allows end users to choose either tradeitem or lot to create stock event. In other words, we provide the lot function to user but we leave the validation to end users as well."

The UI layout will be smarter/easier. If the UI is displaying a table that does have Lot rows inside the table, then these columns will be visible: Lot Number, Expiration Date. But if the UI is displaying a table without any Lot rows, then these columns are hidden: Lot Number, Expiration Date. This should be possible with a simple IF statement in the UI code.

For example, there is a trade item A and its SOH is 100, he inputs lot1, lot2, lot3 under trade item A. Lot1 SOH is 50, Lot2 SOH is 20, Lot3 SOH is 10. For tradeitem A SOH is 80 instead of 180. 

Open Questions

1. Josh, are there any other GS1 fields or naming changes needed?

2. If a TradeItem has no Lots, then has StockCards with inventory and adjustments with no Lots, then later on the TradeItem has lots, how does that impact the Stock service?

   1. Proposed solution A: For any TradeItem, allow the simultaneous existence of stock cards that have Lots along with stock cards that do not have Lots. We simply need our software to be flexible since Lots might get introduced into the supply chain at different times or in different locations, even after some stock cards and physical inventories exist in the software.

   2. Proposed solution B: For any TradeItem, it has a configuration to specify whether it is managed using Lots or not. To change a TradeItem to begin using Lots, that configuration change would modify the Orderables and Stock Cards in order to begin tracking stock in Lots. The pre-existing stock balances might be transferred to a "dummy lot".

3. If a TradeItem has Lots and Stock service has inventories and adjustments associated with it, and then the TradeItem stops using Lots (or stops tracking Lots) and the system needs to transition to tracking the TradeItem without Lots data, how do users do that in Stock Management 3.1?

   1. Proposed solution A: (same as A above).

   2. Proposed Solution B: (similar to B above—an administrator would change the configuration and that would move all of the current quantities from Lots back into a stock card for the overall TradeItem with no Lot information).

4. Inactive Flag on Lots: For future functionality (likely not for 3.1 release), we may need to discuss the Inactive flag and any business or process rules around who sets that flag, when, and why. EG, in a scenario where a TradeItem has Lots and Stock service has inventories and adjustments associated with it, and then the Administrator marks all those Lots as inactive (because they have expired or because they are out of circulation), if the Administrator does not enter any new Lots information for the new lots in circulation, and users of Stock Management are conducting inventories and adjustments with those new Lots that are not yet in the system, how does the system handle that?

   1. Proposed Solution A: Do not have an inactive flag in Stock for 3.1 release.

   2. Proposed Solution B: Do not allow administrators to mark Lots as inactive if there is any stock SOH quantity at any facility for a given Lot.

5. Does Stock Management need an "adjustment" reason to move stock from one lot to another, in cases where it was inaccurately reported? Or in cases where it was previously inventoried with no Lot information but now we want to start tracking it by Lots?

   1. Proposed solution: For now we assume users might need to do this manually (pick some existing adjustment reason to reduce Lot A by 100 and increase Lot B by 100; or reduce count without a Lot by 100 and increase count in Lot C by 100). System administrators might choose to add a Reason to their system that is more descriptive for this case.

User Stories

(This wiki page was originally created in response to ticket OLMIS-2108 - Getting issue details... STATUS ).