The SMS service currently supports outgoing SMS messages. Support for incoming messages is implemented in the service. The first tool integration for incoming messages is with the Q&A tool (http://confluence.sakaiproject.org/confluence/display/QNA), in the tag https://source.sakaiproject.org/contrib/qna/tags/qna-1.2/
- SMPP service provider: the Sakai SMS service uses the SMPP protocol for communicating with an SMS gateway. You therefore need a bulk SMS provider which supports SMPP. A list of some SMPP providers is here: http://www.activexperts.com/xmstoolkit/smpplist/. The Sakai SMS service has been tested with http://www.clickatell.com
- Sakai 2.6.0, 2-6-x or later: the build files (poms) in the SMS project are written for use with Sakai 2.6 or later.
Building the SMS service
Check out the code from svn in the root of your Sakai source tree using trunk for Sakai 2.8 (or use sms-1.0-UCT branch for Sakai 2.9):
or if you use an .externals file, add it to your .externals as:
If you are building against something other than Sakai 2.8 or 2.9 trunk, you can adjust the version in the <parent> block in the top-level pom.xml file, e.g.
Note that the SMS Service uses user profiles as the source of a user's mobile number. To build SMS successfully therefore, your build also needs to contain the profile project (2-6-x) or common (trunk). This is all standard in Sakai 2.8 or 2.9.
SMS also requires entitybroker 2-6-x branch from r64576 or later (see http://jira.sakaiproject.org/browse/SAK-16666). This is all standard in Sakai 2.8 or 2.9.
Configuring the service
Add these 5 properties to your sakai.properties file (or another properties file read on startup, e.g. security.properties):
sms.SMSCAddress and sms.SMSCPort are the IP address and port of your provider's SMPP gateway. sms.SMSCUserName and sms.SMSCPassword are the login details for your SMPP account with your provider. sms.systemType may be required for your provider. For Clickatell, this is the API ID.
These configuration parameters are optional:
On a cluster, sms.BindThisNode (default = true) can be used to control whether the application server connects to the SMPP gateway. Application servers that do not connect to a gateway will queue outgoing messages for another server to handle. At least one server in the cluster must connect to an SMPP gateway to handle outgoing messages.
sms.sendingDelay (default = 500ms) is the interval in milliseconds (ms) between sending outgoing messages. Set this to 0 or a low value on fast connections or when testing with a simulator. Set it to a higher value if the connection is slow or the SMPP gateway has known throughput limits.
sms.notify.email (default = false) enables email notifications when a task is complete to the task owner and account owner email notification address.
sms.usertypes.allow if set will restrict SMS recipients to users whose accounts are of the listed types. Users with other account types will not appear as possible recipients in the SMS Messages tool.
The sms.number settings are used when converting local mobile numbers to a normalized international form. sms.number.intprefix is the prefix used when dialling international numbers. sms.number.localprefix is the number used to prefix mobile or long-distance numbers. sms.number.countrycode is the local country's international country code (e.g. 27 for South Africa). For examples of how numbers are normalized to international form, see MobileNumberHelperTest.
Here are settings for different countries:
USA and Canada
The service currently assumes that the SMPP gateway will only deliver messages to local (same country) numbers. This assumption can be changed in NumberRoutingHelperImpl (see isNumberRoutable).
Further configuration items are contained in sms/impl/src/resources/smpp.properties. These may need to be adjusted for the SMPP gateway in use. The defaults work correctly with Clickatell.
To test the SMS tool you can use SMPPSim
SMS has two tools, "SMS Messages" (sakai.sms.user) which allows users to send SMS messages in a site, and "SMS Admin" (sakai.sms.admin). The SMS Admin tool is only for use by admin-equivalent users. You can prevent SMS Admin and optionally the SMS Messages tool from appearing as a selectable tool in Site Info / Worksite Setup by adding entries to hiddenTools in sakai.properties, e.g.
When you start up Sakai, the SMS service will attempt to connect (bind) to the SMS gateway. If this is successful, you will see log entries like this in catalina.out:
There is only one SMS permission, viz. sms.send. This permission grants the ability to send SMS messages within a site (dependent on available credits in the SMS account associated with the site).
Add the sms.send permission to applicable roles in the template realms, e.g. Instructor role in !site.template.course, through the Admin Realms editor.
Create an account in a test site
Accounts within the SMS service are intended to enable a prepaid model for allocating SMS credits to a site. Users will be able to send messages in a site as long as the account has a positive balance (or has not exceeded the configured overdraft). Accounts are debited with an estimated number of credits when messages are sent out, and then adjusted based on the actual delivery reports for each message, so the internal accounting is accurate and should match the credit usage figures from your SMS provider.
Login as an admin-equivalent user. Add the SMS Admin and SMS Messages tool to a test site.
In the SMS Admin tool, click on Accounts and New Account. Enter a descriptive account name (e.g. "sms testing"). In the Notification email field, you can enter an email address to receive notifications when SMS messages are sent within the site (e.g. the email address associated with the account, or the site owner), if enabled in sakai.properties (see above).
There is a one-to-one association between sites and SMS accounts.
Send a test message
In the SMS Messages tool, click on Send a new SMS. You can then select recipients by role, group, user or enter mobile numbers directly. When selecting roles, groups or users, the service consults the user's profile to get the user's mobile number.
When you finish sending the message, it will appear as a task in the SMS Messages tool. The tool will show the current status of the task, and the delivery status for each recipient once the gateway has provided that information.
Using the SMS service from an external client
The "SMS Task" interface is exposed through a REST webservice, at the URL path /direct/sms-task/. For examples of how to submit a task using an external application, see the examples directory in svn: https://source.sakaiproject.org/contrib/sms/sms/trunk/examples
Bugs and feature requests
Please file these in the JIRA project for "SMS Contrib": http://jira.sakaiproject.org/jira/browse/SMS