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": {
        "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 a map of data coding definitions per-set in the following manner:

{
  "encoding-sets": {  
    "<set name>": {
      "segmentation": {
        "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-strategy": "<message encoding strategy>",
      "encoding-supported": {
        "<userdata encoding scheme>": <userdata encoding value>
      },
      "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.

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 determined by the data coding set’s encoding strategy. 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 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. The available encoding schemes are shown under SMPP Encoding Schemes.
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 Object No sar Implementation of message segmentation for outbound messages from this encoding set. The available options for this section are shown under SMPP Segmentation Schemes.
encoding-strategy String No minimise-bytes The encoding strategy to use for encoding scheme selection. The available values are shown under SMPP Encoding Strategies.
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).

The segmentation configuration section has the following configuration items:

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 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 for the set:


{
  "encoding-supported": {
    "gsm7bit-default": 0,
    "ascii": 1,
    "gsm8bit-default": 3,
    "ucs2": 8
  }
}

SMPP Encoding Schemes

The SMS Gateway supports the following output encoding schemes 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).
ucs2 UCS-2 (ISO/IEC 10646-UCS2).
utf8 UTF-8 (ISO/IEC 10646-UTF8).
windows-1252 Windows code page 1252.

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.

SMPP Encoding Strategies

SMPP endpoints support the following output encoding strategies when sending SMPP messages:

Type Description
minimise-bytes Userdata encoding will be chosen from the available encodings to minimise the total amount of bytes sent.
minimise-messages Userdata encoding will be chosen from the available encodings to minimise the total number of messages sent.

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:

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:

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:

Finally, the SMPP standard alternately suggests using the TLV dest_addr_subunit to carry the message class, with the values:

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:
  • integer - an SMPP integer
  • cstring - an SMPP C-Octet string
  • octets - an SMPP Octet string
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 valuemust 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.