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.

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:

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:

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:

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:

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:

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:

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:

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:

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:

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, either 0 for GSM 7-bit or 1 for 8-bit. Note that some SMSCs do not support this flag.
• aa is the message class, which will always be set to 00 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 to 0 (uncompressed).
• y is a flag for a defined message class. This will always be set to 1 as a message class is present in the aa bits.
• zz refers to the encoding used: 00 for GSM 7-bit, 01 for 8-bit, or 10 for 16-bit.
• aa is the message class, which will always be set to 00 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.

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:

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.