Alex Anderson edited this page May 29, 2012 · 54 revisions

Welcome to the frontlinesms2 wiki!


Workspace Setup


This section is based on a window7 setup experience.

Required softwares

  • JVM JDK 1.6 (32bits)
  • Git
  • Grails (optional if using SpringSource Tool Suite - STS)

The Setup

The team hasn't find the perfect tool yet. So each developer is using different tools.

Gedit Setup

For instructions on how to setup Gedit as your development IDE, follow this link

Option SpringSource Tool Suite - STS

You need to download and install STS (32 or 64 bit). Once it's done, install the additional extension from our dashboard: Grails (current production release), Grails Support and Groovy Eclipse. STS can also be integrate with JIRA task repository. No need to add any dependencies, it's already installed. Just follow those steps (note that the task are under Mylyne view).

Now get the sources from Github and 2 dependencies:

  • frontlinesms2
  • camel-smslib
  • hayescommandset-test

To import this project in STS, the process is not clean due to some files are missing. The current work around is to create a new FrontlineSMS grails project. Then copy past all the file in this folder.


grails run-app
  • "fail maven test": you need to clean the .ivy2 cache in your home directory by deleting everything
  • "Multiple Compilation Errors Exception": the source dependencies are not found.
  • "Assertion Errors": you may use a 64bit JVM. Download and use the 32 bit version.
  • "Loading error while frontlinesms service is starting, the error is a NullPointerException": this error has not been solve yet. issue reported in JIRA. This error is not consistent and will probably disappear next time to start the application.


For more info on testing the application, see:

Source Control

All story and bugfix development should be started on a new branch. Branch name should be the JIRA ticket number which you are working on (e.g. CORE-123). Branches should only be merged with master when the story is complete and all tests pass.

Commit message format [#Jira-number] - Developer name - Description about the work.

master branch

The master branch in the github repository should always build and pass all tests.

Code Style Guide

File encoding

Text files should be saved in UTF-8 format unless there is good reason to use an alternative format.


  • DOM ids in gsp files should be all lowercase with words seperated by dashes: e.g.
<div id="sample-id"/>
  • param references in GSPs should be done using .key notation in preference to ['key'], i.e. <g:if test="${params.messageInstance}"/> is good; <g:if test="${params['messageInstance']}"/> is less good.


Tabs should always be used in preference to spaces when indenting code. This applies to Java, Groovy, JavaScript, HTML, GSP, CSS, XML and others.

SQL Queries

Keywords in SQL and HQL queries should be written in upper-case to allow easy differentiation from Groovy variables, class names and values, e.g.

CustomField.executeQuery("SELECT DISTINCT cf.contact.name FROM CustomField cf JOIN cf.contact $matchingString")



When displaying a list for the first time (e.g. contacts list), ensure the first item in the list is selected if none other is specified.

Continuous integration


sudo su jenkins

/usr/bin/daemon --name=jenkins --inherit --env=JENKINS_HOME=/var/lib/jenkins --output=/var/log/jenkins/jenkins.log --pidfile=/var/run/jenkins/jenkins.pid -- /usr/bin/java -jar /usr/share/jenkins/jenkins.war --webroot=/var/run/jenkins/war --httpPort=8080 --ajp13Port=-1

Firefox display

Firefox display is simulated by Xvfb.

Xvfb -ac :99 //Sets the display to run on port 99

export DISPLAY=:99 //Tells firefox about display.

SMSLib, connected modems, hardware


In BootStrap.groovy there is set up for mock sms modems for SMSLib to access. This is enabled by default when grails.env is test. To enable at other times, set the environment variable serial.mock to true, e.g.

grails -Dserial.mock=true run-app

Installation of FrontlineSMS 2.x

Building the Installer

Need to have Install4J and Maven installed on your computer. This will build installers for Windows and OS X.

  • Download and install install4j. FrontlineSMS has an install4j license which you must enter during installation.
  • Download and install maven 2 and add it to your PATH. Edit the settings.xml (usually in ~/.m2/) to point at your install4j as follows:
  • Download required JRE in install4j - the Windows installer will include a bundled JRE. Open install4j and select 'download JREs'. At the wizard prompt for selection of JREs to download, select windows-x86 1.6.0_30. Close the GUI once this is completed
  • run grails installer build script: $ grails prod BuildInstallers

FrontlineSMS:Radio Plugin

Enabling the Plugin

In BuildConfig.groovy there is a property that determines which FrontlineSMS plugin will be loaded at runtime. To enable the radio plugin set the environment variable radio.plugin to true e.g

$ grails -Dradio.plugin=true run-app


All text throughout the application should be internationalised. Take care to i18n text in:

  • GSP files
  • Javascript (in ``web-app/js` as well as inline in GSPs)
  • controllers
  • SystemNotifications

Rules and Examples

<className>.label : human readable form of the class name
e.g. fmessage.label=Message

<className>.description : description for the user of what a class is for
e.g. announcement.description=Send an announcement message and organise the responses

<className>.<fieldName>.label : human readable form of a field of a class
e.g. fmessage.src.label=From

<className>.list.none : message to display when there are no things to display in a list
e.g. connection.list.none=You have no connections configured

<className>.<action> : for action on a single instance of a class
e.g. fmessage.archive=Archive

<className>.<action>.many : for action on multiple instances of a class
e.g. fmessage.archive.many=Archive All

<className>.tab.label : label for a tab
e.g. fmessage.tab.label=Messages

<className>.<footer|header|other weird place>.<whatever> : label for specialist UI thing which is hard to classify
e.g. fmessage.footer.starred=Starred

<className>.notification.<notificationDescription> : content of a system notification or flash message
e.g. fmessage.notification.sent.success=Message sent successfully