FOR ARCHIVAL PURPOSES ONLY

The information in this wiki hasn't been maintained for a good while. Some of the projects described have since been deprecated.

In particular, the "Ushahidi Platform v3.x" section contains information that is often misleading. Many details about this version of Platform have changed since.

This website is an extraction of the original Ushahidi wiki into a static form. Because of that, functions like logging in, commenting or searching will not work.

For more documentation, please refer to https://docs.ushahidi.com

Skip to end of metadata
Comment: Migrated to Confluence 4.0
Go to start of metadata

Introduction

FrontlineSMS and Ushahidi are both free and open source software tools, widely used by social change projects the world over. FrontlineSMS is used to enable users to send, receive and manage large numbers of incoming and outgoing SMS. Ushahidi is a platform for information collection, visualization and mapping. Used together these tools can produce powerful results, with FrontlineSMS being used as a tool which can manage incoming SMS data which can then be visually represented using Ushahidi.

Approximate time required to configure: 20 - 30 minutes

Documentation in PDF format

Technical requirements

  • FrontlineSMS software (free to download)
  • Compatible USB modem to use with FrontlineSMS (list available here)
  • Ushahidi software: Select either Ushahidi Platform (server-based) or Crowdmap (Cloud-based) 
  • Any phone that can send and receive SMS
  • Internet connection

Step One: Setting up

Download and install v1.7 of FrontlineSMS. As this is the legacy version of FrontlineSMS, make sure you are downloading v1.7 and not the newer v.2X version. If you don’t yet have an instance of Ushahidi or a Crowdmap online, download the Ushahidi platform or launch a new Crowdmap. If you need help, please refer to the Ushahidi Adminstration guide in this wiki.

Once everything is installed let’s start with opening FrontlineSMS and connecting the software to a compatible device according to these instructions.

Next, test that FrontlineSMS is receiving messages from your mobile phone or modem by sending a couple of SMS. If it is not working, read through the user resources section of the FrontlineSMS website and check the Frequently Asked Questions.

Step Two: Ushahidi configurations

In the add-ons tab of your Ushahidi or Crowdmap installation, click on 'show all' and navigate to the 'FrontlineSMS plugin'. Click on 'activate' and then on the 'settings' link next to the title.

This link takes you to a summary of related actions. If you're using Ushahidi, you'll need to use the Ushahidi Sync Key, below. Copy and paste this and the FrontlineSMS HTTP Post link into a text file.  

Please note: In FrontlineSMS Version 1, you are not able to copy and paste text on a Mac, so you will need to enter the above manually.

Step Three: FrontlineSMS provider configuration

In the settings section at the top right of the dashboard, navigate to the SMS tab. Under 'default sending provider', set the option to 'FrontlineSMS'. Enter the phone numbers that are connected to your FrontlineSMS instance, then save settings.

Step Four: Setup FrontlineSMS keywords

In FrontlineSMS, open the Keywords tab, select the ”<NONE>” keyword (1.6.16.3 or earlier).

Next, click on the “click here to go to advanced view” link on the right below the “Keyword Actions” section. At the bottom of the screen, click on “Auto Reply” and in the menu that pops up select the “External Command” option.

Step Five: HTTP requests

In the window that opens, select “HTTP Request” as the execution type, paste the URL you copied from your Ushahidi deployment above into the command text field that is in the “Execution Details” section and select the “Do Not Wait For Response” button. Leave all the other fields untouched.

Then click “Done” and the process should be complete. Any SMS messages sent to FrontlineSMS will also be forwarded to the admin page of your Ushahidi platform.

Step Six: Testing

Test Ushahidi and FrontlineSMS working together: send an SMS to FrontlineSMS while the keyword action is set up. You should see the message come into FrontlineSMS on the 'latest events' box on the Home tab, and then a 'hit' register on the far right column of the keyword action box in the Keywords tab. A report should then appear in your Ushahidi or Crowdmap installation.

Tips and Tricks

Here are a few pointers to help you with the process. If you have more tips, please add them!

  • FrontlineSMS will not retry the HTTP Request if it fails for whatever reason. This means that any SMS messages that come into FrontlineSMS while your Internet connection is down will
    not be automatically forwarded to your Ushahidi deployment. To pause your receiving device, double click on it in the 'phones' tab and uncheck 'use to receive SMS'. When the Internet is restored, check this box again and SMS will start to come through again.
  • Remember that your phone may freeze occasionally or the connection to the receiving device may be lost, so you need to keep an eye out for this. If this happens you can fix it by quitting FrontlineSMS and disconnect and reconnect the receiving device.

Examples of FrontlineSMS and Ushahidi being used together

FrontlineSMS and Ushahidi have been used together in many powerful and inspiring ways including to monitor elections in Nigeria; to map harassment on the streets of Egypt; to track incidences of violence against children in Benin and to demonstrate and challenge incidences of human rights abuse in the Democratic Republic of Congo. We hear from new users regularly who are keen to use the software together, and this resource is intended to make that process as easy as possible.

More Help

We hope that this was useful for you. If you have run through these steps and need further support OR if you would like to add best practice tips to our guide and help other users with this process please visit