23.04. mSupply eLMIS interface

eLMIS stands for Electronic Logistics Management and Information System and is a version of OpenLMIS developed under the USAID Deliver project. mSupply has an interface for receiving orders from eLMIS and sending shipment details back to it.

Because eLMIS does not have an API, the mSupply interface uses files stored in a commonly accessible location to share information.

Before the interface can be used it has to be setup correctly. These are the setup steps you need to follow:

A computer file storage location must be created somewhere that is accessible by both the mSupply and eLMIS servers to directly write files. If a common location does not exist because the mSupply and eLMIS servers are on separate non-linked networks you can create a separate location on each of the mSupply and eLMIS servers and link them using a file synchronisation utility such as Dropbox.

When you have the centrally accessible location sorted out, create a main folder then some sub-folders according to the following:

In this picture we have called the main folder Transfer. You can name yours anything you like but the other folders must have exactly the same names as shown.

Go to the mSupply Special > Preferences window and select the eLMIS tab. Please see the 16.01. General preferences > elmis_tab section in this user guide for information on these settings.

The interface assigns the incoming orders (turned into customer invoices in mSupply - see below) to the correct annual budget period for customers. The budget year is assumed to start on 1st July. So, create a budget period starting on the 1st July in the current budget year and assign that budget period to all the customers you will be importing orders for via this interface. See the 8.08. Customer budgets page for details on doing that.

1. Set eLMIS to export its order files to the main folder/Order/Incoming folder when orders are created.
2. Set eLMIS to look for incoming shipment files in the main folder/Shipment/Incoming folder on a regular basis.

Please consult your eLMIS documentation for information on these steps.

When it's running the interface does 2 things:

Each time the interval set in the settings elapses, mSupply checks the main folder/Order/Incoming folder for new order files from eLMIS. If it finds one it reads the file and turns it into a customer invoice. The customer invoice will have these features:

• its status will be “sg” (suggested)
• its Their ref field will have the value “eLMIS:XXXX.” where XXXX is the eLMIS order number
• it will have a placeholder line for every item in the order file

The Their ref field makes a customer invoice created by the interface easy to spot. Feel free to add anything to the Their ref field after what the interface has put in there but not before. mSupply uses it to generate the shipment file for this order later on.

See the Order file format section below to see the format the order file must have.

If the order is successfully converted into a customer invoice the eLMIS order file is moved from main folder/Order/Incoming to main folder/Order/Processed.

If there is a problem and the order file is not converted into a customer invoice then the order file is moved to main folder/Order/Error. In addition, an error file is created and is also placed in main folder/Order/Error. The error file has the name “XXXX-YYYY-MM-DD-HH-MM.err.csv” where XXXX is the order file's filename without its extension. See the Error file format section below for the format of the error file. An error email with the error file attached will also be sent to the error email address set in the mSupply preferences.

When a customer invoice that was created by this eLMIS interface (mSupply recognises them by the contents of the “Their ref” field) is confirmed then mSupply will create a shipment file for it. The shipment file will have the filename “SHPXXXX.csv” (where XXXX is the invoice number of the customer invoice) and will be saved to the main folder/Shipment/Incoming folder.

See the Shipment file format section below for the format of this file.

If there are any problems creating the shipment file, mSupply will display a message describing the problem. Please note that you will not be able to confirm the customer invoice until all the problems preventing the creation of the shipment file are corrected.

Well, the good news is that day-to-day you don't have to do anything. The interface will continue running quietly in the background processing order files and creating shipment files as the customer invoices are confirmed.

Periodically you should check the error email address set in the eLMIS preferences for messages about errors. Remember the order files that have caused errors can be found on the main folder/Order/Error folder. Note that mSupply does not put anything in the main folder/Shipment/Error folder - eLMIS only uses that folder when processing the shipment files.

The only other time you will hear anything from the interface is if mSupply detects an item on a customer invoice that wasn't in the original eLMIS order. This will happen if one of the item placeholder lines was replaced with a different item (e.g. because of low stock or a preferred item is to be used). In this case, mSupply will show a window and ask you to tell it which item on the original order you replaced with the item in question. Once you have selected the item that has been replaced mSupply will continue creating the shipment file.

This a text file in csv format, each element of data is enclosed in “ characters. The first line of the file will contain headers only (ignored by mSupply), subsequent lines contain data in the following order:

1. Warehouse code. This is the code the store in mSupply that this order (customer invoice) belongs to.
2. eLMIS order ID. Stored in the Their ref field of the customer invoice.
3. Item code. The code of the item being ordered.
4. Product name. The name of the item, as stored in eLMIS. For reference only, not used by mSupply.
5. Customer ID. The code of the customer this order is from.
6. Quantity. The number of packs (default pack size) of this item ordered.
7. First day of reporting Period. The date of the first day of the reporting period (budget period in mSupply) to which this customer invoice is to belong in the format YYYY-MM-DD.
8. Line number. The number of this line in the order.
9. Order date. Date the order was placed.
10. Price. The unit price of the item. Optional, might not be sent from eLMIS, not used by mSupply.

This a text file in csv format with the name “SHPinvoice number.csv” where invoice number is the customer invoice's number in mSupply (e.g. “SHP1234.csv”). The first line will always be “Order No, Product Code, Batch, Quantity Shipped, Cost, Packed Date, Shipped Date, Facility Code, Quantity Ordered, Substituted Product Code, Substituted Product Name, Substituted Product Quantity” (i.e. the column headers only), subsequent lines contain data in the same column order, each element enclosed in ” characters.

A text file with the name “filename without extension-YYYY-MM-DD-HH-MM.err.csv” where filename without extension is the filename of the order file which the error file is generated for and YYYY-MM-DD-HH-MM is the current date and time in 24 hour format (e.g. ORD12345-2015-05-30-14-35.err.csv).

The file contains 3 lines:

1. file name without extension: Error description where file name without extension is the eLMIS order file name without its extension and Error description is a description of the error that has been found e.g. “ORD10002: Facility code not found”
2. Line number: XX where XX is the number of the line in the order file which has the error. e.g. “Line number: 3”
3. Hint: Hint to fix it where Hint to fix it is a hint on how to fix the error e.g. “Hint: Make sure facility code is available in eLMIS, enter the facility code into the file”