23.07. NHLMIS integration

mSupply has an interface with the Nigeria Health Logistics Information System. The interface allows the automatic sending of current stock and pulling of orders from NHLMIS.

The preferences that define how this interface works are managed on the NHLMIS and NHLMIS 2 tabs of the File > Preferences menu. The tabs looks like this:

General preferences

• Server URL: The URL of the NHLMIS interface. Enter everything without the resource to be called and the final “/” e.g. https://dev.api.nscip.field.supply/v1 (this is actually the URL of the NHLMIS test server).
• API key: The authentication key for your organisation. This will be provided by the NHLMIS team.
• Error email: The email address for error emails to be sent to. Separate multiple email addresses with a semicolon (;) if you want error emails to be sent to multiple addresses.
• Stores to send stock and receive requisitions for table: This table contains a row for every store in the datafile. Check the checkbox in the Send stock & Fetch requisitions column (by clicking on it) for each store you want to send stock to and fetch requisitions for in the NHLMIS interface.

Send stock preferences

• Send current stock to NHLMIS checkbox: If this is checked then mSupply will automatically send the current stock stock in each of the stores selected in the Stores to send stock and receive requisitions for table. If it is unchecked then no current stock is sent to NHLMIS.
• No. of days between sends: The number of days to leave between each send of stock. If set to 0 then current stock is not sent to NHLMIS.
• Time to send: The time of day to send the stock. Enter the value in 12 hour clock format and select whether it is AM or PM in the drop down list.
• Manufacturer to use if none: By default, if the stock doesn't have a manufacturer set in mSupply then it is sent to NHLMIS with a blank manufacturer. If you enter something in this field then, if a line of stock has no manufacturer set, then the contents of this field are sent in the manufacturer field. Of course, if a line of stock does have a manufacturer set then it is sent with the name of that manufacturer, regardless of what is entered in this field.
• Send now button: If this is clicked, the current stock in the stores selected in the Stores to send stock and receive requisitions for table will be sent to NHLMIS immediately. This will be an “extra” send and does not affect the automatic send defined by the No. of days between sends and Time to send fields.

Fetch requisitions preferences

• Fetch requisitions from NHLMIS checkbox: If checked then mSupply will fetch all outstanding requisitions (NHLMIS orders) from NHLMIS. The stores they are received for depends on settings in NHLMIS (this is tied to the API key which identifies who is requesting the requisitions/orders).
• No. of minutes between fetches: The number of minutes to leave between fetching requisitions from NHLMIS
• Set “since” marker“ to drop down list: Will contain the date and time that up to 5 previous “since” markers were received from NHLMIS. Selecting one of these will reset the current “since” marker to the one selected and therefore cause mSupply to ask for requisitions ready since that date and time. Useful if you need to force the re-fetching of many previously fetched requisitions because of errors.
• Order ID text box and Fetch now button: These are used to fetch a single order. Enter the NHLMIS order ID in the Order ID text box and click on the Fetch now button to fetch it immediately form NHLMIS. A progress indicator will show how the fetch is progressing.

Send shipments preferences

• Send shipments checkbox: If this is checked then mSupply will send shipments to NHLMIS. If it is unchecked then no sipments will be sent.
• No. times to retry sends: The maximum number of times to try resending shipments that failed to reach NHLMIS.
• Minutes between retries: The number of minutes to leave between attempting to resend shipments that failed to reach NHLMIS.

Synchronise items preferences

• Get new items checkbox: If this is checked, then mSupply will periodically check NHLMIS for new items.
• No. days between requests: The number of days to leave between checking NHLMIS for new items.
• Time to send: The time of day to check for new items in hh:mm format. Use the AM/PM selector to select AM or PM.
• Get now button: When clicked makes mSupply check NHLMIS for new items immediately.

Synchronise customers preferences

• Get new items checkbox: If this is checked, then mSupply will periodically check NHLMIS for new customers.
• No. days between requests: The number of days to leave between checking NHLMIS for new customers.
• Time to send: The time of day to check for new customers in hh:mm format. Use the AM/PM selector to select AM or PM.
• Get now button: When clicked makes mSupply check NHLMIS for new customers immediately.

Click on the OK button to save any settings you have changed; changes will not be put into effect until they are saved by clicking this button

• Store codes: the codes of stores in mSupply must be given the same codes that they have in NHLMIS (warehouse identifiers in NHLMIS).
• Stock: Any stock in a store that needs to be sent to NHLMIS must be assigned a program and donor and must belong to an item with a code that is recognised by NHLMIS. The program is set using the Program drop down list that appears on a supplier invoice line add/edit or stock line edit window when the Send stock checkbox is checked. It is populated with the names of master lists that have an “NHLMISProgram:program name” tag. The program is NOT assigned using custom stock field 5 (commonly used in other installations).
• Master lists: master lists should be created for each NHLMIS program (with a tag in the format “NHLMISProgram:program name”), assigned to the stores that will use themn and then the preference ot control item visibility by item master list turned on. NOTE: this will mean a lot of configuration work when the interface first goes live!

The current stock in each store selected in the Stores to send stock and receive requisitions for table is sent to NHLMIS automatically on the schedule defined by the No. of days between sends and Time to send field.

Each time a send is made the following is done in this order, one store at a time:

1. all the batches in stock (i.e. where available stock is more than 0) that have a program and donor assigned (any other stocklines are ignored) are sent to NHLMIS by calling the /batches endpoint. If all successful then proceed to the next step. If not all are successful then record error and stop.
2. all current stock lines (i.e. where available stock is more than 0 and program and donor have been set) are sent to NHLMIS by calling the /stock-counts endpoint.
   1. Some items have an NHLMISChild property with values in the format ”code,pack_XXX“ where code is the item's code and XXX is the pack size. If the item of any stock line has an NHLMISChild property AND the line is not using the item's default pack size then the code of the item sent to NHLMIS for this line is replaced with the item code in the NHLMISChild property that has the matching pack size value (XXX in the example above). If there is no matching pack size value then no item code replacement is made.
3. The success or failure of each send for each store is logged.

All the outstanding orders (which become requisitions in mSupply) for this mSupply installation which have become outstanding since the last “since marker” are automatically fetched from NHLMIS on a schedule defined by the No. of minutes between fetches field. This is done by making a GET call to the /orders endpoint.

These calls are all made using genericParent=True which means that all items in the NHLMIS response will be replaced with their generic parent items (by NHLMIS). The quantities requested for each item in the order are multiplied by their default pack size to get the number of units for the requisition line.

If there are more than 50 outstanding orders then mSupply will automatically ask NHLMIS to send the next 50 until all outstanding orders have been retrieved.

Each time orders are successfully retrieved, the “since” marker that mSupply uses for the request is updated with the value returned by NHLMIS. And if the “since” marker is for a different day to the last since marker stored, it is added to the Set “since” marker” to drop down list (only the 5 most recent markers are stored in this drop down list - if there are already 5 then the oldest is replaced with the new one).

Each order received from NHLMIS is saved as a requisition in the appropriate store in mSupply. The NHLMIS order ID is stored in the Their ref field of each requisition.

Any orders that have already been received from NHLMIS and saved in mSupply are not saved again, they are ignored.

This occurs when the Fetch now button shown above is clicked. This makes a GET call to the /orders/{suborderId} endpoint, where {suborderId} is the ID of the NHLMIS order to retrieve. As with the scheduled fetching of orders described above:

• These calls are all made using genericParent=True which means that all items in the NHLMIS response will be replaced with their generic parent items (by NHLMIS).
• The quantities requested for each item in the order are multiplied by their default pack size to get the number of units for the requisition line.

When a customer invoice, which comes from a requisition generated from an NHLMIS order, is finalised it is sent to NHLMIs by making a PATCH call to the /orders endpoint. All shipments are sent with a “packed” status. If it is successful, all is well. If the send fails then it is added to a queue and the send is retried after the number of minutes in the Minutes between retries field. When the call is successful then the shipment is removed from the queue. If it fails the number of times in the No. times to retry sends field then the shipment is removed from the queue and an error email is sent to the email(s) in the Error email field.

A GET call is made to the /products endpoint for all NHLMIS services. If an item code returned from these calls exists in mSupply already then it is ignored. If it does not exist in mSupply already then:

• if it doesn't have a Generic parent ID or the Generic parent ID is the same as its ID then it is created as a normal item.
• if it has a Generic parent ID which is different from its ID then it is created as an NHLMISChild property of the parent item (as long as it doesn't already exist as this property!) with a value of “item code,pack_pack size” e.g. “ghsc-mal0004,pack_100”.

In addition, new items will be added to master lists that have tags matching the item's program name (master list tag format is “NHLMISProgram:program name”). If the master list does not exist then it will be crerated by mSupply.

The pack size sent with an item is set as its default pack size.

A GET call is made to the /services endpoint to get all the services that belong to programs in mSupply then a GET call is made to the /locations endpoint for each service in turn. If a customer with the same code exists in mSupply already then it is ignored. If it does not exist in mSupply already then it is created:

• the id is stored in customer custom data so that it can be used when sending shipment information back to NHLMIS.
• state, zone and lga information are stored in the 3 levels of customer category 1 (which must be created before creating the customer).
• the customer is made visible in stores with the same state.

If errors are encountered during any of the processes then information about the error is saved in the log (see the 25.19. The system log page for details) and an email giving details of the error is sent to the email address stored in the Error email field.

When an NHLMIS order is received it is turned into a requisition in mSupply. The requisition has its donor set to the donor in mSupply that matches the value after funder: in the NHLMIS order. The donor is show in the requisition in a Donor drop down list (which is only shown if the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab), shown here:

The drop down list is active so the user can edit it if required.

Supplier invoices have a new Program drop down list, displayed ony when the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab. It is shown here:

It is populated with the names of all the master lists with a tag of NHLMISProgram:XXX where XXX is the name of an NHLMIS program. The user can set the appropriate program for the stock on the supplier invoice.

Read only Program and Donor fields are displayed on a customer invoice if the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab. These fields display the NHLMIS progam and funder (mSupply donor) the customer invoice belongs to and are shown below:

The Program field is populated with the name of the master list which matches the NHLMIS program. It will be empty if there isn't a requisition linked ot the customer invoice.

The Donor field is populated with the name of the donor matching the NHLMIS funder (mSupply donor) associated with the requisition the customer invoice came from. It will be empty if there isn't a linked requisition.

The action of the Issue stock for all placeholder lines option on the grinder icon below the table on the left hand is modified if the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab: it still applies stock in FEFO order but it only uses stock which has a donor and program matching the customer invoice's. If the customer invoice does not have a donor then donor matching is not carried out, if it has no program then program matching is not carried out. If it has neither then the functionality is exactly the same as normal and no additional filtering is carried out.

A Program drop down list is displayed on the stock line edit window (opened by choosing Item > Show items with stock from the menus and double-clicking a stock line on that window). The drop down list will be set to the NHLMIS program associated with the stock and looks like this:

If the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab, the Program is also offered as a column selectable for display on the stock line edit window (opened by choosing Item > Show items with stock from the menus). If you click on the Customise button on that window, you will see the Program field in the available columns as shown here: