Shipment File Import

Target release	3.5
Epic	https://openlmis.atlassian.net/browse/OLMIS-644 https://openlmis.atlassian.net/browse/OLMIS-5477 @Ashraf please insert the edge case epic here.
Document status	DONE
Priority	HIGH
eLMIS Status	Implemented, not in use now in use
OpenLMIS Status	Not Implemented
PATH	@Jenny Thompson (Unlicensed)
OpenLMIS	@Mary Jo Kochendorfer (Deactivated)
JSI	@Ashraf

Goals/Scope

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

Background

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]

Assumptions

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

User Stories

This feature is documented at https://openlmis.atlassian.net/browse/OLMIS-644

#	Title	User Story	Label	Importance	Notes

#	Title	User Story	Label	Importance	Notes
1	Import shipment data from ERP to OpenLMIS	As 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 eLMIS	Must Have
2	View shipment data	As 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 eLMIS	Must Have	Without this they have to wait for the actual MSD delivery before they know of any changes to their order.
3	View shipment adjustment data against orders	As 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 eLMIS	Must Have
4	Export 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 eLMIS	Must 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.
5	Human 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 eLMIS	Must 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
6	Advance 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 eLMIS	Must Have
7	Error handling	Error handling for shipment files with invalid data ...

Diagrams

Dependencies

Description	Link

Description	Link

Open Questions

	Question	Outcome	Status

	Question	Outcome	Status
1	Confirm 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
2	For Tanzania user stories: review the "so thats" added, review the label, and review the priority level.		Open
3	Does this align with our documentation or understanding of shipments outlined Order and Shipment files? Is there any diagrams for these?		Open
4	Is 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".