Configuration
Introduction
The N-Squared JSLEE supports executing highly performant SMPP endpoints for the processing of incoming SMPP messages over TCP. The SMPP application allows for both client and server SMPP connections, and multiple SMPP applications can be executed within the same JSLEE instance, assuming their configuration does not require the same TCP/IP ports to be used for listening.
{
"smpp": {
"handler": "nz.co.nsquared.slee.smpp.SMPPVerticle",
"instance-count": 1,
"configuration": {
"segmentation-sets": {
// segmentation set definitions
},
"encoding-sets": {
// encoding set definitions
},
"tlv-sets": {
// TLV set definitions
},
"endpoints": [
{
// endpoint configuration, either client or server
}
]
}
}
}
Endpoint Configuration
The larger configuration section of the SMPP application is the configuration of each endpoint. Endpoints are either client or server endpoints - reflecting whether the connection is initiated at the TCP level by the JSLEE application, or the JSLEE application opens a TCP port for listening and accepts connections from other SMPP entities.
Note that the distinction between Server and Client endpoints is only relevant for how the SMPP application handles its TCP connection state. Whether the connection acts as a MC or ESME depends on additional configuration (specifically whether it is configured to support RX, TX or TRX style communication).
Common Configuration
Some configuration elements apply regardless of the endpoint type.
If the message-handler
parameter is set to EventBus
, the processing-address
parameter creates a
dependency for the destination value - the endpoint will be
disabled if there is not at least one instance of this address available.
Field | Type | Required? | Default | Description |
---|---|---|---|---|
default-response-time-limit-ms |
Integer | No | 5000 |
The maximum period, in milliseconds, to wait for a response to an outbound message to the network. |
response-time-out-monitor-frequency-ms |
Integer | No | 500 |
The poll period, in milliseconds, to check for missing responses to outbound messages. |
window-size |
Integer | No | 0 |
The number of outstanding sent messages allowed, after which incoming traffic from the event bus will be rejected. If set to 0, no throttling will occur. |
message-handler |
String | Yes | EventBus |
The message handler to use when |
processing-address |
String | No | - | The address of the JSLEE application to send all SMPP messages received to. Only applicable if message-handler is set to EventBus . |
processing-type |
String | No | relay |
The message handler processing type to use when sending messages to other applications. Only applicable if message-handler is set to EventBus . |
preserve-encodings |
Boolean | No | false |
If true , the matched SMPP Encoding Scheme for the received SMPP data_coding value will be included as the message sent across the SLEE as the only allowed outgoing encodings if the message is on-sent. Only applicable when processing-type is set to unpack . |
encoding-set |
Object | No | (see below) | The name of the SMPP Encoding Set used by this endpoint. |
tlv-set |
Object | No | (see below) | The name of the TLV Set used by this endpoint. |
edr-enabled |
Boolean | No | Inherited | Whether EDRs are enabled for this endpoint. If not specified, the inherited value from the service and/or global EDR configuration will be honoured. |
edr-message-text-in |
Boolean | No | true |
Whether EDRs will contain decoded message text for messages received from the network. Only applicable if enable-edrs is true . |
edr-message-text-out |
Boolean | No | true |
As for edr-message-text-in , but for messages sent to the network. |
enable-enquire-link |
Boolean | No | Various | Whether to enable the sending of SMPP enquire_link messages. Defaults to true for client endpoints and false for server endpoints. Note that the JSLEE SMPP service endpoints will always respond immediately to any enquire_link message received, regardless of this setting. |
enquire-link-frequency-ms |
Integer | No | 10000 |
The period, in milliseconds, between sending enquire_link messages. Only used if enable-enquire-link is true. |
window-size |
Integer | No | 0 |
The maximum number of outstanding requests from external entities allowed for this endpoint, i.e. the maximum number of requests that have not had a response sent back to the remote end yet and are still in-progress on the JSLEE system. The valid range for this value is 0..99999 , where 0 indicates no maximum amount. |
is-enabled |
Boolean | No | true |
Whether the endpoint is brought online at service startup. |
name |
String | No | Generated | A friendly name for the endpoint for use in logging. |
tcp |
Object | No | (various) | Common TCP/IP connectivity options to use for all TCP/IP connections to and from the SMPP service. |
Message Handler and Processing Type
Each SMPP application endpoint defines a message handler. The message handler describes how incoming messages are
handled by the SMPP application itself. The following options exist for the message-handler
parameter:
Message Handler | Description |
---|---|
DevNull |
All SMPP messages received are responded to successfully, but otherwise dropped. This handler is useful for testing only. |
EventBus |
All SMPP messages are transferred to another JSLEE application (for example, the SMS Gateway application). |
Note that the message-handler
configuration is optional. The default is EventBus
.
When the EventBus
message handler is used, a mode of operation may also be selected with the processing-type
parameter.
The following otions are available:
Processing Type | Description |
---|---|
relay |
SMPP messages are passed as-received to the destination application. |
unpack |
SMPP messages are translated to the SMS JSON format before being passed to the destination application. |
The processing-type
parameter is optional, and defaults to relay
.
Server Configuration
A simple server endpoint can be defined with the following JSON:
{
"port": 4001,
"server": true,
"processing-address": "<JSLEE application name>"
}
This will define a SMPP server, listening on port 4001. Any SMPP messages recieved over connections opened by this server
will be sent to the JSLEE application defined by the processing-address
configuration field. Note that if a
processing address is provided which does not refer to an accessible JSLEE application, or the application is inaccessible,
then a ESME_RUNKNOWNERR
SMPP response will be sent back to the remote endpoint.
The authentication-address
parameter creates a dependency
for the destination value - the endpoint will be disabled if there is not at least one instance of this address available.
Full server configuration options are as follows:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
port |
Integer | Yes | - | The TCP port to listen on. |
server |
Boolean | Yes | - | Must be set to true for SMPP servers. |
interface |
String | No | 0.0.0.0 |
The IP address of the local interface to bind to. If left as the default value, the server will bind to all interfaces. |
authentication-address |
String | No | - | The name of the JSLEE application to send authentication requests to on the receipt of a bind request from a remote endpoint. If not defined, all bind requests will be accepted. Refer to the SMPP authentication methods for details. |
Client Configuration
A simple client configuration can be defined with the following JSON:
{
"port": 4001,
"remote-server": "192.168.0.56",
"system-id": "<username>",
"password": "<password>"
}
This will define a SMPP client, connecting to port 4001
at 192.168.0.56
. It will connect to the remote endpoint using bind_transceiver
using the given system ID and password. The system type will be set to empty.
Full client configuration options are as follows:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
remote-server |
String | Yes | - | The IP address of the server to connect to. |
interface |
String | No | Inherited | The IP address of the local interface to bind to. By default the system will bind to whichever local interface is the OS uses to route to the remote IP. |
port |
Integer | Yes | - | The TCP port to connect to on the remote server. |
system-id |
String | No | Empty |
The SMPP system_id to use when connecting to the remote server. |
password |
String | No | Empty |
The SMPP password to use when connecting to the remote server. |
service-type |
String | No | Empty |
The SMPP system_type to use when connecting to the remote server. |
bind-type |
String | No | TRX |
Whether to connect using bind_transmitter bind_receiver or bind_transceiver (TX , RX and TRX respectively). |
connection-count |
Integer | No | 1 |
The number of TCP/IP connections to open to the server. Requests to this endpoint are round-robined through each active connection. |
server |
Boolean | No | false |
Must be false for SMPP clients. |
SMPP Data Coding Configuration
SMPP data coding for endpoints is defined as maps of segmentation and data coding definitions per-set in the following manner:
{
"segmentation-sets": {
"<set name>": {
"scheme": "<message segmentation scheme>",
"use-payload": <whether to use the SMPP TLV "message_payload">,
"maximum-bytes": <maximum unsegmented encoded bytes>,
"segment-bytes": <maximum bytes per segment>
}
},
"encoding-sets": {
"<set name>": {
"segmentation-set": "<default segmentation set name>",
"encoding-supported": {
"<userdata encoding scheme>": <userdata encoding value>,
"<userdata encoding scheme>": {
"data-coding": <userdata encoding value>,
"segmentation-set": "<override segmentation set name>"
}
},
"encoding-received": {
"<userdata encoding value>": "<userdata encoding scheme>"
},
"flash-encode-mode": "<flash message encoding mode>",
"flash-decode-alphabet-7bit": "<flash message 7-bit decoding alphabet>",
"flash-decode-alphabet-8bit": "<flash message 8-bit decoding alphabet>",
"flash-decode-alphabet-16bit": "<flash message 16-bit decoding alphabet>",
"replacement": "<replacement character>"
}
}
}
Each SMPP encoding set is given a name as its key and consists of definitions for that set, including an array of data coding definitions containing the on-the-wire integer value and the encoding scheme to use for that value. Segmentation values for sent messages may also be applied, either at the set or encoding scheme level.
When a message to be sent specifies one or more encoding schemes, only those encodings will be used when sending short messages. If the endpoint’s encoding set does not have the specified encoding defined, the message will be rejected.
Messages to be sent that do not specify an encoding scheme will have the endpoint’s encoding
set values tried for userdata encoding, with the order shown for
SMPP Encoding Schemes. If encoding cannot occur with any supported encoding scheme in the
endpoint’s set, the message will be rejected. The replacement
character to be used
for unsupported characters may be specified, in which case the first encoding scheme
will always be used and any non-encodable character will be replaced with the replacement
.
Messages that are received from the network will be translated using the endpoint’s encoding
scheme(s) based on the received SMPP data_coding
value. If the message uses
flash encoding, the appropriate alphabet will be selected based on
the signalled character width.
Within each encoding set, the following configuration items are available:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
encoding-supported |
Object | No | As below | The Encoding Supported Details for this encoding set. |
encoding-received |
Object | No | - | Additional mappings for decoding received messages, keyed off the received data coding value (0..255 ) and the encoding scheme to use. Values given are used in preference to those in encoding-supported . These values are not used for outgoing messages. The available encoding schemes are shown under SMPP Encoding Schemes. |
segmentation-set |
String | No | As below | The SMPP Segmentation Set to use for outbound message segmentation for this encoding set. |
flash-encode-mode |
String | No | smpp-loose |
The encoding mode to use when sending flash messages (AKA GSM message class 0). The available values are shown under Flash Encode Modes. |
flash-decode-alphabet-7bit |
String | No | gsm7bit-default |
The SMPP Encoding Scheme to use when an SMPP message is received with 7-bit GSM flash encoding. |
flash-decode-alphabet-8bit |
String | No | gsm8bit-default |
The SMPP Encoding Scheme to use when an SMPP message is received with 8-bit GSM flash encoding. |
flash-decode-alphabet-16bit |
String | No | ucs2 |
The SMPP Encoding Scheme to use when an SMPP message is received with 16-bit GSM flash encoding. |
replacement |
String | No | null |
The replacement character to use for characters that the encoding scheme does not support. Note that if this parameter is specified, only the first encoding scheme in the encoding-supported mapping will be used (as encoding will always succeed with replaced characters). |
Encoding Supported Details
The entries in an encoding set’s encoding-supported
map provide the available encoding schemes for endpoints using
this encoding set and the value (0..255
) used on the wire in SMPP messages for that scheme. These values are used for
both incoming and outgoing messages. In addition, these entries may override the encoding set’s default
SMPP Segmentation Set if required.
Each entry in the map may be either an integer or an object, e.g.:
{
"encoding-supported": {
"gsm7bit": 0,
"gsm8bit": {
"data-coding": 0,
"segmentation-set": "gsm8-segmentation"
}
}
}
In the above configuration, both GSM 7-bit and GSM 8-bit would be used with a data coding value of 0, but GSM 8-bit would use a specific SMPP Segmentation Set.
The available fields in an encoding-supported
encoding instance when given as an object are:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
data-coding |
String | Yes | - | The data_coding on-the-wire value that is used for this SMPP Encoding Scheme. |
segmentation-set |
String | Yes | - | The SMPP Segmentation Set to use when sending messages. |
The available encoding schemes are shown under SMPP Encoding Schemes.
Default SMPP Encoding Set
If no encoding-set
is specified in an endpoint’s configuration, it will create and use a default encoding set as if
the following configuration were provided:
{
"encoding-supported": {
"gsm7bit-default": 0,
"ascii": 1,
"gsm8bit-default": 3,
"ucs2": 8
}
}
SMPP Segmentation Sets
Each segmentation set may set any of the following options:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
use-payload |
Boolean | No | true |
Whether to use the SMPP TLV message_payload for long messages (true ) or to perform message segmentation (false ). |
maximum-bytes |
Positive Integer | Conditional | 140 |
The maximum allowed characters in the decoded text that may be sent before segmentation occurs (i.e. when use-payload does not apply). Must be defined if use-payload is not set to true . |
segment-bytes |
Positive Integer | No | maximum-bytes value |
The maximum allowed characters per short message segment. If not provided, defaults to maximum-bytes value. |
scheme |
String | No | sar |
The segmentation behaviour scheme for sent messages. Received messages have their segmentation scheme determined automatically. |
Default SMPP Segmentation Set
If no segmentation-set
is specified in an encoding set’s configuration, it will create and use a default segmentation
set as if the following configuration were provided:
{
"use-payload": true
}
SMPP Encoding Schemes
The following encoding schemes are supported for SMPP messages:
Type | Description |
---|---|
gsm7bit |
GSM 7-bit, any table (GSM 23.38). |
gsm7bit-default |
GSM 7-bit, default alphabet tables (GSM 23.38). |
gsm7bit-turkish |
GSM 7-bit, Turkish national language tables (GSM 23.38). |
gsm7bit-spanish |
GSM 7-bit, Spanish national language tables (GSM 23.38). |
gsm7bit-portuguese |
GSM 7-bit, Portugese national language tables (GSM 23.38). |
gsm7bit-bengali |
GSM 7-bit, Bengali national language tables (GSM 23.38). |
gsm7bit-gujarati |
GSM 7-bit, Gujarati national language tables (GSM 23.38). |
gsm7bit-hindi |
GSM 7-bit, Hindi national language tables (GSM 23.38). |
gsm7bit-kannada |
GSM 7-bit, Kannada national language tables (GSM 23.38). |
gsm7bit-malayalam |
GSM 7-bit, Malayalam national language tables (GSM 23.38). |
gsm7bit-oriya |
GSM 7-bit, Oriya national language tables (GSM 23.38). |
gsm7bit-punjabi |
GSM 7-bit, Punjabi national language tables (GSM 23.38). |
gsm7bit-tamil |
GSM 7-bit, Tamil national language tables (GSM 23.38). |
gsm7bit-telugu |
GSM 7-bit, Telegu national language tables (GSM 23.38). |
gsm7bit-urdu |
GSM 7-bit, Urdu national language tables (GSM 23.38). |
gsm8bit |
GSM 8-bit, any table (GSM 23.38). |
gsm8bit-default |
GSM 8-bit, default alphabet table (GSM 23.38). |
gsm8bit-turkish |
GSM 8-bit, Turkish national language tables (GSM 23.38). |
gsm8bit-spanish |
GSM 8-bit, Spanish national language tables (GSM 23.38). |
gsm8bit-portuguese |
GSM 8-bit, Portugese national language tables (GSM 23.38). |
gsm8bit-bengali |
GSM 8-bit, Bengali national language tables (GSM 23.38). |
gsm8bit-gujarati |
GSM 8-bit, Gujarati national language tables (GSM 23.38). |
gsm8bit-hindi |
GSM 8-bit, Hindi national language tables (GSM 23.38). |
gsm8bit-kannada |
GSM 8-bit, Kannada national language tables (GSM 23.38). |
gsm8bit-malayalam |
GSM 8-bit, Malayalam national language tables (GSM 23.38). |
gsm8bit-oriya |
GSM 8-bit, Oriya national language tables (GSM 23.38). |
gsm8bit-punjabi |
GSM 8-bit, Punjabi national language tables (GSM 23.38). |
gsm8bit-tamil |
GSM 8-bit, Tamil national language tables (GSM 23.38). |
gsm8bit-telugu |
GSM 8-bit, Telegu national language tables (GSM 23.38). |
gsm8bit-urdu |
GSM 8-bit, Urdu national language tables (GSM 23.38). |
ascii |
ASCII (ISO/IEC 646-US). |
iso-8859-1 |
Latin alphabet 1 (ISO/IEC 8859-1). |
iso-8859-5 |
Latin/Cyrillic alphabet (ISO/IEC 8859-5). |
iso-8859-8 |
Latin/Hebrew alphabet (ISO/IEC 8859-8). |
iso-8859-15 |
Latin alphabet 9 (ISO/IEC 8859-15). |
windows-1252 |
Windows code page 1252. |
ucs2 |
UCS-2 (ISO/IEC 10646-UCS2). |
utf8 |
UTF-8 (ISO/IEC 10646-UTF8). |
When sending messages, supported encodings are selected preferentially in the order shown.
SMPP Segmentation Schemes
SMPP endpoints support the following output segmentation schemes when sending SMPP messages:
Type | Description |
---|---|
udh8 |
Message segmentation based on information in the userdata header of the message text, with 8-bit reference numbers. |
udh16 |
Message segmentation based on information in the userdata header of the message text, with 16-bit reference numbers. |
sar |
Message segmentation using the SMPP TLV fields sar_msg_ref_num , sar_total_segments , sar_segment_seqnum , and more_messages_to_send . |
Flash Encode Modes
When sending an SMS, it is possible to specify that the message is a “flash” message (AKA GSM “message class 0”). Such messages are displayed on the user’s handset, but are not saved. For details of how to specify the message class in input, refer to the SMS JSON format. Note that the reference information given here is minimal; please refer to the following standards for more information:
- Short Message Peer to Peer Protocol Specification v3.4 / v5.0
- GSM TS 03.38 / ETSI TS 123 038 (3GPP TS 23.038)
Different flash message modes options are provided by SMPP endpoints because a strict interpretation of the SMPP standard
supports only 7-bit and 8-bit text via GSM message class control using a data_coding
value of 1111xxxx
. The remaining
bits are then filled according to GSM 23.038 in the format 0zaa
, where:
z
refers to the data coding, either0
for GSM 7-bit or1
for 8-bit. Note that some SMSCs do not support this flag.aa
is the message class, which will always be set to00
for flash.
However, as this format does not allow for 16-bit encoding, there is an alternate encoding method from the same GSM standard
that is sometimes used, despite being explicitly outside the SMPP defined values. This alternate encoding has a data coding
value of 00xyzzaa
, where:
x
refers to message compression. For messages sent by SMPP endpoints using this scheme, this will always be set to0
(uncompressed).y
is a flag for a defined message class. This will always be set to1
as a message class is present in theaa
bits.zz
refers to the encoding used:00
for GSM 7-bit,01
for 8-bit, or10
for 16-bit.aa
is the message class, which will always be set to00
for flash.
Finally, the SMPP standard alternately suggests using the TLV dest_addr_subunit
to carry the message class, with the values:
0
as an unknown message class.1
equivalent to “flash”.2
equivalent to a normal message.
Accordingly, SMPP endpoints offer the below modes for flash message data coding when sending messages.
Type | Description |
---|---|
smpp-loose |
(Default) Use the standard SMPP 11110x00 format for 7-bit and 8-bit encodings, and use the GSM 0001xx00 format for 16-bit encodings. |
smpp-8bit-as-7bit |
As for smpp-loose , but use the 7-bit mask 11110000 for both 7-bit and 8-bit encodings. |
smpp-strict |
Use only the standard SMPP 11110x00 format for 7-bit and 8-bit encodings, with no support for 16-bit encodings. |
gsm |
Use only the GSM 0001xx00 format for 7-bit, 8-bit, and 16-bit encodings. |
subunit |
Use the SMPP standard 0000xxxx data coding and set the dest_addr_subunit TLV to 1 . |
Note that none of these options have any impact at all for the data coding value for non-flash SMS, which is always set
according to the standard SMPP data coding format of 0000xxxx
.
When processing received messages from the network, all possible flash message schemes are checked.
SMPP TLV Configuration
Default information for SMPP TLVs may be specified within for the SMPP service as a map of TLV set names with TLV definitions within:
"smpp-tlv-sets": {
"<set name>>": [
{
"name": "<TLV name>>",
"tag": <TLV decimal tag>,
"type": "<TLV type>",
"value": "<TLV value>"
}
]
}
Any TLV definitions in the SMPP service are only default values - SMS input may override any, all, or none of the values configured. In any combination, the TLV input and configured TLVs must provide all required fields for a TLV to enable it to be constructed for sending.
Each TLV definition in a TLV set may have the following parameters:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
name |
String | Yes | - | The reference for this TLV when specified in SMS input. |
tag |
Integer | Yes | - | The decimal tag value to set for the TLV, in the range 0..65535 . |
type |
String | Yes | - | The type of TLV. Possible values:
|
value |
String or Integer | No | (none) | The default value of the TLV. For integer TLVs, must be an Integer, otherwise must be a String. |
length |
Integer | Conditional | (none) | The fixed length of the TLV value. For integer TLVs, sets the range of the value . For octets TLV types, the given value must be exactly this long. For cstring TLVs, the given value must be one character less than this to account for the required null suffix. |
min_length |
Integer | Conditional | 0 |
The minimum length of the TLV value, following the rules given for length . |
max_length |
Integer | Conditional | ∞ |
The maximum length of the TLV value, following the rules given for length . |
Note that TLVs of type integer
must have a length defined in some manner. For other TLV types, length constraints are optional.
When TLV length is specified, either length
or one or both of min-length
or max-length
may be used.