Child pages
  • Installing and using the SMS Service
Skip to end of metadata
Go to start of metadata

Capabilities

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/

Requirements

  • 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):

svn co https://source.sakaiproject.org/contrib/sms/sms/trunk/ sms

or if you use an .externals file, add it to your .externals as:

sms   https://source.sakaiproject.org/contrib/sms/sms/trunk

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.

<parent>
   <artifactId>master</artifactId>
   <groupId>org.sakaiproject</group>
   <version>2.10-SNAPSHOT</version>
   <relativePath>../master/pom.xml</relativePath>
</parent>

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=127.0.0.1
sms.SMSCPort=2773
sms.SMSCUserName=username
sms.SMSCPassword=password
sms.systemType=123456789

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:

# Connect to the gateway from this app server
sms.BindThisNode=true

# Delay in milliseconds between sending outgoing messages
sms.sendingDelay=25

# Send email notifications
sms.notify.email=true

# SMS account types allowed to be recipients (c/f SMS-130)
sms.usertypes.allow=student,staff,guest

# Country dialling prefixes for number normalization
sms.number.intprefix=00
sms.number.localprefix=0
sms.number.countrycode=27

# Source address for outgoing messages, required by some providers (no default)
sms.sourceAddress=12345

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:

Country

Int Prefix

Local prefix

Country Code

South Africa

00

0

27

USA and Canada

00

1

1

UK

00

0

44

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.

Testing

To test the SMS tool you can use SMPPSim

Stealth tools

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.

hiddenTools@org.sakaiproject.tool.api.ActiveToolManager=sakai.sms.admin,sakai.sms.user

Startup Sakai

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:

2009-05-21 09:51:57,348  INFO main org.sakaiproject.sms.logic.smpp.impl.SmsSmppImpl - init()
2009-05-21 09:51:57,349  INFO main org.sakaiproject.sms.logic.smpp.impl.SmsSmppImpl - Binding to A.B.C.D on port 2773 with Username dhorwitz
2009-05-21 09:51:59,399  INFO main org.sakaiproject.sms.logic.smpp.impl.SmsSmppImpl - EnquireLinkTimer is set to 60000 miliseconds
2009-05-21 09:51:59,399  INFO main org.sakaiproject.sms.logic.smpp.impl.SmsSmppImpl - TransactionTimer is set to 50000 miliseconds
2009-05-21 09:51:59,401  INFO main org.sakaiproject.sms.logic.smpp.impl.SmsSmppImpl - Bind successful

Set permissions

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

  • No labels