19.02. FrontlineSMS integration

mSupply has the ability to integrate with your FrontlineSMS installation. This allows you to send your current stock levels to mSupply using an SMS (text) message from any mobile phone. This is particularly useful if, for example, you are a mobile or remote health post or dispensary which doesn't have internet access and only needs to send in information about a few items at a time.

To get mSupply talking to your FrontlineSMS installation, follow these simple steps:

1. Tell mSupply the details of your FrontlineSMS database

You do this on the FrontlineSMS tab of the mSupply preferences page (File > Preferences). See here for a detailed description of how and what to set.

2. Set the SMS code and pack size of the items you want to receive information about

Because SMS messages need to be kept short (they are only allowed a limited number of characters), instead of writing the full name of an item in an SMS message you simply write a short code which represents it. It is impossible for mSupply to know the pack size of the items being counted in the remote store so you also need to enter a pack size to be used for calculating item quantities from the pack quantities supplied in an SMS. You set both the SMS code and SMS pack size for an item in the Misc tab of the item's Item details window (via the Items > Show items menu). For detailed instructions see the 'The Misc(ellaneous) tab' part of 'The Item Details Window' section on the items basics page here.

3) Add SMS senders as contacts to customers

mSupply needs to know which of your customers an SMS message has been sent from. To give it this information you simply add each mobile phone number that will be sending messages to mSupply to the appropriate customer as a contact. To do this use Special > contacts (see here for details) or Customers > show customers, select the customer, go to their contacts tab, click on the Add contact icon and enter the contact's details.

Please note: whichever way you do it, the phone number must be entered exactly as it is recorded in FrontlineSMS (it will probably include the international dialling code e.g. +977 but this will vary with phone service providers). You can find out how FrontlineSMS stores a sender's number by sending a dummy text message and viewing its details in FrontlineSMS.

4) Make sure that emailing is turned on in mSupply

mSupply will inform the people selected in the preferences (see step 1 above) by email when a message has been received and is successfully processed or has an error. But mSupply can't send the emails if you haven't configured it to. To set up emailing, go to File > Preferences and click on the Email tab. See the E-mail section of the general preferences page here for details of the various settings.

OK, that's the setup complete and you're ready to…

5) Send an SMS message to mSupply

The text message you send to mSupply must be in the correct format. Any mistakes and the message will be rejected and will have to be resent. The correct format is this:

keyword item_code item_value item_code item_value…

keyword: This is the keyword you set in the Frontline preferences (step 1 above) that enables the software to recognise a message as intended for mSupply. If this keyword does not exactly match what is set in the FrontlineSMS preferences mSupply will ignore the message.

item_code: An SMS code identifying an item in mSupply. You set these in step 2 above.

item_value: The number of the item represented by item_code that you have in stock. Obviously, the number must not be negative!

You can have as many item_code and item_value pairs as a single text message will allow. But they must always be paired. If mSupply finds an item_code not matched with an item_value it will reject the message and it will need to be resent.

Every single element (the keyword, an item_code or an item_value) of the message must be separated by a space.

To make all this clear, let's have some examples:

A valid text message: msm am 1000 lp20 2000 cf 1 (msm is the keyword; am, lp20 and cf are item SMS codes; 1000, 2000, 1 are amounts of the corresponding items in stock and each element is separated by a space)

An invalid text message: msm am 1000 lp202000 cf 1 (msm is the keyword; am, lp20 and cf are item SMS codes; 1000, 2000, 1 are amounts of the corresponding items in stock but the space between lp20 and 2000 has been missed out. mSupply will interpret lp202000 is an item SMS code which doesn't have a paired value and reject the message)

A valid text message: s 201 1000 102 3000 lf 200 (s is the keyword; 201, 102, 1f are item SMS codes; 1000, 3000, 200 are amounts of the corresponding items in stock and each element is separated by a space)

An invalid text message: msm am 1000 lp20 -2000 cf 1 (everything's OK except the -2000. A stock value can't be negative so mSupply will reject the message)

It is OK to enter multiple spaces where there should only be one or to add leading and trailing spaces to the message. Because mSupply is clever software it will know what you meant and ignore the extra spaces.

When an SMS message has been received by mSupply an email will be sent to the recipients selected in the FrontlineSMS preferences (set in step 1 above). It will tell them that it has been successfully processed or that there was an error (and will give details of the error). In the case of a successful message mSupply will also create a reminder (see here for information about reminders) for the recipients selected in the FrontlineSMS preferences. In the case of an error, the e-mail recipient should contact the sender to correct the mistake and resend their message.

6) View and complete the stock history record

When mSupply has successfully processed an SMS message it produces a Customer stock history record of the appropriate type (imprest or stock history) for the appropriate customer. See Customer stock history records for more information on these. The stock history record will have a status of 'suggested' and must be viewed and completed by someone in mSupply before it is turned into a customer invoice.

The point of creating reminders for people on successful receipt of an SMS message is that the customer stock histories don't get forgotten!

7) If anything goes wrong

Any errors which occur during the processing of SMS messages are sent by e-mail to the people selected in the FrontlineSMS preferences so that appropriate action can be taken. The error messages detail the problem to make troubleshooting easier. The most likely problems with SMS messages are:

Sender phone number not added as a contact to a customer in mSupply or not added exactly as it appears in the FrontlineSMS database.

Keyword forgotten or wrongly typed. In this case the message will appear to have disappeared into thin air! mSupply will ignore it because it is the keyword that identifies it as an mSupply message.

Space missing between message elements. You will receive an error message about item codes and item values not being paired in this case.

Please note that all SMS and FrontlineSMS database error messages are also written to the log: to view them go to Special > View log (if you want to display only SMS errors select the 'SMS error' item in the right hand drop down list in the log display window). This can be very helpful for working out if anything's gone wrong, especially if emailing is not working (because you've forgotten to set it up - in step 1 above - or your internet connection is broken or slow).

Previous: 19.01 DHIS2 Integration | | Next: 19.03 The mSupply eLMIS interface