Configuration

Overview

The SMS Gateway service is configured in four sections:

• At the root level, general configuration of the SMS Gateway as a whole.
• Under the routes key, the outbound routes to send translated, built short messages.
• Under the correlation key, the configuration for the storage and retrieval of correlation documents.

At a high level, the SMS Gateway configuration can be visualised as:

{
  // General configuration options
  "routes": [
     // Outbound routes to send translated, built short messages.
  ],
  "correlation": {
     // Configuration for correlation document storage and retrieval.
  }
}

General Configuration

The SMS Gateway’s general configuration options are as per the common application configuration parameters.

Route Configuration

Messages received from the JSLEE are processed through configured SMS Gateway routes in the order defined. Transformation and delivery is tried on each matching route’s destinations in order until either the matching routes are exhausted or the generated message (or all messages where segmentation occurs) are delivered.

Routes are examined for delivery in the order defined. The next route is examined if:

• The current route definition does not match the input source-name and source-message-type.
• Any other failure in processing (including delivery failure of any message segment) on the current route.

If all routes are exhausted, the SMS input is rejected with a temporary error.

The destination-addresses parameter creates a dependency for each route - the route will be disabled if there is not at least one instance of this address available and incoming traffic for delivery will not be advertised.

The following configuration options are available for each route in the SMS Gateway routes array:

An example routes configuration might be:

{
  "routes": [
    {
      "destination-addresses": [ "smpp/endpoint1-1", "smpp2/endpoint1" ],
      "destination-message-type": "nz.co.nsquared.slee.smpp.event.SMPPMessageJsonEvent",
      "source-name": "redis/endpoint1",
      "source-message-type": "nz.co.nsquared.slee.redis.JSLEERedisResponse",
      "message-timeout-ms": 500
    },
    {
      "destination-addresses": [ "smpp/endpoint2" ],
      "destination-message-type": "nz.co.nsquared.slee.smpp.event.SMPPMessageJsonEvent",
      "smpp-encoding-set": "alternate"
    }
  ]
}

Correlation Configuration

When translated messages are sent by the SMS Gateway, correlation information is produced in order to report message delivery information. Correlation documents provide information in JSON format on the received input, the sent short message, the received short message acceptance messages, the received delivery status message, and its response.

Correlation information may be kept in either or both of a local cache or an external persistent storage. When a delivery receipt is received, the previous correlation document is retrieved and updated with the delivery receipt’s details before being moved to a final location.

If no correlation configuration is provided, no correlation documents will be produced on message submission and no storage will be used when delivery receipts are received.

When storing correlation documents in Redis, the key used is normally in the format <service name>:[<endpoint name>:]<message ID>, where:

• <service name> is the configured name of the service that received the delivery receipt, and
• <endpoint name>, if present, is the configured name of the endpoint that received the delivery receipt, and
• <message ID> is the protocol-specific value used for unique correlation. For SMPP messages, this is the receipted_message_id parameter.

Correlation key overrides may also be specified in either or both route or additional correlation override configuration.

When storage-service is specified, it creates a dependency. If at least one instance of this service is not available, the SMS Gateway will not start nor process traffic; all routes will be disabled until this dependency (and any route dependencies) are satisfied.

The following correlation configuration options are available for the SMS Gateway:

When specifying persistent storage, either all or none of storage-service, storage-message-type, and storage-complete-name must be specified.

An example correlation section configuration might be:

"correlation": {
  "cache-name": "smsgw",
  "storage-service": "redis",
  "storage-expiry-duration": "P1H",
  "storage-message-type": "nz.co.nsquared.slee.redis.JSLEERedisRequest",
  "storage-complete-name": "complete",
  "error-on-correlation-failure": true,
  "message-timeout-ms": 10000
}

When the cache-name parameter is specified , the cache will only be active if it is also configured in the JSLEE Hazelcast configurationm, e.g.:

    <map name="smsgw">
        <time-to-live-seconds>5</time-to-live-seconds>
        <max-idle-seconds>5</max-idle-seconds>
        <eviction-policy>LRU</eviction-policy>
        <max-size policy="PER_NODE">5000</max-size>
    </map>

For more information on these parameters, refer to the Hazelcast Map documentation. Entries that are found in the cache will not be retrieved from persistent storage as part of correlation processing.

Correlation Override

Instead of using the correlation key defaults when storing or retrieving correlation documents from the cache and/or persistent storage, override values may be used to group logical entities together. When an override is used, the key used becomes <correlation override>:<message ID> instead of using the service and endpoint.

Overrides may be defined at the routes level for use when sending messages, and additional overrides can be specified in the correlation section as required, e.g. when a custom high availability setup is used. Additional correlation key overrides are specified as:

        "correlation": {
            ...
            "additional-correlation-key-overrides": {
                "<override key>": [
                    "<address>",
                    "<address>",
                    ...
                ],
                ...
            }
        },

The addresses used for each key are as defined in route configuration.

Note that, in order to prevent unexpected correlation overrides being applied, the SMS Gateway does not allow:

• Overlaps of route destinations between different correlation override keys (including when no override keys are specified for one of the route).
• Correlation override key specification when no storage (either cache or persistent) is enabled.