Objective

The integration aims to streamline and automate the communication of dispensing information between CMIS (Dispensing System) and eLMIS (Inventory Management System). This will ensure accurate stock adjustments in eLMIS, reducing the stock on hand based on actual dispensed quantities.

Excerpt from:

Core solution idea

To accommodate 3rd party integration, we shall modify the Stockmanagment API for Stock Event creation to allow reference facility, orderable, program, lot, and reason through business keys (ex.: unique names, codes, etc). Additionally, the error responses shall be improved to clearly state the reason for failure, ex.: in case of an event that consumes stock, the error object shall contain information about the current stock to clearly state why the requested amount can not be documented as consumed.

Considerations

1. The modification shall not break the current API - not a breaking change.

2. The modification can be made to replace the current API in the future or be just an alternative.

Issues

1. Lot’s business key is a combination of Lot code and Trade Item (having unique gtin).

   1. We can deduce the correct Lot based on Orderable. Lot is assigned to TradeItem which is assigned to all versions of the Orderable - Lot appears to ignore Orderbale versioning. The StockCard ignores Orderable versioning.

2. The orderable referenced by code would always point to the latest version of the orderable.

   1. Which is fine in the context of stock management.

3. The Stock Event Line item references the source and destination via Node which may be a Facility or Organization - a Node has no business key.

   1. This can be solved by priority lookup - assume it’s Facility Code if not found assume it’s an Organization name, else error that clearly says that Facility or Organization was not found.

   2. Should be fine, since having the Facility with a code that is the same as the name of some organization is a bad configuration/doesn't make sense.

Technical details

1. Introduce the idea of /api/integration REST API namespace for OpenLMIS. All REST API inside this namespace are made with 3rd party integrations in mind. They are not supposed to be used by OLMIS services. Another name might be /api/public.

2. Create a new API endpoint - /api/integration/stockEvents - which is an alternative for /api/stockEvents/ that resolves references by business keys (with some smart-guessing logic). There is a performance cost, but rather small. Preferably it should work on top of existing Stock Event logic.

3. Improve error handling for StockEvent validation. The LocalizedMessage shall be extended with context data that can be automatically and reliably interpreted. The new details object shall be added which would contain error-specific details, ex:

   {
     "messageKey": "stockmanagement.adjustment.quantity.invalid",
     "message": "Stock Adjustment quantity must not be negative.",
     "details": {
       "requestedQuantity": 15,
       "availableQuantity": 10,
       "product": "SKU12345",
       "lot": "ABC20250112"
     }
   }

Open questions

1. Do we need to provide an API for reading the current Stock on Hand or does the regular API return enough data for CMIS?