Shipment File Import

Target release3.5

OLMIS-644 - Getting issue details... STATUS  

OLMIS-5477 - Getting issue details... STATUS

Ashraf please insert the edge case epic here.

Document status
eLMIS StatusImplemented, not in use now in use
OpenLMIS StatusNot Implemented
PATH Jenny Thompson (Unlicensed)
OpenLMIS Mary Jo Kochendorfer (Deactivated)
JSI Ashraf


To enable import of shipment data from an ERP into OpenLMIS so that that data can be visible to facilities and districts, and so that delivery data can be compared to shipment data through OpenLMIS.  Shipment data shows whether and when orders are shipped and any changes between the ordered and shipped products and quantities.  If the facilities and districts have this data, they can take actions such as re-distributions or purchases through private supply chains earlier, rather than waiting for the actual MSD delivery before they know of any changes to their order.  This also increases accountability and visibility showing at what point in the supply chain any problems or bottlenecks occur.

Status in eLMIS: In eLMIS, not in use

Status in OpenLMIS: Not in OpenLMIS

Priority: High priority


After MSD receives R&Rs from OpenLMIS and converts them into orders, a shipment is done.  The shipment may or may not correspond exactly to the order.  For example, amounts may be lower due to lack of stock at the central stores, or lack of availability of one product may lead to another similar product being substituted for it.

MSD records the shipment data in the ERP, but without this feature, this data is not accessible to facilities or districts.  For that reason, facilities and districts do not know whether their order has been adjusted by MSD, whether and when it has been shipped, and when to expect delivery.  

See also sections of the document System requirements specifications for eLMIS interface with mSupply” which discuss export of shipment file. [called out in open questions]


  • Assumes that ERP can provide the shipment file details in our defined format 

User Stories

This feature is documented at 

#TitleUser StoryLabelImportanceNotes
1Import shipment data from ERP to OpenLMISAs a facility/district user, I want to be able to import shipment data from an ERP into OpenLMIS so that data are visible to facilities and districts and delivery data can be compared to shipment data in OpenLMIS.  Tanzania eLMISMust Have
2View shipment dataAs a facility/district user, I want to be able to see when shipments were made and any differences between the products and quantities shipped from what was ordered in OpenLMIS so that I can take action, such as re-distributions or purchases through private supply chains earlier. Tanzania eLMISMust HaveWithout this they have to wait for the actual MSD delivery before they know of any changes to their order.  
3View shipment adjustment data against ordersAs a facility/district user, I want to visibility to order differences against what's shipped so that I can identify and address problems or bottlenecks in the supply chain.Tanzania eLMISMust Have
4Export shipment data from ERP to central store

As a central store user I want data exported from the ERP to OpenLMIS when shipment occurs so that I can track shipments.

Tanzania eLMISMust Have

The shipment file should contain:

  • order number (as generated by OpenLMIS at the time of ordering, and exported into the ERP)

  • ordered product code

  • substituted product code (if different product substituted for ordered product)

  • quantity shipped (of either ordered product or substituted product)

  • packed date

  • shipped date

  • notes (which could contain explanations for any substitution or quantity changes)

  • as an extra feature, it may be useful to list batch numbers and expiration dates.  One product shipment may be fulfilled by multiple batches with different expiration dates.  This feature is not in the current shipment file format in in eLMIS, but was included in specifications for mSupply interoperability.

5Human readable shipment file

As an Logistics office I want data to be included in the shipment file which is human readable, including data that can be derived from the shipment file together with order data and configuration data, so that I can manually cross-check, if needed.

Tanzania eLMISMust Have

To make the information human-readable:

  • facility code

  • program code

  • ordered product name

  • quantity ordered

  • pack size of ordered product

  • product name of substituted product if any

  • pack size of substituted product if any

  • cost of shipped product

6Advance shipment notification

As a supervisor at a receiving facility, I want an advance shipment notification can be sent to me and my facility when shipment data is received into OpenLMIS, an the receiving facility so that I know a shipment is on its way.

Tanzania eLMISMust Have
7Error handlingError handling for shipment files with invalid data ...




Open Questions

1Confirm where “System requirements specifications for eLMIS interface with mSupply” is/which document this is referring to. There's a specifications document and the interface-related Tanzania gap documentation speaks to mSupply, but it's not referenced this way.Chris Opit (Unlicensed) could you share more information on how it is done with mSupply? How does mSupply tell eLMIS about the shipments?Open
2For Tanzania user stories: review the "so thats" added, review the label, and review the priority level.
3Does this align with our documentation or understanding of shipments outlined Order and Shipment files? Is there any diagrams for these?
4Is the shipment file in anyway related to proof of delivery and closing the loop on quantity requisitioned, ordered, shipped, received/rejected (and therefore returned), updated stock on hand at warehouse/depo?

Out of Scope

Gap Estimation Notes 4/12/2018

  • Question: Do they put a file on our FTP server, or do we look at their FTP server?
    • Josh: There is a file format, and there is a "quasi-protocol" in how you name files or where you put them. Order files and shipment files (or whether the order was rejected). 
    • Any FTP server can be used. Both the OpenLMIS and the ERP are pointed to this FTP server, wherever it is.
  • Issues with Product list changing over time
    • There can be issues when the products change.
    • Elias: We dealt with this. WE import all the lines in the file that we can, but the lines that cannot be imported are stored somewhere else in the database. If they solve the issue later, those line items can be re-processed.
    • Josh: Having a common master product list that Epicor/ERP and OpenLMIS and other systems share is a dependency here.
    • Elias: The ERP in Zambia lets users define products, and it lets them define a product any way, and use their own judgement. EG, we saw product codes for World Bank commodities (WB-1234) but it was really amoxycillin. So the shipment file comes in saying WB-1234 and the automation cannot handle it.
  • What and how do we need to build for this feature?
    • Mary Jo: Need to import a shipment file from FTP. Unclear on how far we go on error handling.
    • Mary Jo: OR our strategy could be we tell the ERP they have to hit our endpoint.
    • Josh: OR We say we use same shipment file, parity with previous versions (v0.8).
    • Josh: OR We try to use GS1 and identify a common ERP file format.
  • Flag: “order fill rate report” and others may be impacted (that is a Jasper report in the eLMIS)
  • Elias: We need you to review epic OLMIS-644. This includes "product substitution".

OpenLMIS: the global initiative for powerful LMIS software