Skip to end of metadata
Go to start of metadata

What is a Lot in v3

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


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.

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.

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

  • No labels


  1. Brandon Bowersox-Johnson  Mary Jo Kochendorfer  Josh Zamor  Chongsun Ahn Shiyu JIN

    I am going to make up 2 new words, to make the following sentences shorter.
    lotless stock card: a stock card created without any lot information.
    lotful stock card: a stock card created with lot information.

    For open question 2, solution A:

    A lotless stock card was created when there are no lots configured yet.
    Then admin adds lots.

    Now, do we allow users to make any more movements on the existing lotless stock card?
    Or does the user have to create new lotful stock cards to track all future movements?

    There is an existing lotless stock card, its soh is 10.
    Then admin adds lots.
    A user is trying to create a lotful stock card.

    Now, do we allow the very first movement made to the lotful stock card to be subtractive?
    If we don't, then user would have to make an additive movement first, which could very well be duplicating what is already there in the lotless stock card.
    If we do, then user would get a negative number when querying soh for the lotful stock card alone.

    In short, a lotless stock card's soh belongs to unknown lot(s), that makes it hard to balance soh when lot is introduced.

    For open question 2, solution B:

    If we transfer a lotless stock card's balance to a "dummy lot", I think we still have the same problem.
    Since the system does not know which real lots the "dummy lot" consists of, it'll be hard to determine if stock is balanced when lot is introduced.
    (It's like I know I lent $10000 in total to many different people. But I don't remember who owes me how much. It'll be hard for me to balance my book.)

  2. Pengfei so perhaps for question 2, solution B, we might not have a dummy lot, but stock balances would need to be transferred to the new lotful stock cards. If there is any balance that does not fit in any of the lotful stock cards, there would be a lotful stock card based on an unspecified lot.

    1. I think that'll help to decrease chances of balance problem.

      But as long as there is a stock card associated with an unspecified lot, the system won't know for sure if stock is balanced.

      I think a way to make sure the system is sound is to do this:

      1 When lots are enabled(added) for a trade item that has existing lotless stock card, the system would force users to transfer existing lotless soh into lotful stock cards to a point where the lotless stock card's soh becomes zero.

      2 Before zero is reached, no further actions are allowed to be taken on any of the stock cards.

      3 After zero is reached, the lotless stock card would become inactive/disabled.

      I think this will make sure the system always knows if stock is balanced. But it does also incur more user effort, and makes the system feel a bit rigid.

      Chongsun AhnMary Jo KochendorferJosh ZamorBrandon Bowersox-Johnson

      I think this will be a trade off between soundness/integrity and user friendliness.

  3. Pengfei Chongsun Ahn I'll propose an answer to each of Pengfei's questions:

    For Open Question 2, Solution A, Question 1:

    In Proposed Solution 2A, my suggestion is to be "permissive" about Lotful and Lotless stock cards being used simultaneously for a given trade item. We might still have some stock on the books that is Lotless, meanwhile other stock might begin arriving that is Lotful, even at that same facility. Both kinds of stock cards could have SOH at the same time and could still have activity. So when you ask "Now, do we allow users to make any more movements on the existing lotless stock card?", my proposed answer is Yes. And when you ask, "Or does the user have to create new lotful stock cards to track all future movements?", my answer is No. Users could make movements and do inventory at both at once. I would expect that written SOP policies would encourage them to phase out the Lotless stock and begin using separate bins to track each lot on Lotful stock cards going forward, but the software would be "permissive" as they make this transition.

    For Open Question 2, Solution A, Question 2:

    When you ask "Now, do we allow the very first movement made to the lotful stock card to be subtractive?", my proposed answer is that we allow any first movement that would normally be a valid movement. If we have a rule that they cannot go below zero on any stock card SOH, then we would not allow them to Issue 10 items out of the Lotful stock card if it has zero (0) SOH. If they really have 10 new items in that Lot, they would make an adjustment to record that they got this stock. If those 10 items were the same 10 that used to be counted on the Lotless stock card, they would make an adjustment to subtract 10 from the Lotless card SOH.

    You asked if that would cause a problem with "duplicating what is already there in the lotless stock card." My answer is that it would not, because they would subtract the quantity from the Lotless stock card. In fact, my question number 5 was about this very situation—about whether we should create a specifically named Adjustment Reason for when you properly record stock in a Lot. The reason could be called "Correcting Lot Assignments".

    By doing this, I believe it will not make SOH hard to balance.

    For Open Question 2, Solution B, Your Question:

    For the "dummy lot" idea, I believe Chongsun has replied. I believe, whether we call it a "dummy lot" or "unspecified lot", that's fine. I'm also fine with the idea Chongsun suggested that we force them to transfer all stock to a Lotful stock card.

    Overall, I still have a personal bias towards 2A as a better solution. Why? We write less code and create software that will be flexible enough for real world situations. I am afraid about 2B that we will create software that is "brittle" and real-world users will not have a way to handle situations that come up in usage while they are transitioning from a Lotless country implementation to a Lotful country implementation. With option 2B we would spend much more time writing rules, and that would actually decrease the value of the software because users would be stuck unable to accurately track their reality.

    1. I see, I am interpreting this as:

      It is more of a process/policy thing than it is a software thing.

      Users are expected to operate in a certain standardized way to make sure the system's data is sound and reflect reality, the system would not force rigid rules upon users.

      Would that be a correct summary?

    2. Brandon Bowersox-Johnson, I agree whole-hardheartedly with your assessment - don't try to overly enforce in expensive to change code what SOP of an implementation should guide.

      In my mind there are too many situations that could arise where lots are and are not tracked.  At this point in development and requirements gathering, we're too early to truly make informed decisions that deliver value.

      I'd propose that we deal with some of these questions in terms of gathering business processes.  i.e. any code written to enforce any of these rules is subject to vary depending on the business process in place.  Pengfei I feel that this complexity and unknown-ness of what the rules are, are handled through something like the Processing Rule introduced by Fowler on Page 2 of the Accounting Patterns document.  In previous discussions we've talked about the Stock Management service's Validators, how they should be like Fowler's Processing Rule, and the need for these to be natural points of extension.  Do you think these Validators are on the right track for achieving this need?

      1. Right now the validators are:

        1. Independent from each other. Each of them can operate with or without existence of the others
        2. Non-ordered. There is no specific order that the validators must execute in.

        If an implementer has their own rules, they can write their own validator that implements the StockEventValidator interface and somehow put it into Spring's context. It'll be picked up and ran each time before a stock event is persisted.