Integrating Frontline SMS with ODK Aggregate

FrontlineSMS is a very easy-to-use tool for SMS data collection that can be integrated with other data systems. The steps for integrating with ODK Aggregate are pretty straighforward:

  • Download and configure FrontlineSMS to receive SMS'.
  • Customise a php script to process the received SMS' and forward the data to ODK Aggregate

Configuring FrontlineSMS to receive SMS'

Download FrontlineSMS by filling out their download form. It is available for Windows, Mac, and Linux. After installing, you may configure it to accept SMS' from a mobile phone, 3G modem, or external server. In this example, I'm using it with a SonyEricsson phone. Launch FrontlineSMS without the phone connected. Wait a few minutes to let the auto detection to fail.

Screenshot showing ports failing to connect

Connect the phone via USB cable. Fron tthe phones menu, choose USB "Phone mode." Click "Manually Connect" button in FrontlineSMS and enter the following settings:

  • Port: Com 14 (the port depends on your phone, USB usage, and other software.)
  • Baud rate: 115200
  • Handler: SonyEriccson_W550i (dependent upon your particular phone)

After clicking Connect, you may see a "PortinUse" exception for COM14. Close the "SonyEricsson PC companion" in this case; it is probably using that port. After a few moments the phone should be listed in the "Working Devices" pane in FrontlineSMS.

Screenshot of a connected phone in FrontlineSMS

Passing data to ODK Aggregate by using Keyword processing.

Configure php script

Data from the SMS' will be processed by FrontlineSMS by a php script. You must have Apache and php installed, php in the system path, and PEAR setup. Use "pear install" to install support for XML Serializer and Log. Run the following commands:

  • pear install Log
  • pear install XML_Serializer - may need to run pear install XML_Serializer-beta

The script uses libcurl to send the data, in XML format, to the ODK Aggregate instance. Since you will be executing the php script using the php.exe command, the php script may be located anywhere on the hard drive.

Download sample php script, zipped. This sample supports sending data to two forms. You will need to customise the server URL and form field names.

Configure Frontline SMS External command

Click on the "Keywords" tab in FrontlineSMS and click the "None" keyword. This keyword routes all messages sent to the phone. Right-click in the Keyword Actions pane, select "Add action" and then "External Command."  Enter the following fields:

  • Execution Type: Command Line Execution
  • Command: Path to the script.
  • Message: Message: ${command_response}
  • Send an Auto Reply: Checked

Screenshot of configuring a FrontlineSMS External Command

Click "Done" to save the new External command.

Screenshot of Keyword manager with an External Command

Adding Contacts

In te contacts tab, click "New Contact" and enter the name and phone number of the mobile phones submitting data via SMS.


If you click the Home tab in FrontlineSMS, you should see that you are now ready to receive SMS'. Each event will be listed in the "Latest Events" pane. You can view details of message processing in the "Messages" pane.

Screenshot of Messages listing