Lutris EAS SMS Service Technology Preview

The Lutris EAS SMS Service is a hot deployable platform service that adds Short Message Service (SMS) capabilities to Lutris EAS. The SMS Service adds the following capabilities to Lutris EAS:

Note: As with all field test software, the SMS Service Technology Preview is not production quality. It's licensed for field test use only and it shouldn't be used in a production environment.

Lutris SMS Service Overview

This distribution contains three key components: the SMS Service itself, the SMSSampleClient example application, and a Lutris EAS logging pipeline.

The SMS Service gives Lutris EAS the ability to send messages via SMS (mt-sms) through 3rd party SMS service providers. The service contains default phone numbers, so clients may either use the SMS service to send messages directly to a known user or to the configured default recipient. The latter case could be used, for example, by a system administrator who wants all such messages to go to her cell phone. Simply by changing the default number, someone else gets the messages without having to change the sending applications.

The SMS Service uses a plug-in architecture to support multiple SMS service providers and currently includes two plug-ins: one for use with NovelSoft (http://www.novelsoft.ch/), and a "no-op" plug-in (default) that writes messages to the Lutris EAS log file (good for testing). 

The SMSSampleClient is an example Web application that can be used to manually send messages. It is provided for testing and as example code for developers who wish to use the SMS service.

The optional logging pipeline forwards selected logging messages to the SMS service (using the default SMS recipient). The log level (debug, warning, emergency etc...) and/or the log channel name may be specified. The default log level is DEBUG9 and the default channel is "SMS". SMS messages have a limited length, so if the log message is too long it is split up and sent as multiple messages. SMS messages may arrive out of order, so the logger prepends a message # to keep things straight.

Each of the 3 pieces may be deployed independently using the deploy tool, the Lutris Management Console (LMC), or by copying to the deploy directory.

Getting Started

 To install and use the SMS Service: (more detailed information is available in the doc/install.txt file)

  1. Deploy the SMS Service (<sms_root>\services\SMSService.jar). 
  2. Deploy the SMS sample client (<sms_root>\examples\SMSSampleClient\SMSSampleClient.war).
  3. Use the SMS sample client to send messages
  4. View results (by default) in the Lutris EAS log file (<eas_root>\logs\ems.log)
  5. Optionally deploy the logging pipeline (<sms_root>\logging\SMSLogPipeline.jar). This sends selected log messages through the SMS service, which can also be tested from the SMS sample client.

The Lutris EAS SMS service performs no actions on its own - it provides methods for applications to call. the SMS sample client is provided as a simple test case in addition to providing sample code.

Testing Using the SMSSampleClient

You can use the SMS sample client to send messages. This lets you test the SMS service, or use it to send live messages. It's mission in life is testing and being sample code to show developers how to connect to and use the SMS service.

By default, the no-op plug-in is used, which writes messages to the Lutris EAS log file without actually sending them via SMS. It is meant for debugging and development use: create and test an application using it and then switch to a real SMS service provider without making any source code changes.

To view the results in the Lutris EAS log file:

Sending SMS Messages

SMS messages can be easily sent from applications and services using the following steps: 

  1. Look up the SMS service via JNDI:

    SMSService service = (SMSService) new InitialContext().lookup("ems:/Services/SMSService/manager");

  2. Send the message:

    SMSStatus stat = service.send("<recipient phone number>", "<messsage to send>");

  3. Respond appropriately to the returned status information.

More robust sample code with error checking can be found within the sendSMS() method in the  <sms_root>\examples\SMSSampleClient\com\lutris\service\smsService\sampleClient\presentation\SendServlet.java file.

Using an SMS Service Provider

The easiest way to send live SMS messages is to create an account with NovelSoft (file:///F:/lutris-eas4/lutris-sms-service/doc/www.novelsoft.ch). An account can be opened for $20.00 that provides 200 messages, $0.10 for each additional message.  

Once an account has been created with NovelSoft, the SMS Service needs to be configured to use the NovelSoft plug. In this technology preview, this is done by editing the enhydra-service.xml file inside of the SMSService.jar file: 

  1. Extract the enhydra-service.xml file from the <sms_root>\services\SMSService.jar file. 
  2. Search for the following lines inside the enhydra-service.xml file:

    <!-- USE THIS PLUGIN FOR TESTING -->
    <property name="pluginClass" type="java.lang.String" value="com.lutris.service.smsService.noop.NoopPlugin"/>
    <!-- USE THIS PLUGIN TO SEND VIA WWW.NOVELSOFT.CH (CREATE AN ACCOUNT FIRST)
    <property name="pluginClass" type="java.lang.String"
    value="com.lutris.service.smsService.novelsoft.HttpSend"/>
    <property name="username" type="java.lang.String" value="USERNAME"/>
    <property name="password" type="java.lang.String" value="PASSWORD"/>
    -->
  3. Comment-out the no-op plug-in, and un-comment-out the NovelSoft plugin.
  4. Change USERNAME and PASSWORD to appropriate values for the just created account.
  5. Change the 'defaultSender' and 'defaultRecipient' properties to a phone # with SMS support. Resulting XML should look like the following (with user specific settings changed):
    <!-- REQUIRED KEYS -->
    <property name="defaultSender" type="java.lang.String" value="senderPhoneNumber"/>
    <property name="defaultRecipient" type="java.lang.String" value="recipientPhoneNumber"/>
    <property name="defaultMessage" type="java.lang.String" value="SMS Test Message"/>
    <!-- USE THIS PLUGIN FOR TESTING
    <property name="pluginClass" type="java.lang.String" value="com.lutris.service.smsService.noop.NoopPlugin"/>-- >
    <!-- USE THIS PLUGIN TO SEND VIA WWW.NOVELSOFT.CH (CREATE AN ACCOUNT FIRST) -->

    <property name="pluginClass" type="java.lang.String"
    value=
    "com.lutris.service.smsService.novelsoft.HttpSend"/>
    <property name="username" type="java.lang.String" value="USERNAME"/>
    <property name="password" type="java.lang.String" value="PASSWORD"/>
  6. Add the updated enhydra-services.xml file to the SMSService.jar file, ensuring that it is added in the META-INF directory of the SMSService.jar file.
  7. Undeploy / redeploy the SMSService from Lutris EAS.
  8. Use the SMSSampleClient to send a test message.

Creating an SMS Provider Plug-in

New SMS provider plug-in classes can be created and specified within the SMS Service config file to connect the SMS service to different SMS providers.  

The SMS provide plug-in class must implement the interface com.lutris.service.smsService.SMSPlugin, whose source code and documentation is provided at <sms_root>\src\com\lutris\service\smsService\SMSPlugin.java. For this release, the class has to be added to the SMSService.jar file, and the enhydra-service.xml file needs to be modified as described above.

Lutris EAS Logging with SMS

The Lutris EAS SMS Service can be tied into the Lutris EAS logging mechanism for sending arbitrary log messages using SMS. To use this capability, the included logging pipeline (<sms_root>\logging\SMSLogPipeline.jar) must be deployed, using one of the deployment options described for deploying the SMS Service itself. Once deployed, the SMSSampleClient can be used to test the logging pipeline:

The message will appear in the Lutris EAS log file (<eas_root>\logs\ems.log). The pipeline is configured by default to only accept messages at the DEBUG9 log level where the channel name is "SMS", with the sample client being the only place where this combination occurs. To use the logging pipeline in applications and services:

The logging pipeline always sends the messages to the default recipient. A system administrator could deploy a second instance of the SMS service with her cell phone set as the default, and set the logging pipeline to use that instance, with the log level set to "EMERGENCY", and the channel name "" (for example).

Using the SMS Service with the Scheduler Service

The SMS Service can also be used in conjunction with the Lutris EAS Scheduler Service Technology Preview to automatically send messages via SMS on a defined schedule. 

To send messages via SMS from a scheduled task, add a new job to the Scheduler Service where the task is a JNDI lookup of "ems:/Services/SMSService/manager", then either call the method send() or send(messageString). The default configuration for the SMS service is to log the messages, so you should see the scheduler service logging that it is about to fire off the task, then the SMS service logging the actual message.

Future Enhancements

Potential future enhancements for the SMS Service: (Please provide feedback on which are most important for you.)

  1. Provide a UI to change the plug-in class and configure properties (for example, phone numbers, username and password). 
  2. Ability to receive SMS messages (depends on how service providers decide to implement this).
  3. Asych receipt tracking Send(msec): send and wait at most N msec for a verification that the message made it to the phone. Returns an ID Object. Have a getStatus(Object) method to let the clients check in later to see if the SMS finally made it. Note: Most US carriers do not support this, so until they do it's not worth it. Most US carriers don't even support specifying a "from" phone number!!!!
  4. Handle multiple to: phone numbers in a comma separated list. 
  5. Make a new version of the current send that waits at most N msec and might return an incomplete/unknown status. When N is zero you get always non-blocking for fire-and-forget uses.
  6. Have a version of send that takes an array/container of addresses to send to, for bulk SMSing. 
  7. Add logging - save a copy of the last N messages. Allow for MBean inspection. 
  8. Provide more pre-defined SMS provider plug-ins.
  9. Expose an MBean enumeration (popup menu) of plug-in class names. List all known classes.
  10. Complete the to/from/message input validation methods. Need to check on what the standards really are. The max length, for example, depends on the carrier and varies from 80 - 200 chars. 160 is a good average. Maybe these methods should be removed, if they provide a false sense of security. Can always allow the service provider to do validation at send time.

Back to Top

Focus Areas

We are especially interested in these areas for your feedback:
  • How you are or would like to use the SMS Service
  • Functionality of existing capabilities
  • What SMS service provider (if any) are you currently using? What interfaces/APIs to they expose to let you send messages?
  • Favorite items from the 'Future Enhancements' section
  • General comments and suggestions

 


Copyright © 2001 by Lutris Technologies Inc. All rights reserved.