Mobile SMS Services
手机短信系统服务
The SAP Hybris Commerce offers integrated SMS functionality. This feature allows you to set up an additional channel for interaction with your customers.
The SMS functionality is built on top of the high performance and resilient Action Framework. The SMS services provide a trouble-free performance and easy integration with custom business logic.
The Hybris mobileservices extension contains components responsible for sending and receiving SMS messages to the SAP Hybris Commerce, sending SMS to customers, and responding to the SMS messages received from customers.
It consists of:
- A server side module for sending, receiving, and processing SMS messages.
- A UI integrated inside the Backoffice Administration Cockpit, which can be used to configure the SMS use cases of your organization.
Definitions
| Name |
Description |
|---|---|
| Action Framework |
A Hybris technology for executing Spring beans with run-time parameters and database driven configuration. Spring beans must implement the ActionPerformable interface and model configuration must extend AbstractAction. |
| One-way message |
A message sent by hybris system. The triggering of the message is not initiated by the reception of a SMS. It is triggered by system according to settings. |
| Process Engine |
A Hybris technology that allows the asynchronous execution of distributed code in the hybris cluster. It supports event triggering, scheduling, error recovery and tolerance. The SMS services are built on top of this technology. |
| SMS |
A mobile short text message. |
| Strategy Pattern |
The ability to select a specialized strategy object for a particular task in run time . |
| Two-way message |
A message sent by hybris system as a response to a received SMS. |
| WAP |
Wireless Application Protocol. A technology framework for mobile pages. |
| WAP Markup |
Markup language for mobile devices. More common are WML or XHTML MP. |
| WAP Push |
A technology to send a link to a phone supporting WAP. |
| WML |
WAP 1.x markup language |
| XHTML MP |
WAP 2.x markup language |
Overview of the Server Side Module
Server-side SMS components use two Hybris technologies:
- Process engine: Allows the SMS code to be spread on the Hybris cluster, takes care of failures and retrial in case of error, and supports the scheduled execution of program retries or deliveries.
- Action framework: Is a standard Hybris way to plug user generated-components into the system.
SMS Services have built-in load management. For more information on load management within a Hybris system, see the Description of Load Management section Mobile SMS Services Configuration document.
Advanced knowledge of the Action Framework is mandatory to personalize shipped services or build new ones. Developers of SMS services are not required to know how the process engine works, but it is highly recommeneded that they do. You can find several examples of SMS actions provided in this document.
See also:
One-Way and Two-Way Messaging
The SMS services functionality supports one-way and two-way messaging.
One-way messaging is triggered by the Hybris system. You can use it to send all kinds of information such as promotions, content, and so on, to the customer without the customer triggering it. One-way messaging uses short codes and defined aggregators.
Two-way messaging is produced as a response to a received SMS. Typically, the system receives a message and processes it. A response is created and sent to the customer. Two-way messaging uses aggregators, short codes, actions, and assignments (binding of an action to a short code using a keyword).
Standard Messaging and Link Messaging
SAP Hybris Commerce supports plain text messages or WAP Push indicators. WAP Push messages are a standard way of sending links to WAP pages that work only in GSM-based networks. Although all devices that support WAP 1.x or 2.0 should accept these messages, in practice some devices and manufacturers don't support it., such as the Apple iPhone mobile phone.
In such cases, you can disable WAP Push by configuration to stop sending WAP Push messages from the system. When disabled, all WAP Push messages are converted to plain text messages, the resulting textis a combination of the WAP Push subject and payload URL. This behavior is controlled by the mobile.wappush.enabled parameter, which is disabled by default .
Validation
Every phone number that enters the system, either using the external aggregator or the Backoffice Administration Cockpit, is validated for correctness against a database of valid phone number formats per country. Phone numbers which are not valid, for example, lacking a digit, and so on are rejected by the system on input.
SMS Life Cycle
There are two connecting points between SMS services and the external world: incoming gateways and outgoing gateways. The life cycle of a message varies depending if it is one-way or two-way messaging.
Figure: SMS Services Methods
Incoming Gateways
Incoming gateways are input sources that inject SMS into the system and typically use the IncomingSMSMessageGateway interface or use the DefaultIncomingSMSMessageGateway bean.
Outgoing Gateways
Outgoing gateways send messages to the aggregators or external systems. They must implement the SMSEngine interface.
Two-Way Messaging Life Cycle
Two-way messaging is an asynchronous activity that takes place in three steps. Each step is executed asynchronously and can take place anywhere in the Hybris cluster. The steps involved are: message reception, processing, and delivery.
Figure: Methods used to send and receive two-way messages.
Message Reception
Message reception means that the message injected by the incoming gateway is received by the system. The system looks up the dictionary of the available keywords, settings, and actions for the short code the message is using and identifies the optimal routing strategy. That means, it decides which action is going to be executed in the processing step and which engine is going to be used in the delivery step.
The DefaultMessageScheduler initiates the message reception. This class queues messages for reception or sending and delegates them to the Receive task, which is executed asynchronously.
The Receive task uses the DefaultIncomingMessageProcessor to route the message based on its keyword and properties. Routing takes place in the IncomingMessageRoutingStrategy, which follows the strategy design pattern. You can replace it for your own customized routing strategy.
Finally, the incoming message processor delegates the action that generates the response, and triggers the processing step, to the action framework to execute. The action that is matched by the previous process gets all the message information, the original phone number, message, keyword, and so on. The action uses the information to determine how to proceed with the message.
Message Processing
Message processing means that an action is executed. Once the action to execute is identified (as described in the previous section), the next step consists of executing the code that generates the response to the customer, that is, executing the hybris action. Actions are JavaBeans that can use the TextService API to signal a response to the incoming data, but that do not modify or alter the message object in any way.
When invoking the TextService to generate a response, the system queues the response to be executed by the SendTask task. It triggers the third asynchronous step.
Message Delivery
The message scheduler bean initiates message delivery. Message delivery is responsible for performing additional final validation on the message. The phone number is validated. Then an output route is chosen by the outgoing message routing strategy. The blocking lists are verified to ensure the destination number is not blocked on the short code. Next, the message is converted, if necessary, from WAP Push to plain text and finally passed to the SMSEngine registry which identifies the engine responsible for sending based on the aggregator engineId.
The SMSEngine is the one responsible for connecting to the external system, sending the messages using the appropriate protocol and taking care of aggregator negotiation and error detection.
Figure: Methods behind delivery of a message.
One-Way Messaging Life Cycle
For one-way messaging the message is injected into the system either through the textService.sendMessage or textService.sendLink. In each case, there is only one asynchronous execution step, the message delivery step, which is identical to the two-way scenario.
The other possibility is that the message is sent as a result of executing any of the one-way actions defined, which you can potentially execute asynchronously, and generate a call to textService.sendMessage or textService.sendLink. In this case, there are two steps: a processing step and a delivery step.
The delivery step is identical to a two-way message delivery. The message processing is also similar but there's one important difference: When processing actions in a two-way scenario, a response is generated by calling textService.replyWithX. When processing actions in a one-way scenario, a response is generated by a standalone message using textService.sendX.
There is nothing in the system that prevents a gateway from operating as receiving and sending gateway. This is the case of the SMPP gateway.
Both type of gateways use the engineId concept. Each gateway, incoming or outgoing, is identified by a string that is used both for tracing where the message was injected into the system and to decide which implementation the aggregator uses.An EngineId is declared as an enumerated type in the mobileservices-items.xml file.
...
<enumtype code="EnginesType" autocreate="true" generate="true" dynamic="true"> <value code="smppEngine" /> <value code="mBloxSmppEngine" /> <value code="bulkSMSEngine" /> <!-- other engines to be included here --> < ... > </enumtype> ...
Gateways use input/output DTOs to encapsulate and hide the message model to the gateway implementations.
SMS Data Model
The central piece of the data model is the structure representing the message. The MessageContextModel exists for this task. It stores the contents of the message, information when it was sent, and which particular route was used for later use.
Figure: SMS services data model.
The MessageContextModel serves as a state record for each message. It is used to coordinate SMS execution through the SMS life cycle.
The model consists mainly of the representations of the concepts of aggregators, short codes, actions, and action assignments.
The aggregator represents an output gateway in the system. It can use any of the system engines. It can receive customized configuration information, such as a login and a password. Instead of being limited to system engines, you can write your own engine according to your needs, or to the needs of the aggregator, the carrier, or the technology used to deliver the messages.
The aggregators contain short codes. A short code is the combination of a country and a phone number. In two-way messaging, short codes are used for routing the message, based on its country and original number. Short codes have a different meaning in one-way messaging. They represent an output route in a given country and the original number is used in the standalone message when possible.
Actions hold configuration information to customize how the messages and responses are produced. They are assigned to the short code using a construction called MobileActionAssigment, which is a combination of an action with a given keyword. PhoneLists is a feature that enriches the model. It is used both for storing subscribers to campaigns and to store which phone numbers should not receive communication from the Hybris Platform.
Keywords can use equality matching ignoring case, or use regular expressions. In the case of regular expressions, the matching text is restricted to one word.
Action Matching Process
The ReceiveAction selects an action to generate a response in two-way messaging based on the MobileActionAssigmentsavailable.
Figure: Organization of action matching process.
Assignment matching looks into each assignment for a particular short code. It tests its keyword matching to check if it is selected by the incoming message.
Other configuration options, such as phone filters, test mode, start and end dates, affect the matching process by preventing an assignment from being used if the appropriate values are not found.
If the system cannot find a match to the short code in the message,a defaultAction on the short code is executed. This action typically generates a text message in the form Sorry, your message could not be understood to ensure that the customer always receives a reply even if the requested action does not exist.
Message State Transition
SMPP mBlox implementation uses the additional state VERIFYING. Whenever the mBlox delivers the message, it reschedules the message after the retry timeout (configurable in aggregator) seconds. If the confirmation of delivery is received at any time, the state is set to SENT and the retry message not sent.
Figure: States of message transition.
The state is used for the SMPP message retry. VERYFYING works like SCHEDULED, but a VERIFYING message sees incremented its number of errors every time the message is sent. After the maximum number of attempts (configurable in aggregator) is reached, the message is DISCARDED. If the message is verified to be sent, the state is set to the final value SENT, and no more retries take place.
mobileservices Extension APIs
The SMS services are made up of a number of classes and APIs. The ones that are relevant for the technical user are explained in this section.
TextService
The TextService is responsible for sending replies to customers. It is the service the hybris actions use to send replies. The TextService has the following methods:
| Method |
Description |
|---|---|
| discard | While processing an incoming message, this method allows marking the message as discarded. It further allows optionally to specify an error type, a message, or causing exception to be specified. Such a message is considered as processed abnormally. Therefore the mobile framework may keep such messages for reporting reasons. Because message processing is done by custom AbstractActionModel actions, it is recommended that implementors signal the end of processing by calling either #done or #discard in case no reply is being triggered. |
| done |
While processing an incoming message, this method allows marking the message as done. Such a message is considered as processed without an error. The mobile framework is allowed to either delete or archive it from now. Since message processing is done by custom AbstractActionModel actions, it is recommended that implementors signal the end of processing by calling either #done or #discard in case no reply is being triggered. |
| getAvailableShortcodesForSending |
Locates all short codes for the specified country which support sending outgoing messages. NoteThe OutgoingMessageRoutingStrategy specifies the final routing decision. The OutgoingMessageRoutingStrategy is set up in the mobile Spring configuration. This method simply lists all potential ones. |
| getExclusiveShortCode |
Looks up an exclusive short code using its unique code. |
| getSharedShortCode |
Looks up a shared short code by a specified code and keywords. |
| replyWithLink |
While processing an incoming message, this methods allows sending a reply link message using the incoming message information. The specified MobileShortcodeModel is used to send the message on behalf. Reply messages are not sent immediately but are queued. Therefore the returned model shows intermediate states. Use the MessageHelper#blockUntilProcessed if you must wait until sending is done. |
| replyWithMessage |
While processing an incoming message, this method allows sending a reply text message using the incoming message information. The specified MobileShortcodeModel is used to determine the origin number. Reply messages are not sent immediately but are queued. Therefore the returned model shows intermediate states. Use trhe MessageHelper#blockUntilProcessed if you must wait until sending is done. |
| sendLink |
Sends a WAP Push message to the specified number. The specified MobileShortcodeModel is used to determine the origin number. Messages are not sent immediately but are queued. Therefore the returned model shows intermediate states. |
| sendMessage |
Sends a text SMS message to the specified number. The specified MobileShortcodeModel is used to obtain the origin number of the message. Messages are not sent immediately but are queued. Therefore the returned model shows intermediate states. Use the MessageHelper#blockUntilProcessed if you must wait until sending is done. |
Extending the SMS Service
The SMS service is extensible. There are two main points of interface to customize its behavior (in addition to configuration using configuration files and database model):
- Defining new input/output gateways
- Creating actions to respond to incoming messages
Creating an SMS Receiving Gateway
Any input source of incoming messages must implement the IncomingSMSMessageGateway interface . This interface consists of a messageReceived method, which is invoked each time a message is received. The incoming gateway uses the engineId parameter to detrmine which gateway among the available gateways is responsible for the injection of the message.
The message parameter, an instance of the IncomingSMSMessageDTO class, contains the data of the message to be injected. The messageId and the rawMessageDetails are fields in the DTO. The messageId is used to uniquely dentify the message in the original system; it is typically provided by the aggregator.
Most often, incoming messages are received over an HTTP connection. Then, the gateway must reside inside a web application, either using a plain servlet or a more advanced artifact, such as a Spring controller.
The SMS incoming gateway needs to construct a DTO-based on the request parameters. It calls the provided default messageGateway using the appropriate engineId.
Both the engineId and the message gateway are referenced using a Spring IOC. The engine implementation is a reference to the class DefaultIncomingSMSMessageGateway provided, with the incomingSMSMessageGateway Spring ID. You can set any chosen value to the engineId using Spring. This value is later referenced in the aggregator model.
If a new engineId needs to be defined, it also must be added to the EnginesType enumeration, which contains the list of engineIds for your system.
Creating a New SMS Output Gateway
An SMS output gateway is a Java class that implements the connection to the aggregator for sending messages.
First, you have to create an action for processing the SMSEngine interface. This interface contains methods for sending messages, as well as managing the engine life cycle.
The engine life cycle is controlled by the startup and shutdown methods, which are called at system initialization and shutdown. The engines are expected to be able to reload their configuration at run time. This is accomplished by implementing the updateAggregators method.
The information for starting up or updating the configuration is held in a DTO, whose source is the database model. The aggregators hold database stored configuration information as a map of key-value pairs assigned to each aggregator.
To define a user-generated engine, the user must implement a class implementing the SMSEngine interface and the bean must be named with the desired engineId.
As with incoming messages, if the engineId or bean name is a new value not previously used in the system, it must be declared so that the models and UI can reference it. You can do this by adding the bean name to the EnginesType enumeration in the mobileservices-items.xmlfile. See the One-Way Messaging Life Cycle section above for an example of the file.
The AbstractSMSengine convenient class is provided for your. Any SMSEngine must override thesend method to be able to send messages, and ideally should override the updateAggregators to support live reloading. If your engine needs to perform start up code or shutdown logic, place it in the appropriate methods.
The engines are automatically registered in the SMSEngineRegistry, the system comes with a default registry,DefaultSMSEngineRegistry, that selects the appropriate engine for each delivery based on the engine assigned to each aggregator in the model.
Creating an Action to Process a Message
Actions are the standard hybris way to host user-defined logic. Whenever a model needs to execute business logic that resides in a JavaBean, the name of the bean is referred to an action and the action has execution arguments stored in database as a part of the action model.
In addition to receiving a configuration object, which is a Hybris model, actions also receive a run-time argument, which is arbitrary and can be anything depending on the type of action.
For mobile messages, actions must implement the ActionPerformableMobileMessageContextModel. Hence the action implements the method, where the action is an instance of the action configuration object:
public void performAction(final AbstractActionModel action, final MobileMessageContextModel data)
Typically this is not an AbstractActionModel, but a subclass of it that contains the configuration information that defined the action. And data is a reference to a message being received. The outcome of the action is reaction to the message based on its configuration and generating a response.
Instead of modifying or altering the message object (data), actions are expected to delegate to the TextService for generating the response. The TextService contains several methods for this task, such as replyWithMessage or replyWithLink. The ReplyWithMessage is used whenever a normal text message must be sent back to the user. The ReplyWithLink is used to send a link response. Both methods are overloaded to allow selecting the response short code automatically by using the same short code as the originating message. It also makes it possible to explicitly select one.
If the message needs to be discarded, the TextService has a discard method that allows a message to be dropped unanswered, and which holds error information that can be used later for debugging purposes.
Actions can also decide to perform business code as a response to the message but do not send an answer back to the customer. In this case, instead of signaling a response, the action must call the done method in the TextService to indicate that processing the message is finished and that no response must be generated.
The response is not sent immediately but is queued to be sent as soon as the send task picks up the message and delivers the response to the outgoing engine.
NoteWhen defining new actions configuration, it is important to follow certain guidelines during definition of the configuration model. Follow the action naming nomenclature:
- Use the prefix MobileReceiveAndSend for actions used in two-way messaging.
- Use the prefix MobileSend for actions used in one-way messaging.
Both use the suffix Action.
One-way actions must extend the AbstractMobileSendAction, while two-way actions extend the extendMobileReceiveGenericAction.
All actions should overwrite the target field to provide the action bean name as a default value. This way, whenever a new action is created on the UI, web users don't need to know the bean names in the Spring configuration file.
Creating an Action
Creating an action is a common customization within SAP Hybris Commerce. In the example, an action invokes a web page and responds with a generic text after conclusion. In order to clarify the example, the action is as simple as possible and no error checking is considered.
The action has a model configuration that contains the URL to invoke, as a string, and the text which should be answered back to the customer. No default error response is introduced so that the example is as clear as possible. This example is for training purposes and is not to be used in production systems.
You should define your actions in custom modules. Although you can add your actions to the mobileservices extension,Hybris advises against this as you would have to maintain your code every time your module is updated. In this procedure, you require a custom module and you must add your action to a package named com.company.actions.
When implementing your action, you must extend AbstractMobileActionPerformable as it handles initializing commonly required services such as the TextService.
In this example, a class called MobileReceiveAndSendSampleActionPerformable is created that extends the abstract parent and implements the interface.
public class MobileReceiveAndSendSampleActionPerformable extends AbstractMobileActionPerformable implements ActionPerformable<MobileMessageContextModel> { private static final Logger LOG = Logger.getLogger(MobileReceiveAndSendSampleActionPerformable.class.getName()); @Override public void performAction(final AbstractActionModel action, final MobileMessageContextModel data) { // Do something } }
In the above code excerpt, the MobileMessageContextModel message is passed as a run-time argument. It holds the reference to the message that you are responding to.
You must define the bean in the Spring XML file. You must extend the abstractMobileAction bean to receive the Spring configuration defined for the parent in the mobileservices extension Spring configuration file as follows:
<bean id="mobileReceiveAndSendSampleAction" class="com.company.actions.MobileReceiveAndSendSampleActionPerformable" parent="abstractMobileAction" scope="tenant"> </bean>
You must specify configuration information such as the URL and text used to respond by adding it to the items.xml file, as shown in the following code example:
<itemtype code="MobileReceiveAndSendSampleAction" jaloclass="com.company.jalo.actions.MobileReceiveAndSendSampleAction" extends="MobileReceiveGenericAction" autocreate="true" generate="true"> <attributes> <attribute qualifier="message" type="java.lang.String"> <persistence type="property" /> <modifiers optional="false" /> </attribute> <attribute qualifier="url" type="java.lang.String"> <persistence type="property" /> <modifiers optional="false" /> </attribute> <attribute type="java.lang.string" qualifier="target" redeclare="true"> <persistence type="property" /> <modifiers optional="false" /> <defaultvalue>"mobileReceiveAndSendSampleAction"</defaultvalue> </attribute> </attributes> </itemtype>
The actions extend the MobileReceiveGenericAction. The action target attribute, which stores the bean name, is initialized with a sample value equal to the bean name.
Now that all the pieces are in line, you can complete the original bean to perform the task. Use the TextService to generate the response. This is a two-way action, therefore the textService.replyWithMessage action is used. For a one-way action, you would use the textService.sendMessage.
public class MobileReceiveAndSendSampleActionPerformable extends AbstractMobileActionPerformable implements ActionPerformable<MobileMessageContextModel> { private static final Logger LOG = Logger.getLogger(MobileReceiveAndSendSampleActionPerformable.class.getName()); @Override public void performAction(final AbstractActionModel action, final MobileMessageContextModel data) { final MobileReceiveAndSendSampleActionModel config = (MobileReceiveAndSendSampleActionModel) action; final String url = config.getUrl(); final String message = config.getMessage(); if (getPage(url)) { textService.replyWithMessage(data, message); } else { textService.replyWithMessage(data, "Something went wrong"); } } private boolean getPage(String aUrl) { try { URL url = new URL(aUrl); URLConnection conn = url.openConnection(); BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream())); while (in.readLine() != null) { // do nothing with the output } } catch (Exception x) { //no error control return false; } return true; } }
If you want the action to appear correctly formatted in the Backoffice Administration Cockpit, you must localize the new model and customize its appearance. The following code excerpt shows how to do this in yourextension-locales_en.properties file:
type.mobilereceiveandsendsampleaction.name=Sample Reply Action type.mobilereceiveandsendsampleaction.url.name=Url to invoke type.mobilereceiveandsendsampleaction.message.name=Response
In the Backoffice Administration Cockpit, ensure that your action adds a new section containing your attributes to the SMS tab (defined in mobileservices).
Mobile Testing Interface
Refer to the SMS Configuration Overview section of the Mobile SMS Services Configuration document, for information and an overview diagram on the placement of the testing interface within the system.
The SMPP Test Aggregators in diagram are colored in red, and are external programs that simulate being an aggregator to the Hybris Platform. These elements are used to configure the Hybris system without needing a contract with an aggregator. An example of such a program is SMPPSim. The communication of these test tools with the Hybris suite is done through the SMPP protocol, which is a connection-oriented protocol as explained in the business guide.