Utilizing Mobile: Installation and Use of FrontlineSMS for Basic Data Collection or Outbound Messaging (Part III)
In this addition (Part III) to the Weaver tutorial on FrontlineSMS, we look at the use of Keywords for collection of data and other automated tasks. I will provide several hypothetical examples relevant to the hydro-meteorological community, but there are many, many possibilities. If you are not yet familiar with basic setup and operation of FrontlineSMS, please read Part I and Part II.
What are Keywords?
In earlier versions of FrontlineSMS, the software allowed tracking of some information in an automated way. This was done largely through the Survey feature. Surveys allowed you to take polls or otherwise aggregate information from submitted SMSs.
For instance you might conduct a Survey of crops planted. To do so you create a Survey with the title 'Crop'. This title then becomes a trigger / code word in received mobile text messages to tell FrontlineSMS that the received text is a Survey response. In this hypothetical, any time FrontlineSMS receives an SMS beginning with 'Crop', it will know to start tallying information based upon the rest of the text in the message In example someone might send a message 'Crop Maize'. This message in essence says, "I'm responding to your survey of crops planted. I have planted maize." FrontlineSMS in turn adds a point / count to maize, or if no one else has submitted maize, the new category is created.
The Keywords functionality in the new FrontlineSMS extends and builds upon the original Survey capability. A Keyword is simply a trigger to have FrontlineSMS perform another action. This action might be an auto-reply to the sender of the original message. The auto-response might even target a group of contacts rather than just one individual, and rather than an auto-response, the original message could be forwarded to a group. It could also send a message to an e-mail address rather than as an SMS. The Keywords feature can also be used to make an HTTP request, which in turn could trigger almost any subsequent action.
In short the Keywords module extends the functionality of FrontlineSMS from a simple messaging client to a tool that can be used to trigger and manage a variety of processes via mobile text messaging.
Example 1: Forecast Upon Demand
In this first example I'll demonstrate the ability of Keywords to auto-respond to incoming SMS messages. For instance you could allow individuals to receive a daily forecast upon demand. In this workflow a farmer or agricultural extension agent might send a mobile text message to your FrontlineSMS system. This message would begin with a keyword that in essence is the request for a forecast. Let's say this is simply 'dailyforecast'. Upon receiving a message that begins 'dailyforecast', FrontlineSMS will reply back to the original sender with a forecast message you update.
To start you will need to go to the Keywords tab. If the tab is not visible, in the menu bar go to View and then Tabs. You should then ensure the Keywords tab is checked.
In the Keywords window you will see the screen divided into two sections. The area to the left will list all your Keywords, but of course right now it is empty.
You can create a new Keyword in three different ways. First option is to simply right click the menu area to the left on the 'Add keyword' item. Then select 'New Keyword'.
An alternative is to simply click the button on the bottom left of the Keywords tab that says 'New'.
Both of these options will pop up a new mini-window asking you to enter a keyword and a description.
In this new window, under "Create new keyword", you should enter the actual keyword you want to be used as a trigger. This is not simply a title, but rather it is the actual trigger keyword that the sender will use as the first word of the text message.
Another option to the two just mentioned is to simply begin filling out the form on the right hand side of the Keywords tab.
I'll use this option in my example. So lets create a daily forecast keyword for a particular region. I'll choose Kayunga in Uganda as a hypothetical. To keep the trigger somewhat short and easy to enter via a mobile phone, I'll shorten the keyword to "DFKayunga". I'm just making it shorter so that a user doesn't needlessly spend time typing letters. Also, the case does not matter here, so the user can as easily type "dfkayunga" or "DFKAYUNGA" and get the same result. Clearly, I'm assuming that forecasts would vary by region, so Kayunga is mentioned by name in the keyword. To have a forecast auto-response for other cities or regions of a country, you will have to create separate keywords.
Now, we need to enter a message that will be an auto reply. In this case I've entered a fake forecast, but you get the idea. Ensure you check the box for sending the auto reply. Now click Create, and you are all done.
Our Keyword will now appear in the menu to the left. You can highlight any Keyword to edit or delete it.
Clearly, for a daily forecast someone operational will need to update the text every day or multiple times a day in FrontlineSMS to ensure it is current. Another important thing to pay attention to is the format and length of your SMS. Again, each SMS will incur a cost, therefore it is best to have your system reply with a single SMS rather than a multipart message. If you decide to establish this sort of functionality you will need to play around with format and guidance you provide to the forecasters who will enter the information. Use abbreviations where possible, but ensure you do not shorten it so much that information will not be lost. Similarly, avoid using punctuation that doesn't help to make the message more readable. For instance in the above example I shortened temperature to 'Temp'. Similarly, I did not use a period in my abbreviation, as each period would add a character and therefore increase the length of my message. You'll simply have to know your users to be able to strike a balance between brevity and clarity.
Note, there is a small bug in FrontlineSMS 1.5.8. Keywords with character counts in multiples of four (4, 8, 12), such as 'test', will not work properly. For some reason FrontlineSMS will not recognize the Keywords with character counts in multiples of four. There is a good chance that this will be fixed by the time you read this tutorial and have downloaded a more recent version. Nonetheless, if you have played with Keywords and notice they are not capturing incoming messages properly, try either shortening or lengthening the keyword by one character. For example, in my initial experimentation with FrontlineSMS, I created a Keyword of 'test'. This didn't work, but when recreated as simply 'tst', it worked fine. A discussion of the issue is available in the FrontlineSMS forums.
Now its time to try out your keyword. With a separate mobile device, send a message to your FrontlineSMS system where the SMS is simply 'dfkayunga' -- or whatever keyword you chose to create.
After sending the message from your mobile device, you can monitor progress by going to the Messages tab in FrontlineSMS. Click on 'All messages' in the left hand menu and look for a received message. Once received you should see an outgoing message from FrontlineSMS. And of course you should then soon receive the forecast message you created on your mobile device.
Clearly, you could extend this sort of 'on demand' information service to applications beyond forecasts. But in this simple example we established some fairly advanced functionality in just a few minutes.
Example 2: Field Requests for Assistance
Within RANET, but really any program with remote field sites, one of the greatest challenges is knowing in a timely fashion if there are technical issues or failures. Without other communications it may take days before someone in the rural community can send a message back to the central office. Moreover, time delays only increase if the message is routed to the wrong person or if that individual is unavailable.
With FrontlineSMS and the Keywords functionality, you can setup a 'help line' for field partners. In this case they might send a message like 'TechSupport Station fuse blown.' In this hypothetical 'TechSupport' is the trigger keyword telling FrontlineSMS it is not just a normal message, but rather it is a message requiring some special action taken by FrontlineSMS. The rest of the message ('Station fuse blown.') provides some details of the technical trouble faced by the community. Rather than simply receive the message, we'll use FrontlineSMS to actively try to reach project managers and technicians that might be able to help. To do so, we'll have FrontlineSMS send a mobile text message, containing the original message from the field site, to one or more technicians. We'll also have FrontlineSMS forward via e-mail the technical support message to several e-mail addresses associated with technicians and project managers. (Of course for the e-mail functionality to work, the FrontlineSMS station will need to have internet connectivity.) Finally, FrontlineSMS will also send an auto-reply back to the field site, letting them know the message has been received and someone will look into the issue further.
As before we'll create a new Keyword. In this case the trigger word is 'TechSupport'. I'll enter an auto-response to let the field site know the message was received and is being routed to someone that can help.
Once created, click again on the keyword in the left hand menu. You will notice under the form on the right hand side, there is now a link to open up advanced options.
Click this link, and you'll be presented with a new screen. At the bottom you can select the type of special action FrontlineSMS should take. Let's have it auto-forward the message as an SMS to a technician's mobile phone. Select auto-forward.
Now click the add button to the right of the selection menu.
By clicking the add button a new window will appear. In this window you select the group (as created in your contacts list) to which the message will be forwarded. Next you will need to determine what the forwarded SMS message should say. In my example I start it with 'URGENT:', and then pressed the 'Sender Name' and 'Message Content' buttons. By pressing these buttons, dynamic variables are inserted into the form. Not surprisingly these variables are placeholders to insert the sender's name / mobile number and the message into the SMS that will be forwarded to technicians.
Now, when FrontlineSMS receives a message starting with TechSupport, it will forward the message to a contact group. The message forwarded will begin with 'Urgent:'. This will be followed by the sender's name, and then finally the message from the person requesting help.
While I chose not to use it, you can select a start and end date for this process. While not useful in our hypothetical example, this might be useful to set if you had a project or other activity that would end after a certain period of time. For example, some government information is embargoed until a certain release date. Therefore you could setup your system in advance, but you could instruct it not to respond to requests until a certain start date. Similarly, you may have seasonal forecasts or other information (cyclone outlooks) that are no longer valid after the end of a season. Therefore, rather than have people access outdated information, and cause your system to incur costs sending them invalid information, you could have the Keyword functionality disabled by a certain date.
Now, finally, we can also have our Keyword for technical support forward the message via e-mail. To do so we need to set up an SMTP server account. Go to the 'Setting' menu item to select 'Email Settings.'
You will need to fill out the following form to add a new account. It is important that the SMTP information be filling out, otherwise FrontlineSMS is unable to send messages. If you don't know this information, it can generally be found in your e-mail client settings (Thunderbird, Outlook, etc.) or you should contact your local network administrator. For RANET countries, an SMTP server can be provided.
Now that your e-mail account is setup, go back to the Keywords tab. Select E-mail from the menu of process options located at the bottom of the right hand side of the tab.
After selecting E-mail, click the add button. This will bring up the following window.
This form is much like that we filled out for forwarding the message as an SMS. Create a useful subject, and as desired add some dynamic information into the subject, such as 'Sender Name', 'Sender Number', etc. You add these variables by positioning your cursor in the subject field and then clicking the appropriate button for 'Sender Name' or similar.
You can also set up a standard message for the body of the e-mail. As with the subject field you can add some dynamic variables which would include the incoming message, sender, etc.
For the From field you should select the e-mail account you created earlier, or select the e-mail account you wish to use. FrontlineSMS will use both the SMTP server and e-mail account to send the message.
And finally you should either select an e-mail address (from your contacts) to which the incoming SMS will be forwarded, or simply type in the e-mail address you wish to use. You can set up start and end dates as described earlier.
That's it. Your Keyword script is ready to run. When an SMS with 'TechSupport' as the first word in the message is received, FrontlineSMS will send an auto-reply back to the sender letting him know the message was received and that help is on the way. FrontlineSMS will then forward the message as an SMS to one or more technicians defined in a messaging group from our contact list. And finally, FrontlineSMS will forward the message as an e-mail to one or more recipients we designate.
Example 3: Keep Emergency Managers Linked
One of the original designs of FrontlineSMS was to help keep groups of individuals in small organizations linked via SMS. A hypothetical need and application of this group functionality might be to keep emergency managers connected. In this example we create a group in our contacts list. Let's call it "EMs". Now, we create a Keyword such as "EMsList". Do not create an auto-reply message or other functionality. Assuming you have read the previous examples, I will not provide a step-by-step on how to create a new Keyword or create a group in the Contacts tab.
With both of these created, go back to the Keywords tab and select our "EMsList" keyword. Now, select the advanced view option.
In the new window, use the menu list of processes to select Auto Forward, and then click the add button.
A new window will pop up. We've used this functionality before in example two. Here, we will select our newly created group; EMs. Then we'll set up a message template / format. Here I've chosen to have the SMS begin with "EMs:", which is then followed by the senders name. Since FrontlineSMS will be forwarding this message, it will not be apparent who sent the original SMS. Providing the name, although it consumes our limited characters in an SMS, provides some clarity. This is then followed by the actual SMS message.
That's it. Now, if you have emergency managers or any similar group that needs to broadcast messages to one another, you can use the powerful Keywords feature to have SMSs automatically forwarded. All the users need to do is send an SMS to the FrontlineSMS modem and begin their message with the Keyword associated with the group distribution. In our case this Keyword was EMsList.
Note, that while I have used a combination of upper and lower case letters for my keyword, this will not affect how a user must enter the keyword into an SMS. FrontlineSMS should see EMsList, EMSLIST, and emslist as all the same thing. Using a combination of upper and lower case letters within FrontlineSMS makes managing a long list of Keywords easier. At the same time your users should enter the keyword as is easiest for them. On small mobile phones, they need not and should not go through the hassle of switching between upper and lower case.
Example 4: Web Server Interfacing
This hypothetical example won't be provided in full detail. The applications are many and require some ability to perform server side scripting. That said, suppose you wanted some messages or field reports to be automatically posted to a website. For instance, you might have a network of automated weather stations (AWSs) which are able to send reports via SMS. Clearly these can be setup to send messages to FrontlineSMS, but it'd be nice for the information to also be processed into a database suitable for operational roles and analysis, and similarly, why not post current weather conditions to your website. Once again, FrontlineSMS and its Keywords module can help you do this.
As with the examples above you should create a Keyword. Do not create an auto-reply. Once created, select the Keyword once more from the left menu list, and then in the right menu, select the advanced tab option. Now select the 'External Command' option from the menu of processes, and click the add button.
A new window should pop up. As shown in the example image below, you can select an execution type. If using HTTP request, FrontlineSMS will send a series of variables to a script you have created on a website. This script might be PHP, ASP, etc. The script would do the heavy lifting of processing data, placing messages in a database, posting information to a website, etc. etc. I've entered an example of how this might be entered under Execution Details. If you don't quite follow what is going on here, do not worry. This functionality is really intended for a server administrator or programmer, but knowing the general possibility is worthwhile. For RANET countries, the RANET team can help write or assemble necessary code to achieve your objective.
The other execution type is "Command Line Execution." This is used more for triggering actions or command line scripts on the local computer. For instance you might have a script that reports how much disk space is left on a server, copies files for backup, etc. etc. This might be useful if you are remotely administering a system where internet is not available. By sending a FrontlineSMS system a special command / keyword, you could get status reports of the computer, have it restart, and similar.
I won't go into detail, but you can have FrontlineSMS wait for a response as well, and then based upon the response, send a message. An example might be to retrieve your remote server status. For instance, say you are in the field. You could send an SMS message to your FrontlineSMS installation. This SMS would be a Keyword that sends an HTTP Request to your server asking for some type of status information. Your server, through a server side script, returns a response, which is then forwarded once more to you on your mobile. This might be useful for retrieving the system status or other information stored in a database.
You could also use this for a more advanced version of the forecast on-demand example discussed earlier. Rather than having your operators enter information into FrontlineSMS each day, the forecast could be pulled from a server database or text file. This might be more advantageous if the forecast is already part of your standard operating procedures.
In short the External Command feature adds powerful functionality to have FrontlineSMS interface with servers and other computing infrastructure. Moreover, it may be the best way to have FrontlineSMS interface with legacy infrastructure and operations. At the end of the day, some knowledge of a server side scripting language, such as PHP or ASP, will be necessary. For RIPI and other RANET participants, RANET can write custom scripts and functionality upon request.
