Welcome to the 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:
- Dynamically add SMS capabilities to a running instance of Lutris EAS
- Send SMS messages from within applications or services, such as the Lutris EAS Scheduler Service.
- Support for third-party SMS service providers
- "Send" messages to the log file for testing purposes.
- Send Lutris EAS log messages to SMS enabled devices.
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
- Getting Started
- Testing Using the SMSSampleClient
- Sending SMS Messages
- Using an SMS Service Provider
- Creating an SMS Provider Plug-in
- Lutris EAS Logging with SMS
- Using the SMS Service with the Scheduler Service
- Future Enhancements
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)
- Deploy the SMS Service (
<sms_root>\services\SMSService.jar
).- Deploy the SMS sample client (
<sms_root>\examples\SMSSampleClient\SMSSampleClient.war
).- Use the SMS sample client to send messages
- View results (by default) in the Lutris EAS log file (
<eas_root>\logs\ems.log
)- 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.
- Access the sample client from a browser (default location: http://localhost:8002/SMSSampleClient/Main.html)
- Type in a message and hit "send".
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:
- UNIX: "tail -f" on the <eas_root>\logs\ems.log file (before sending the message).
- Windows: open the <eas_root>\logs\ ems.log file in an editor (after sending the message).
- Lutris Management Console: from the menu, select
Server|Display Log|localhost:1099.
Sending SMS Messages
SMS messages can be easily sent from applications and services using the following steps:
- Look up the SMS service via JNDI:
SMSService service = (SMSService) new InitialContext().lookup("ems:/Services/SMSService/manager");
- Send the message:
SMSStatus stat = service.send("<recipient phone number>", "<messsage to send>");
- 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 theSMSService.jar
file:
- Extract the
enhydra-service.xml
file from the<sms_root>\services\SMSService.jar
file.- 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"/>
-->- Comment-out the no-op plug-in, and un-comment-out the NovelSoft plugin.
- Change USERNAME and PASSWORD to appropriate values for the just created account.
- 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"/>- Add the updated
enhydra-services.xml
file to theSMSService.jar
file, ensuring that it is added in theMETA-INF
directory of theSMSService.jar
file.- Undeploy / redeploy the SMSService from Lutris EAS.
- 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 theSMSService.jar
file, and theenhydra-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:
- Access the sample client from a browser (default location: http://localhost:8002/SMSSampleClient/Main.html)
- Type in a message and hit "log".
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:
- Send log messages to the DEBUG9 log level and/or the SMS channel.
or
- Edit
enhydra-service.xml
insideSMSLogPipeline.jar
and change the log level and/or channel name to match existing log message. Set either the log level or channel name (but not both) to "" to accept anything. (but be careful with how many SMS messages are sent!)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 methodsend()
orsend(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.)
- Provide a UI to change the plug-in class and configure properties (for example, phone numbers, username and password).
- Ability to receive SMS messages (depends on how service providers decide to implement this).
- 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!!!!
- Handle multiple to: phone numbers in a comma separated list.
- 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.
- Have a version of send that takes an array/container of addresses to send to, for bulk SMSing.
- Add logging - save a copy of the last N messages. Allow for MBean inspection.
- Provide more pre-defined SMS provider plug-ins.
- Expose an MBean enumeration (popup menu) of plug-in class names. List all known classes.
- 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.
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
The Lutris EAS SMS Service requires Lutris EAS 4.0.1 (development, deployment, or trial version) or the Lutris EAS "Rabbit" Technology Preview 1 to be pre-installed on your system and has been tested to work on Windows 2000, Solaris, and Linux machines.
Installation
Refer to the doc/install.txt file for installation instructions.
How to undeploy
From the command line:
undeploy SMSService
From the Lutris Management Console (LMC):
- Select the
Deployer Tab
- Expand the entry for the desired server
- Select
Services
- Select
SMSService
- From the menu, select
Tools|Deployer|Undeploy Object
This section summarizes common issues with this release and any available workarounds.
Issue Workaround I don't see anything in the EAS output when I send messages. Logging messages at the level used by the SMS service are not being sent to STDOUT, but are going to the file ems.log. Do a "tail -f" or just edit the file to see the output. The SMS Service is not displayed in LMC under By Type|Services
.On some systems, one needs to refresh the MBeans ( Server|Refresh
) in order for the service MBean to be displayed.The SMSSampleClient is not available after I restart the server. For this release, the SMSSampleClient needs to be manually started after a server restart. The quickest way to do this is to use the Web Admin Console (http://localhost:8001/, username: admin, password: enhydra) Select 'SMSSampleClient' from the list of applications, and then select 'Start'
We encourage you to submit feedback/bugs and ask questions concerning your experience with the Lutris EAS product and documentation. You can post questions and participate in the Lutris EAS Beta email Forum by sending email to the lutriseas@eas.lutris.com mailing list. You can browse the Lutris EAS Beta email Forum at http://www.lutris.com/lutrisEASmail/lutriseas/maillist.html.
Note: You must first subscribe to the mailing list before posting. To subscribe, send email to mailto:majordomo@eas.lutris.com?subject=subscribe&body=subscribe lutriseas with '
subscribe lutriseas'
in the body of the email message (automatically added if you click the preceding mailto link).If you believe that you have encountered a defect in the product, please follow these guidelines:
- Before posting your problem report, please review the Known problems and workarounds section in the Release Notes and mailing list archives to see if your problem has already been reported along with a solution or workaround.
- Submit your bug report to lutriseas@eas.lutris.com. Please include your operating system and JDK versions as well as detailed steps necessary to reproduce the problem.
Note: Bug reports that cannot be reproduced by Lutris will not be reviewed by Lutris Engineering.
Copyright © 2001 by Lutris Technologies Inc. All rights reserved.