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

Approximate time required to install, configure, and test: 15 - 25 minutes

Introduction

FrontlineSMS and Ushahidi are 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, curation, and geospatial visualization. Used together, these tools can produce powerful results, with FrontlineSMS managing incoming mobile data and Ushahidi handling the visual representation.

Technical requirements

Step 1: Setting up

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.

Download and install v2.2+ of FrontlineSMS. Their walkthrough installer is like installing most any other software on your computer and should be fairly straightforward.

Step 2: Configuring the FrontlineSMS Ushahidi Add on

Log into your Ushahidi instance. In the "Addons" tab of your instance, you'll find the complete list of addons that extend Ushahidi's core functionality. Find the 'FrontlineSMS' addon. We'll need to enable this for the two platforms for communicate, so click on 'Activate' on the right. Confirm that you wish to activate this plugin in the dialog box that appears by clicking 'OK'.
Now the FrontlineSMS plugin is active and we can almost connect the two platforms. Our final step is retrieving a key piece of information we'll need to plug into FrontlineSMS: the "Sync Key." You can find this by clicking the 'Settings' link next to the "FrontlineSMS" title of the addon. This will open the FrontlineSMS addon settings where you will find the Sync Key. Copy this key; we'll cover where to plug it in in the next step.  (Note: You may ignore the "FrontlineSMS HTTP Post Link" URL as that pertains to the 1.X versions of FLSMS.)

Step 3: Setup a new activity in FrontlineSMS

On the left sidebar, click on the "Create new activity" under the "Activities" section.

 

A new window will appear and you will be presented with a number of options. Choose "Web Connection" at the bottom of the list.

Selecting Web Connection will present a new set of options. Select "Crowdmap / Ushahidi" and click "Next" at the bottom right.

For Crowdmap:
Click the Crowdmap button and add the following settings: Complete your Crowdmap deployment URL and API key (the "Sync Key" from your deployment).

For Ushahidi:
Click the Ushahidi button and add the following settings: Add your custom URL and API key (the "Sync Key" from your deployment).

Once you've entered this, click the "Next" button at the bottom right and you'll come to some final configuration options.

On this screen, you have the option to configure FrontlineSMS to automatically move messages into your Web Connection and pass SMS reports up to Crowdmap. To automatically process SMS in this way select, "Process responses containing a keyword automatically."

Alternatively, you can select the "Do not use a keyword" option, which will result in all incoming messages triggering the Web Connection provided they do not match any other activities' keywords. Only one activity at a time can have this setting.

The third option, "Do not automatically sort messages," you can also disable automatic sorting altogether. With this setting you can still use your Web Connection's functionality by manually moving messages into your new activity from the inbox or any other activity or folder. This allows you to manually choose which incoming SMS get passed up to Crowdmap. When you have finished setting up your automatic sorting options, you can set your keywords. You can enter any number of keywords separated by commas. With this setting, any incoming message that starts with one of those keywords will trigger the Web Connection.

Once you've decided how to deal with incoming messages, click "Next" again at the bottom right.

On the final screen you will find a summary of all your selected options to confirm the correct settings before creating the activity. You will also be prompted to give a name to your Web Connection to make it easily recognizable from the list of activities on the messages tab.

When you've finished, click "Next."  The dialog box confirms that the Web Connection has been created and you can click "OK" to close the window. This new Web Connection will appear in the left sidebar under "Activities." Clicking on the name here in the future will show the settings and any messages matching those filter settings (if any).

Step 4: Testing

Now that the platforms are connected, it's time to do and end-to-end test to ensure that messages received in FrontlineSMS will appear within your Ushahidi or Crowdmap deployment.

Begin by connecting FrontlineSMS to a compatible device. Test that FrontlineSMS is receiving messages from your mobile phone or modem by sending a couple of SMS, being sure to include a keyword if you specified that. You should see the message come into FrontlineSMS in the "Messages" section, or listed within your activity. A report should then appear in your Ushahidi or Crowdmap installation as well.

If it is not working, read through the user resources section of the FrontlineSMS website and check the Frequently Asked Questions. 

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 assistance or if you would like to add best practice tips to our guide and help other users with this process please visit