Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.0 Part Number E21362-01 |
|
|
View PDF |
This chapter describes the Parlay X 2.1 Short Messaging/Short Message Peer to Peer (SMPP) communication service in detail.
The Parlay X 2.1 Short Messaging/SMPP communication service exposes the Parlay X 2.1 Short Messaging set of application interfaces.
The communication service acts as an External Short Message Entity (ESME) that connects to a Short Messaging Service Center (SMSC) over TCP/IP.
For the exact version of the standards that the communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Concepts Guide.
Services Gatekeeper provides support for the billing identification identifier, smpp_billing_id, defined in SMPP Specification 5.0, through the use of a tunneled parameter. It also supports the ussd_service_operation, which was added as an optional parameter to the DELIVER_SM operation as a tunneled parameter in SMPP Specification 5.0. See "smpp_billing_id" and "ussd_service_operation" for information about these parameters.
Using a Short Messaging communication service, an application can:
Send short messages to one or many destination addresses. The payload in these short messages can be text, logos, or ringtones
Logos must be in either Smart Messaging or Enhanced Messaging Service (EMS) format. The image is not scaled. Ringtones must be in either Smart Messaging or EMS (iMelody) format.
Request to be notified that delivery receipts for sent short messages have been received from the network.
Receive delivery receipts on sent short messages that have arrived from the network.
Explicitly query Services Gatekeeper for delivery receipts on sent short messages.
Subscribe to be notified if specified short messages for the application have been received from the network.
Receive notifications that specified short messages for the application have arrived from the network. These notifications include the short message payload.
Explicitly poll Services Gatekeeper for short messages sent to the application that have arrived from the network and been stored in Services Gatekeeper.
Requests can flow in two directions: from the application to the network (called application-initiated or mobile-terminated) and from the network to the application (called network-triggered or mobile-originated). Both of these scenarios are covered in the following sections.
After an application has sent a short message to one or more destination addresses, two different types of responses can be returned:
Send receipts are acknowledgements that the network node has received the short message from the application by means of Services Gatekeeper. Although a single short message may be sent to multiple destination addresses, Services Gatekeeper normally returns only one send receipt to the application. The receipt is returned synchronously in the response message to the sendSms operation.
Delivery receipts contain the delivery status of the short message; that is, whether the short message has actually been delivered by the network to the mobile terminal. There is one delivery receipt per destination address, with one of three possible outcomes:
Successful: In the case of concatenated short messages, this is returned only when all the parts have been successfully delivered.
Unsuccessful: The short message could not be delivered before it expired.
Unsupported: Delivery notification for this address is not supported. This can occur if the originating network supports delivery receipts but is unable to acquire the appropriate information for one or more destination addresses. This status is reported for each address for which this is the case.
Because actual delivery of the short message may take several hours, or even days (if, for example, the mobile terminal is turned off at the time the short message is sent), delivery receipts are returned asynchronously. Applications can choose either to have delivery receipts delivered to them automatically by supplying Services Gatekeeper with a callback interface or they can poll Services Gatekeeper.
If the application supplies a callback interface, there are two possible outcomes:
Services Gatekeeper sends the delivery receipt and the application receives and acknowledges it.
Services Gatekeeper sends the delivery receipt but the application does not acknowledge reception. In this case, Services Gatekeeper stores the delivery receipt in a reliable storage. The application can poll Services Gatekeeper for these receipts. Each stored delivery receipt is time stamped and, after a configurable time period, is removed.
If the application chooses not to supply a callback interface, Services Gatekeeper stores the delivery receipt in reliable storage. The application can poll Services Gatekeeper for these receipts. Each stored delivery receipt is time stamped and, after a configurable time period, is removed.
To correlate a sent message with a delivery receipt from the network node, Services Gatekeeper stores the information about the message for a period of time. This information has a life span. If the delivery receipt does not arrive prior to the expiration of the message, a cancel request for the message is sent to the SMSC.
Two types of traffic destined for an application can arrive at Services Gatekeeper from the network. They are:
Delivery receipts for application-initiated sent short messages
Mobile-originated short messages destined for the application
For an application to receive short messages from the network, it must register its interest in these short messages by setting up a subscription in Services Gatekeeper. A subscription, or notification, is defined by a service activation number, which is the destination address to which the mobile sender directs the short message. This is usually a short code.
Additional criteria can be tied to the service activation number, such as the first word of the text in the short message payload. For Services Gatekeeper to accept a message, both the service activation number and the additional criteria must match the details set up in the subscription. Each registered subscription must be unique, and subscription attempts with overlapping criteria are rejected. The application can either poll Services Gatekeeper for received short messages or include a callback interface in setting up the original subscription.
If a short message that matches a subscription arrives at Services Gatekeeper from the network and the original subscription includes a call-back interface, there are two possible results:
Services Gatekeeper sends the short message to the application, and the application receives and acknowledges it. In this case Services Gatekeeper acknowledges the reception of the short message to the network.
Services Gatekeeper sends the short message to the application, but the application does not acknowledge reception. In this case, Services Gatekeeper can store the short message in reliable storage, if offline provisioning has occurred and a registration identifier has been established. In such a case, Services Gatekeeper acknowledges the reception of the short message to the network. If no provisioning has been done, Services Gatekeeper returns an error to the network. The application can poll Services Gatekeeper for any stored short messages. Messages are removed after the polling application has had the chance to consume them. Each stored short message is time stamped and, after a configurable time period, is removed from storage.
If a short message that matches a subscription arrives at Services Gatekeeper, and the original subscription does not include a callback interface, the short message is stored in reliable storage and Services Gatekeeper acknowledges the reception of the short message to the network. The application can poll Services Gatekeeper for any such short messages. Each stored short message is time stamped and, after a configurable time period, is removed.
If a short message arrives at Services Gatekeeper and no matching subscription is found, Services Gatekeeper does not acknowledge reception to the network. It is the responsibility of the network node to handle any further processing of the short message.
The Parlay X 2.1 Short Messaging/SMPP communication service uses the Services Gatekeeper SMPP Server Service to establish and manage southbound connections between Services Gatekeeper and SMSCs. The SMPP Server Service is deployed as an Oracle WebLogic Server service.
See "System Properties for SMPP Server Service" and "Reference: Attributes and Operations for SMPP Server Service" for information about configuration options pertaining to these client connections.
The client connection ID is created on the plug-in's successful bind with the SMSC. The connection ID changes on a successful rebind.
When a client connection is successfully established, the connection is verified periodically by using ENQUIRE_LINK requests (heartbeats). If the ENQUIRE_LINK requests fail a configurable number of times, Services Gatekeeper attempts to reconnect with the SMSC. If the reconnect attempts fail a configurable number of times, the client connection is closed and removed.
The plug-in instance MBean provides the following configurable timers for southbound connections between Services Gatekeeper and SMSCs:
Connection timer: This timer sets the heartbeat interval that Services Gatekeeper uses to request the connection status on the client connection. If the ENQUIRE_LINK requests fail, Services Gatekeeper closes the connection and attempts to reconnect. See "Attribute: EnquireLinkTimerValue" for more information.
Transaction timer: This timer establishes the interval between an SMPP request to the SMSC and the corresponding SMPP response. If the interval is reached, Services Gatekeeper does not resend the request. In this case, Services Gatekeeper removes the transaction information and discards the PDU response. See "Attribute: RequestTimerValue" for more information.
A Parlay X 2.1 Short Messaging/SMPP plug-in can bind to an SMSC as an ESME transmitter/receiver or transceiver. If more than one account in the SMSC is used, create one plug-in instance for each account. If more than one SMSC is used, create a plug-in instance for each account in each of the SMSCs.
If plug-in instances have the same bind type, they can share a connection to the SMSC. If they have different bind types, each must have its own client connection.
Each plug-in instance executes on all network tier servers. Shared storage is used, so network-triggered messages and delivery notifications can be accepted by all network tier servers and match them with all application subscriptions, thus creating a configuration with high availability.
To maximize throughput, the Parlay X 2.1 Short Messaging/SMPP communication service supports windowing on the network-facing interfaces. Windowing provides a way to specify the amount of data that can be transmitted without receiving an acknowledgment.
Windowing for requests to the SMSC is configured in the plug-in.
Requests wait in a windowing queue until they can be submitted. Two attributes apply to the windowing queue. The WindowingMaxQueueSize attribute sets the size of the queue, specifying the maximum number of requests that can wait in the queue at one time. The WindowingMaxWaitTime attribute specifies the maximum amount of time that a single request can wait in the windowing queue.
The WindowingSize attribute sets the number of unacknowledged requests that can be sent simultaneously.
A request moves from the windowing queue to the window. From the window it is submitted for processing. A submitted request remains in the window until its response is received. When the response is received, the request is released and another request can be moved from the windowing queue to the window.
If any one of these three windowing parameters is set to a value less than zero, windowing is turned off. If all of these three parameters are greater than zero, windowing is turned on.
For descriptions of these attributes see:
If the windowing request queue is full or the timer has expired, the request is not sent and an error code is returned to the plug-in instance.
If an SMS message is larger than the maximum payload size, the message content is concatenated into segments before it is delivered to the application.
The maximum payload size defaults to the standard set by the Parlay X 2.1 Short Messaging specification. You can set the maximum payload size using the wlng.smpp.max_payload_size system property on the command line when starting Services Gatekeeper.
For configuration attributes regarding segments, see:
Messaging-capable networks use short codes and message prefixes to help route traffic and to make access to certain features easier for the end user. Instead of having to use the entire address, users can enter a short code that is mapped to the full address in the network. The Parlay X 2.1 Short Messaging/ SMPP communication service supports short codes and message prefixes, which allow the same short code to be mapped to different applications based on the prefix to the enclosed message.
To optimize system utilization, applications should load-balance application-triggered requests among all application tier servers.
When there are multiple connections to the SMSC within a single plug-in instance, the SMPP Server Service selects one of the connections to the SMSC.
A prerequisite for high-availability for the Parlay X 2.1 Short Messaging/SMPP communication service is redundant network tier servers, redundant network interface cards in each network tier server, and a redundant set of SMPP servers to connect to. High availability between Services Gatekeeper and the network is achieved by using at least two different plug-in instances per network tier server and having the plug-in instances connect to different SMPP servers.
High availability behavior is as follows:
The SMPP server runs in every network node. If one network node is unavailable, mobile-terminated requests are automatically routed to a healthy node. Related delivery reports are routed from the healthy network node that handled the request to the application.
If the application tier is unavailable, mobile-originated messages are routed to a healthy application tier node.
In a Services Gatekeeper cluster, if the server becomes unavailable after sending a SUBMIT_SM request to and receiving the SUBMIT_SM_RESP from the SMSC, the SMSC routes the subsequent delivery receipt to another server. This other server retrieves the message information from cluster-level storage and processes it.
In a Services Gatekeeper cluster, if a server becomes unavailable after sending a SUBMIT_SM request to and receiving the SUBMIT_SM_RESP from an application, the application routes the subsequent cancel, query, or replace request to another server. This other server retrieves the message information from cluster-level storage and processes it.
For information about the SOAP-based interface for the Parlay X 2.1 Short Messaging/SMPP communication service, see the discussion of Parlay X 2.1 Interfaces in Application Developer's Guide.
For information about the RESTful Short Messaging interface, see the discussion of Short Messaging in RESTful Application Developer's Guide.
The RESTful Service Short Messaging interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating SLAs, reading CDRs, and so on, they are the same.
The Parlay X 2.1 Short Messaging/SMPP communication service generates Event Data Records (EDRs), Charging Data Records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service.
For general information, see Appendix A, "Events, Alarms, and Charging."
Table 6-1 lists the IDs of the EDRs created by the Parlay X 2.1 Short Messaging/SMPP communication service. This list does not include EDRs created when exceptions are thrown.
Table 6-1 Event Types Generated by Parlay X 2.1 Short Messaging/SMPP
EDR ID | Method Called |
---|---|
6000 |
notifySmsDeliveryReceipt |
6001 |
notifiySmsReception |
7000 |
sendSms |
7001 |
sendSmsLogo |
7002 |
sendSmsRingtone |
7003 |
startSmsNotification |
7004 |
stopSmsNotification |
7011 |
getSmsDeliveryStatus |
7012 |
getReceivedSms |
See Table 20-2, "Event Types Generated by the SMPP Server Service" for the list of EDRs generated by the SMPP Server Service.
Short Messaging/SMPP-specific CDRs are generated under the following conditions:
After a sendSms request is sent from Services Gatekeeper to the network.
After a reportNotification request is sent from the network to Services Gatekeeper, indicating that a delivery receipt has been returned for the application.
When a mobile-originated message has been successfully delivered to the application.
Table 6-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
This section lists the parameters that can be tunneled or defined in the <requestContext>
element of an SLA.
The last four parameters described, dest_bearer_type, service_type, ussd_service_operation, and its_session_info, are used to support Unstructured Supplementary Service Data (USSD).
This parameter defines the mandatory SMPP protocol_id parameter.
It is valid for application-initiated requests only.
This parameter can be set using SLAs or parameter tunneling. An SLA setting overrides a tunneled parameter.
This parameter key name can be configured in the wlng.sms.protocol.id system property. The default is sms.protocol.id.
Integer
Value range is 0–65535.
This parameter defines the optional SMPP source_port parameter.
It is valid for application-initiated requests.
It is valid for network-triggered requests if the forwarding parameter is enabled. See "Attribute: ForwardXParams" for more information.
This parameter can be set using parameter tunneling.
Integer
Value range is 0–65535.
This parameter defines the optional SMPP destination_port parameter.
It is valid for application-initiated requests.
It is valid for network-triggered requests if the forwarding parameter is enabled. See "Attribute: ForwardXParams" for more information.
This parameter can be set using parameter tunneling.
Integer
Value range is 0–65535.
This parameter defines the mandatory SMPP data_coding parameter.
Overrides the DefaultDataCoding configuration attribute. See "Attribute: DefaultDataCoding" for more information.
It is valid for application-initiated requests.
It is valid for network-triggered requests if the forwarding parameter is enabled. See "Attribute: ForwardXParams" for more information.
This parameter can be set using parameter tunneling.
Integer
Value range is 0–255. Some values are restricted. See the SMPP specification for details.
This parameter defines the mandatory SMPP esm_class parameter.
It is valid for application-initiated requests only.
This parameter can be set using parameter tunneling.
Integer
Value range is 0–255. Some values are restricted. See the SMPP specification for details.
This parameter defines the mandatory SMPP service_type parameter.
It is valid for application-initiated requests only.
This parameter can be set using SLAs or parameter tunneling. An SLA setting overrides a tunneled parameter.
This parameter name can be configured in the wlng.sms.service.type system property. The default is sms.service.type.
String enumeration
Valid values are CMT, CPT, VMN, VMA, WAP, USSD, and an empty string (""). See the SMPP specification for details.
This parameter defines the mandatory SMPP replace_if_present_flag parameter.
It is valid for application-initiated requests only.
This parameter can be set using SLAs or parameter tunneling. An SLA setting overrides a tunneled parameter.
This parameter key name can be configured in the wlng.sms.replace.if.present system property. The default is “sms.replace.if.present”.
Integer
Value values are 0 and 1. See the SMPP specification for details.
This parameter defines a mapping ID.
The ID is used for looking up an SMPP ESME Type Of Number (TON) and an SMPP ESME Numbering Plan Indicator (NPI). The TON and NPI are configured using OAM.
This parameter is valid for application-initiated requests only.
This parameter can be set using SLAs or parameter tunneling. An SLA setting overrides a tunneled parameter.
String
This parameter defines a mapping ID.
The ID is used for looking up an SMPP ESME Type Of Number (TON) and an SMPP ESME Numbering Plan Indicator (NPI). The TON and NPI are configured using OAM.
The n is the number of the destination address. Valid values are 0 to one less than the number of destination addresses. An example of this parameter name would be:
com.bea.wlcp.wlng.plugin.sms.DestinationAddressType.2
This parameter is valid for application-initiated requests only.
This parameter can be set using SLAs or parameter tunneling. An SLA setting overrides a tunneled parameter.
String
This parameter defines the mandatory SMPP registered_delivery parameter.
It specifies whether delivery reports are requested for application-initiated requests.
It is valid for application-initiated requests only.
This parameter can be set using SLAs or parameter tunneling. An SLA setting overrides a tunneled parameter.
Boolean
If true
, delivery reports are requested and the SMPP registered_delivery parameter is set to 0x01.
If false
, delivery reports are not requested and the SMPP registered_delivery parameter is set to 0x00.
This parameter defines the mandatory SMPP data_coding parameter.
The plug-in uses it for encoding the message string.
It is valid for application-initiated requests only.
This parameter can be set using SLAs.
Integer
Value range is 0–255. Some values are restricted. See the SMPP specification for details.
This parameter defines the mandatory SMPP priority_flag parameter.
It is valid for application-initiated requests only.
This parameter can be set using SLAs.
String
Valid values are:
HIGH; Sets priority_flag to 3.
LOW; Sets priority_flag to 0.
DEFAULT; Sets priority_flag to 0.
UNDEFINED; Sets priority_flag to 0.
This parameter defines the originating address of the SMS in the delivery receipt.
When this parameter is used, the SmsMBean's Boolean forwardXParam attribute must be set to true
to make the parameter appear in the SOAP header. By default, forwardXParam is false
. See "Attribute: ForwardXParams" for more information.
This parameter can be set using parameter tunneling.
String
This parameter defines the billing information according to the format in the SMPP Specification 5.0, section 4.8.4.3 titled "billing_identification".
The parameter works with SMPP 5.0 SMSCs, but with not with SMPP 3.4 SMSCs.
The parameter is intended for use with Parlay X 2.1 SMPP.
Hexadecimal String
Table 6-3 describes the format.
Table 6-3 Format for smpp_bliing_id Value
Field | Size (octets) | Type | Description |
---|---|---|---|
parameter tag |
2 |
Integer |
0x060B |
length |
2 |
Integer |
Length of value part in octets |
value |
1 - 1024 |
Octet String |
Bits 7......0 0XXXXXXX (Reserved)1XXXXXXX (Vendor Specific) The first octet represents the Billing Format tag and indicates the format of the billing information contained in the remaining octets. |
If the value is not sent as a hexadecimal string, it is ignored and a warning is logged.
Here is sample code for encoding the string.
private String getHexEncodedString(String normalString) { byte[] bHexStr = normalString.getBytes(); String retVal = ""; ..String sOctet = null; for (int i = 0; i < bHexStr.length; i++) { sOctet = Integer.toHexString((int) (bHexStr[i] & 0xFF)); if (sOctet.length() == 1) { sOctet = "0" + sOctet; } retVal = retVal.concat(sOctet); } return retVal.toUpperCase(); }
This parameter defines the dest_addr_subunit field in the following SMPP operations:
SUBMIT_SM
SUBMIT_MULTI
DATA_SM
It can be set using parameter tunneling.
Decimal
The decimal value is automatically converted to a hexadecimal string before it is passed to the SMPP dest_addr_subunit field.
<xparams> <param key="dest_addr_subunit" value="1"/> </xparams>
This parameter is used to request the desired bearer for delivery of the message to the destination address.
If the receiving system (the SMSC) does not support the indicated bearer type, it may return a response PDU reporting a failure.
See section 5.3.2.5 of the Short Message Peer to Peer Protocol Specification v3.4 for the formal definition of the parameter and section 4.7.1 for its specification as an optional parameter for the DATA_SM operation.
This parameter can be set using parameter tunneling.
Unsigned Byte [0–255]
Valid values are:
0x00 = Unknown
0x01 = SMS
0x02 = Circuit Switched Data (CSD)
0x03 = Packet Data
0x04 = USSD
0x05 = CDPD
0x06 = DataTAC
0x07 = FLEX/ReFLEX
0x08 = Cell Broadcast (cellcast)
9 to 255 Reserved
This parameter indicates the SMS application service associated with the message. Allows the ESME to use enhanced messaging services such as replace_if_present and to control the teleservice used on the air interface (for example, ANSI-136/TDMA and IS-95/CDMA).
It is used to support tunneling USSD (3G TS 23.090 version 3.0.0) messages through the SMPP protocol.
See section 5.2.11 of the Short Message Peer to Peer Protocol Specification v3.4 for the formal definition of the parameter and the appropriate subsections of section 4 for its specification as a mandatory parameter for SUBMIT_SM, SUBMIT_MULTI, DELIVER_SM, DATA_SM, and CANCEL_SM.
This parameter can be set using parameter tunneling.
Octet string
The predefined generic service type value for USSD is USSD.
This parameter defines the USSD service operation that is required when SMPP is used as an interface to a (GSM) USSD system.
It is used to support tunneling USSD (3G TS 23.090 version 3.0.0) messages through the SMPP protocol.
It is used as an optional parameter to the SMPP SUBMIT_SM operation.
This parameter is defined in section 5.3.2.44 of the Short Message Peer to Peer Protocol Specification v3.4.
It was added to the DELIVER_SM operation in the SMPP 5.0 specification. See Short Message Peer to Peer Protocol Specification Version 5.0.
This parameter can be set using parameter tunneling.
Unsigned byte [0–255]
Valid values are:
0 = PSSD indication
1 = PSSR indication
2 = USSR request
3 = USSN request
4 to 15 Reserved
16 = PSSD response
17 = PSSR response
18 = USSR confirm
19 = USSN confirm
20 to 31 Reserved
32 to 255 Reserved for vendor-specific USSD operations
This is a required parameter for the CDMA Interactive Teleservice as defined by the Korean PCS carriers [KORITS]. Contains control information for the interactive session between an MS and an ESME.
See section 5.3.2.43 of the Short Message Peer to Peer Protocol Specification v3.4 for the formal definition of the parameter and the appropriate subsections of section 4 for its specification as an optional parameter for SUBMIT_SM, DELIVER_SM, and DATA_SM.
This parameter is also supported for native SMPP.
This parameter can be set using parameter tunneling.
Unsigned Short (2 bytes) [0–65535] as an octet string
Following is a description of the octet string.
Bits 7...............0
SSSS SSSS (octet 1)
NNNN NNNE (octet 2)
Octet 1 contains the session number (0–255) encoded in binary. The session number remains constant for each session.
Octet 2 encodes the sequence number of the dialog unit (as assigned by the ESME) within the session in bits [7. . . 1] .
Bit 0 of octet 2 is the End of Session Indicator, indicating that the message is the end of the conversation session. Valid values for the End of Session Indicator are:
0 = End of Session Indicator inactive
1 = End of Session Indicator active
This section describes the properties and workflow for setting up Parlay X 2.1 Short Messaging/SMPP and Extended Web Services Binary SMS/SMPP network protocol plug-in instances. These plug-in instances share the same configuration options.
The Parlay X 2.1 Short Messaging/SMPP and Extended Web Services Binary SMS/SMPP communication services rely on an SMPP Server Service for connecting to the Small Message Service Center (SMSC).
The SMPP Server Service is also used by the Native SMPP Communication Service. See Chapter 20 for information on managing client connections using SMPP Server Service.Configuration facilities for the SMPP Server Service are described in detail in the following sections of Chapter 20, "Native SMPP."
Table 6-4 lists the technical specifications for the communication service.
Table 6-4 Properties for Parlay X 2.1 Short Messaging/SMPP and EWS Binary SMS/SMPP
Property | Description |
---|---|
Managed object in Administration Console |
domain_name > OCSG > server_name > Communication Services > plugin_instance_id |
MBean |
Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=same as the network protocol instance_id assigned when the plug-in instance is created Type=oracle.ocsg.sms.smpp.management.SmsMBean |
Network protocol plug-in service ID |
Plugin_px21_short_messaging_smpp |
Network protocol plug-in instance ID |
The ID is assigned when the plug-in instance is created. See "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. |
Supported Address Scheme |
tel |
Service type |
Sms |
Exposes to the service communication layer a Java representation of: |
Parlay X 2.1 Short Messaging/SMPP:
Extended Web Services Binary SMS/SMPP:
|
Interfaces with the network nodes using: |
SMPP 3.4 |
Deployment artifacts |
wlng_nt_sms_px21.ear and wlng_at_sms_px21.ear |
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Create one or more instances of the plug-in service. See "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. Use the plug-in service ID as listed in the "Properties for Parlay X 2.1 Short Messaging/SMPP and Extended Web Services Binary SMS/SMPP" section.
Using the Administration Console or an MBean browser, select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.
Configure the behavior of the plug-in instance. See "Reference: Attributes and Operations for Parlay X 2.1 Short Messaging/SMPP and Extended Web Services Binary SMS/SMPP" for the list of attributes and operations.
If the plug-in uses short code mappings, configure the Short Code Mapper. For more information. See "Managing and Configuring Shortcode Mappings" in System Administrator's Guide.
Set up the routing rules to the plug-in instance. See "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 2.1 Short Messaging/SMPP and Extended Web Services Binary SMS/SMPP" section.
If required, create and load a node SLA. For details see “Defining Global Node and Service Provider Group Node SLAs” and “Managing SLAs” in the Accounts and SLAs Guide.
Provision the service provider accounts and application accounts. For information, see Accounts and SLAs Guide.
The Parlay X 2.1 Short Messaging/SMPP and Extended Web Services Binary SMS/SMPP communication services use the SMPP Server Service to establish and manage client connections with the SMSC.
The SMPP Server Service establishes a client connection to the SMSC when the plug-in instance is activated or when the administrator resets the client connection by using the resetClientConnection SMPP Server Service operation.
The following Server Service operations, described in Chapter 20, "Native SMPP," are used to manage client connections:
This section describes the attributes and operations for configuration and maintenance:
Scope: Server
Unit: Not applicable
Format: Boolean
Read-only attribute reporting the active status of the plug-in:
true
if the plug-in is currently active
false
if the plug-in is currently inactive
Scope: Server
Unit: Not applicable
Format: Integer
Specifies how the plug-in binds to the SMSC
Use:
0 to bind as transmitter and receiver
1 to bind as transceiver
2 to bind as transmitter only
3 to bind as receiver only
The default is 0.
Scope: Server
Unit: Not applicable
Format: Boolean
Set to true
to use the DATA_SM operation when sending binary data.
The default is false
.
Scope: Server
Unit: Not applicable
Format: Integer
Specifies the default data coding to use when sending SMS messages. This value will be used if a data coding is not provided by the application-facing interface.
See the data_coding parameter in the SMPP specification for valid values.
Use:
0 for SMSC Default Alphabet
1 for ASCII
8 for USC2
If this attribute is set to 0, the message is 7-bit encoded with a maximum of 160 characters in a single SMS message. Messages greater than 160 characters are split.
If this attribute is set to 1, the message is 8-bit encoded with a maximum of 140 characters in a single SMS message. Messages greater than 140 characters are split.
The default is 0.
Scope: Server
Unit: Not applicable
Format: Integer
Specifies the command status of the DELIVER_SM_RESP operation to send to the SMSC if a delivery notification or mobile-originated message can not be delivered to the requesting application and there is no matching offline notification.
Scope: Server
Unit: Not applicable
Format: Integer
ESME Numbering Plan Indicator (NPI). Used as a default for the destination address.
Use:
0 for Unknown
1 for ISDN (E163/E164)
3 for Data (X.121)
4 for Telex (F.69)
6 for Land Mobile (E.212)
8 for National
9 for Private
10 for ERMES
14 for Internet (IP)
18 for WAP Client ID
Scope: Server
Unit: Not applicable
Format: Integer
ESME Type Of Number (TON). Used as a default for the destination address.
Use:
0 for Unknown
1 for International
2 for National
3 for Network
4 for Subscriber
5 for Alphanumeric
6 for Abbreviated
7 Reserved
Scope: Server
Unit: Minutes
Format: Integer
Minimum interval between ENQUIRE_LINK requests to the SMSC.
The default is 60 seconds.
The plug-in instance performs ENQUIRE_LINK requests (heartbeats) to the SMSC to verify that the connection is alive.
The setting is applied as follows:
If the plug-in has received traffic subsequent to the last scheduled time, no ENQUIRE_LINK request is made and a new timer (EnquireLinkTimerValue) is scheduled.
If no response is received, the plug-in unbinds and attempts to re-bind.
If the plug-in has outstanding requests that prevent it from sending ENQUIRE_LINK requests, it unbinds. This typically occurs if the SMSC is unresponsive while the plug-in is filling the window with unacknowledged SUBMIT_SM requests.
To turn off sending ENQUIRE_LINK requests, set the EnquireLinkTimerValue to 0.
Scope: Server
Unit: Not applicable
Format: String formatted as a regular expression.
Address range of the SMS messages to be sent to the plug-in instance by the SMSC. The address range is specified as a UNIX regular expression.
Scope: Server
Unit: Not applicable
Format: Integer
ESME Numbering Plan Indicator (NPI).
Used for the destination address and as a default for the originating address. Also used for both destination address and originating address during the BIND operation.
Use:
0 for Unknown
1 for ISDN (E163/E164)
3 for Data (X.121)
4 for Telex (F.69)
6 for Land Mobile (E.212)
8 for National
9 for Private
10 for ERMES
14 for Internet (IP)
18 for WAP Client ID
Scope: Server
Unit: Not applicable
Format: String
Password used by the plug-in instance when connecting to the SMSC as an ESME.
Scope: Server
Unit: Not applicable
Format: String
System ID used by the plug-in instance when connecting to the SMSC as an ESME.
Scope: Server
Unit: Not applicable
Format: String
System type used by the plug-in instance when connecting to the SMSC as an ESME.
The default is mess_gateway.
Scope: Server
Unit: Not applicable
Format: Integer
ESME Type Of Number (TON).
Used for destination address and as a default for originating address. Also used for both destination address and originating address during the BIND operation. Use:
0 for Unknown
1 for International
2 for National
3 for Network
4 for Subscriber
5 for Alphanumeric
6 for Abbreviated
7 Reserved
Scope: Server
Unit: Not applicable
Format: Boolean
Specifies if tunneled parameters are forwarded to applications for network-triggered requests.
Use:
true
to enable forwarding.
false
to disable forwarding.
The default is false
.
Scope: Server
Unit: Not applicable
Format: String
Local server address used by the plug-in to connect to the SMSC. The address can be expressed as an IP address or host name. The address or host name must resolve to a local address.
The default is "".
Scope: Server
Unit: Not applicable
Format: Integer [1–65535]
Local port used by the plug-in to connect to the SMSC.
The default is 3000.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of keywords that can be used to match in a short message to determine whether the application receives a notification.
The text is matched in two steps:
The entire string is compared against the incoming short message for an exact match.
If no match is found, the plug-in matches the short message one word at a time against the criteria string, up to the number set in the this attribute.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Describes the format of the message_id in SUBMIT_SM_RESP, SUBMIT_MULTI_RESP, and DATA_SM_RESP operations.
If true
, the message_id is in hexadecimal format; if false
, it is in decimal format.
The default is false
.
Scope: Server
Unit: Not applicable
Format: Integer
ESM_CLASS Messaging Mode for packets.
2 for Forward mode. Used for the DATA_SM operation.
3 for Store and Forward mode.
Scope: Server
Unit: Not applicable
Format: Integer
Mobile country code for sending operator logos.
Scope: Server
Unit: Not applicable
Format: Integer
Mobile network code for sending operator logos.
Scope: Server
Unit: Not applicable
Format: String
Read-only module identifier assigned to the plug-in instance when it is created.
Scope: Server
Unit: Not applicable
Format: Integer
Number of receiver connections used to connect to the SMSC. Used when the bind type is 0 or 3. See "Attribute: BindType".
The connections are established when the plug-in instance is activated.
The default is 1.
Scope: Server
Unit: Not applicable
Format: Integer
Number of transceiver connections used to connect to the SMSC. Used when the bind type is 1. See "Attribute: BindType" for more information.
The connections are established when the plug-in instance is activated.
The default is 1.
Scope: Server
Unit: Not applicable
Format: Integer
Number of transmitter connections used to connect to the SMSC. Used when the bind type is 0 or 2. See "Attribute: BindType" for more information.
The connections are established when the plug-in instance is activated.
The default is 1.
Scope: Server
Unit: Not applicable
Format: Integer
ESME Numbering Plan Indicator (NPI).
Used as a default for the originating address.
Use:
0 for Unknown
1 for ISDN (E163/E164)
3 for Data (X.121)
4 for Telex (F.69)
6 for Land Mobile (E.212)
8 for National
9 for Private
10 for ERMES
14 for Internet (IP)
18 for WAP Client ID
Scope: Server
Unit: Not applicable
Format: Integer
ESME Type Of Number (TON).
Used as a default for originating address.
Use:
0 for Unknown
1 for International
2 for National
3 for Network
4 for Subscriber
5 for Alphanumeric
6 for Abbreviated
7 Reserved
Scope: Server
Unit: Seconds
Format: Integer
Maximum time to wait for the arrival of the subsequent segments of a concatenated short message from the SMSC after the arrival of the first segment.
Scope: Server
Unit: Not applicable
Format: Boolean
Specifies if the plug-in instance will deliver network-triggered short messages with missing message segments to applications.
Use:
true
if the plug-in assembles received segments and delivers the incomplete message to the application.
false
if the plug-in does not deliver messages to the application unless all segments are received.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if the default behavior of the plug-in instance is to request delivery reports.
Use:
true
if delivery reports should be requested.
false
if delivery reports should not be requested.
The default is true
.
If delivery requests are not requested, applications will, by default, not have the ability to poll for delivery status. However, it is possible to override the default setting in the service provider SLA or in an application SLA.
Scope: Server
Unit: Seconds
Format: Integer
Maximum time between the submission of a request to the SMSC and the receipt of the corresponding response, before the connection is terminated.
The default is 20 seconds.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of times for the plug-in to try to reconnect to the SMPP Server Service.
The default is 30.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of times for the plug-in to try to connect to the SMPP Server Service before attempting to reconnect.
The default is 3.
Scope: Server
Unit: Not applicable
Format: Integer
SMSC default alphabet. This is the default character encoding scheme used by the SMSC when encoding short messages. The plug-in instance needs to use the same character encoding scheme for the characters to be decoded correctly. All encoding schemes supported by Java are possible.
Use:
ASCII for American Standard Code for Information Interchange.
Cp1252 for Windows Latin-1.
ISO8859_1 for ISO 8859-1, Latin alphabet No. 1.
GSM_DEFAULT for the default GSM character set.
If the default character set used by the SMSC is GSM 7- bit, set this attribute to GSM_DEFAULT.
If the SMSC has a limit of 160 characters per SMS message, set the wlng.smpp.max_payload_size system property to 140.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of SMPP segments an application is allowed to send when using the Extended Web Services Binary SMS interface.
Scope: Server
Unit: Not applicable
Format: Integer
End ID of the sequence number range. Sequential numbers generated for plug-in instances cannot exceed this value.
Scope: Server
Unit: Not applicable
Format: Integer
Start ID of the sequence number range. Sequential numbers for plug-in instances begin with this value.
Scope: Server
Unit: Not applicable
Format: String
Version of the SMPP protocol used by the plug-in.
Scope: Server
Unit: Not applicable
Format: String
SMSC address as an IP-address or a host name.
The setting is not applied until the plug-in service is restarted or "Operation: resetClientConnection" is performed.
Scope: Server
Unit: Not applicable
Format: Integer
Port used by the SMSC.
The setting is applied until the plug-in service is restarted or the resetClientConnection operation is performed in the SMPP Server Service. See "Operation: resetClientConnection" for more information.
Scope: Server
Unit: Not applicable
Format: Boolean
If true
, the message is carried in the optional message_payload field in the SMPP PDU.
Current behavior predicates that only segmented messages such as ringtones, logos, and long SMS messages that have a UDH are carried in the message_payload field.
If this attribute is false
, both segmented and unsegmented messages are sent in the short_message field.
The short message data can be inserted in either the short_message or message_payload fields, but not both simultaneously.
The default is true
.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of characters allowed in a short message.
The default is 1600.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of mobile-terminated requests to the SMSC allowed in the windowing queue.
The default is 100.
If any one of the three windowing attributes (WindowingMaxQueueSize, WindowingMaxWaitTime, or WindowingSize) is set to a value less than zero, windowing is turned off. If all of these three attributes have values greater than zero, windowing is turned on.
See "Windowing" for general information about windowing.
Scope: Server
Unit: Seconds
Format: Integer
Maximum time that a mobile-terminated request to the SMSC is allowed to wait in the windowing queue.
Valid only when the WindowingSize is enforced. See "Attribute: WindowingSize" for more information.
The default is 15 seconds.
If any one of the three windowing attributes (WindowingMaxQueueSize, WindowingMaxWaitTime, or WindowingSize) is set to a value less than zero, windowing is turned off. If all of these three attributes have values greater than zero, windowing is turned on.
See "Windowing" for general information about windowing.
Scope: Server
Unit: Not applicable
Format: Integer
Maximum number of simultaneous unacknowledged mobile-terminated requests to the SMSC enforced for each connection.
This setting applies only to requests sent from the plug-in to the SMSC, not to requests from the SMSC to the plug-in.
A value of -1 indicates that the number of unacknowledged operations is not restricted. Other valid values must be greater than 0 (zero).
The default is 5.
If any one of the three windowing attributes (WindowingMaxQueueSize, WindowingMaxWaitTime, or WindowingSize) is set to a value less than zero, windowing is turned off. If all of these three attributes have values greater than zero, windowing is turned on.
See "Windowing" for general information about windowing.
Scope: Cluster
If the tunneled parameter com.bea.wlcp.wlng.plugin.sms.OriginatingAddressType is available in a request, the value of the parameter is extracted and matched against the originating address type mapping list. The matching is with the type parameter.
Signature:
addOriginatingAddressTypeMapping(type: String, ton: int, npi: int)
Table 6-5 addOriginatingAddressTypeMapping Parameters
Parameter | Description |
---|---|
type |
Specifies the originating address type to be mapped. |
ton |
Specifies the ESME Type Of Number (TON). Use:
|
npi |
Specifies the ESME Numbering Plan Indicator (NPI). Use:
|
Scope: Cluster
If the tunneled parameter com.bea.wlcp.wlng.plugin.sms.DestinationAddressType is available in a request, the value of the parameter is extracted and matched against the destination address type mapping list. The matching is with the type parameter.
Signature:
addDestinationAddressTypeMapping(type: String, ton: int, npi: int)
Table 6-6 addDestinationAddressTypeMapping Parameters
Parameter | Description |
---|---|
type |
Specifies the destination address type to be mapped. |
ton |
Specifies the ESME Type Of Number (TON). Use:
|
npi |
Specifies the ESME Numbering Plan Indicator (NPI). Use:
|
Scope: Cluster
Displays the number of entries in the offline notification cache.
Signature:
countOfflineNotificationCache()
Scope: Cluster
Displays the number of entries in the online notification cache.
Signature:
countOnlineNotificationCache()
Scope: Cluster
Displays the sum of short messages in the cache for mobile-originated messages and mobile-terminated short messages. There are separate caches (stores) for mobile-originated and mobile-terminated short messages. This method returns the sum of both caches.
Signature:
countSmsCache()
Scope: Cluster
Adds an offline notification for applications that poll for mobile-originated short messages. Those mobile-originated short messages that match the criteria will not result in a notification callback to an application. Instead the message is stored in Services Gatekeeper. The application must use the correlator returned by this method to poll for short messages.
Signature:
enableReceiveSms(shortcode: String, criteria: String, appInstanceID: String)
Table 6-7 enableReceiveSms Parameters
Parameter | Description |
---|---|
shortcode |
Destination address of the short message. Prefixed with the URI; for example, tel: |
criteria |
Text to match against to determine if the application should receive the notification. |
appInstanceID |
ID of the application instance associated with the notification. |
Scope: Cluster
Displays information about a notification registered offline. See "Operation: enableReceiveSms" for more information.
Signature:
getOfflineNotificationInfo(correlator: String)
Scope: Cluster
Displays information about a notification registered online by an application.
Signature:
getOnlineNotificationInfo(correlator: String)
Scope: Cluster
Displays a list of all destination address type mappings.
Signature:
listDestinationAddressTypeMappings()
Scope: Cluster
Lists all online notifications for binary SMS messages.
These are notifications added using StartBinarySmsNotification.
Scope: Cluster
Displays a list of all notifications registered offline.
Signature:
listOfflineNotificationInfo()
Scope: Cluster
Displays a list of all notifications registered by an application.
Signature:
listOnlineNotificationInfo()
Scope: Cluster
Displays a list of all originating address type mappings.
Signature:
listOriginatingAddressTypeMappings()
Scope: Cluster
Removes a notification registered off-line.
Signature:
removeOfflineNotificationInfo(correlator: String)
Scope: Cluster
Removes a notification registered by an application.
Signature:
removeOnlineNotificationInfo(correlator: String)
Scope: Cluster
Removes an existing TON or NPI address type mapping for a specified originating address type.
Signature:
removeOriginatingAddressTypeMapping(type: String)
Table 6-12 removeOriginatingAddressTypeMapping Parameters
Parameter | Description |
---|---|
type |
Originating address type for the mapping. See "Operation: addOriginatingAddressTypeMapping" and "Operation: listOriginatingAddressTypeMappings" for more information. |
Scope: Cluster
Removes an existing TON or NPI address type mapping for a specified destination address type.
Signature:
removeDestinationAddressTypeMapping(type: String)
Table 6-13 removeDestinationAddressTypeMapping Parameters
Parameter | Description |
---|---|
type |
Destination address type for the mapping. See "Operation: addDestinationAddressTypeMapping" and "Operation: listDestinationAddressTypeMappings" for more information. |
Scope: Cluster
Registers a notification for mobile-originated short messages on behalf of an application. Has the same result as if the application used the startSmsNotification operation in the Parlay X 2.1 SmsNotificationManager interface.
The text in the criteria parameter is matched in two steps to determine the target application:
The entire string is compared with the incoming short message for an exact match.
If an exact match is not found, the message is matched one word at a time from left to right up to the number of words set by the MaxKeywordLimit attribute. See "Attribute: MaxKeywordLimit" for more information.
Services Gatekeeper rejects overlapping criteria. For example, if the text "FUNNY JOKE" and "FUNNY JOKE 5439" are both specified as the criteria text for the same shortcode, an exception will be raised when the notification is started.
An exact match takes precedence over a partial match. For example, if Application1 sets its criteria to "FUNNY JOKE" and Application2 sets its criteria to "JOKE", both for the same short code, a message with the content "FUNNY JOKE" will trigger a notification to Application1 but not to Application2.
Signature:
startSmsNotification(endpoint: String, shortcode: String, criteria: String, appInstanceID: String)
Table 6-14 startSmsNotification Parameters
Parameter | Description |
---|---|
endpoint |
Notification endpoint implemented by the application. This endpoint implements the Parlay X 2.1 SmsNotification interface. Format: URL |
shortcode |
Destination address or service activation number for the short message. |
criteria |
Text in the payload of the short message to match to determine if the application receives the notification. |
appInstanceID |
ID of the application instance associated with this notification. |
Scope: Cluster
Gets the ESME Numbering Plan Indicator (NPI) of the destination address mapping added for the specified type.
Signature:
translateDestinationAddressNpi(type: String)
Table 6-15 translateDestinationAddressNpi Parameters
Parameter | Description |
---|---|
type |
Type for used for the mapping. See "Operation: addOriginatingAddressTypeMapping" for more information. |
Scope: Cluster
Gets the ESME Type of Number (TON) of the destination address mapping added for the specified type.
Signature:
translateDestinationAddressTon(type: String)
Table 6-16 translateDestinationAddressTon Parameters
Parameter | Description |
---|---|
type |
Type for used for the mapping. See "Operation: addDestinationAddressTypeMapping" for more information. |
Scope: Cluster
Gets the ESME Numbering Plan Indicator (NPI) of the originating address mapping added for the specified type.
Signature:
translateOriginalAddressNpi(type: String)
Table 6-17 translateOriginatingAddressNpi Parameters
Parameter | Description |
---|---|
type |
Type for used for the mapping. See "Operation: addOriginatingAddressTypeMapping" for more information. |
Scope: Cluster
Gets the ESME Type of Number (TON) of the originating address mapping added for the specified type.
Signature:
translateOriginalAddressTon(type: String)
Table 6-18 translateOriginatingAddressTon Parameters
Parameter | Description |
---|---|
type |
Type for used for the mapping. See "Operation: addOriginatingAddressTypeMapping"for more information. |