SMPP Device Engines

SMPP Device Engines enable xMatters to send text notifications to and receive text responses from service providers using the Short Message Peer-to-Peer (SMPP) protocol. This protocol involves communicating via SMS-based messages on text-enabled mobile phones. xMatters supports SMPP version 3.4 only.

For most protocols, the connection is transient, and each notification contains the required provider information. SMPP providers are different in that they require that connections are constantly established. In xMatters, this means that the provider configuration must be performed at the Device Engine level, rather than the Protocol Provider level.

The xMatters SMPP Device Engines support SMS short codes. For information about HELP and STOP codes and best practices, see Constants.

Note: SMPP Device Engines are single-threaded.

By default, SMPP Device Engines can handle only one socket connection. You can manually configure the number of socket connections handled by the SMPP Device Engine by editing the configuration file.

To set the number of SMPP socket connections:
  1. On the xMatters server, open the <xMHOME>/node/assets/resources/spring/integration/deSmppContext.xml file.
  2. Locate the smppConfigurationAgent bean, and change the value for the numberConnections setting from 1 to the maximum number of connections that the SMPP Service Provider allows.
  3. Save and close the file.
  4. Restart the web server.

SMPP Device Engine Details

Many of the settings required for the SMPP Device Engine may be specified by your SMPP service provider.

SMPP Device Engine details

Detail

Description

Name

Name used to identify this Device Engine.

Description

Brief description of this Device Engine (optional).

Notification Polling

How often (in seconds) the Device Engine polls the notification node for new alerts. Must be a whole number greater than or equal to 10 and less than or equal to 300.

Logging

For an explanation of Device Engine logging, see Enabling Device Engine logging.

Server Address

IP address of the SMPP server to which xMatters should connect.

Server Port

TCP/IP port used to connect to the SMPP server.

Connection Mode

Specifies how the Device Engine should connect to the SMPP provider. Select Tranceiver to send and receive messages over the same connection, or select Transmitter/Receiver to use separate connections for sending and receiving.

System ID

Account ID provided by your SMPP service provider.

System Password

If required, the password for your SMPP account ID.

System Type

If required, the system type parameter provided by your SMPP provider.

Address Range

Range of addresses to use for SMPP messages, if provided by your SMPP service provider.

Address Range TON

Type Of Number (TON) required for the address range as supplied by your service provider.

Address Range NPI

Numbering Plan Identity (NPI) required for the address range as supplied by your service provider.

Source Address

Number associated with your SMPP account; used to indicate the sender for outgoing messages. This setting may be overridden by the Source Address setting on the SMPP Protocol Provider details.

Source Address TON

Your SMPP account’s TON to be used during the server session. This setting may be overridden by the Source Address setting on the SMPP Protocol Provider details.

Source Address NPI

Client’s NPI required by your service provider for the source address. This setting may be overridden by the Source Address setting on the SMPP Protocol Provider details.

Default Dest Address TON

TON required by your service provider for the default destination address. This setting may be overridden by the Source Address setting on the SMPP Protocol Provider details.

Default Dest Address NPI

NPI required by your service provider for the default destination address. This setting may be overridden by the Source Address setting on the SMPP Protocol Provider details.

Session Timeout

Length of time in minutes before the session times out. To have every session time out, enter ‘0’. To have sessions never time out, enter a negative value.

Notification Key

String included in the body of the notification that identifies the original alert or notification to which the User is responding.

Normally this key is enclosed with delimiting characters; e.g., the default value, <%Notification Key%>.

If the delimiting character sequence is not guaranteed to be unique, the Device Engine may make an incorrect match, causing an exception and response failure.

If no delimiters are present, the first word of the response will be used as the notification key. If the delimiters occur more than once in the body of the notification, the first instance is used as the notification key.

If you have configured simple SMS replies, as described in Configuring simple SMS replies, this field is disabled.

For more information about how xMatters handles SMS messages, see the section, "Configuring SMS messages and replies".

Response Key

String included in the body of the notification that identifies the beginning of the response portion of the User’s return message.

If you have configured simple SMS replies, as described in Configuring simple SMS replies, this field is disabled.

Choice Message

Portion of notification message describing the User’s response options.

If you have configured simple SMS replies, as described in Configuring simple SMS replies, this field is disabled.

Response Message

Instructions to the recipient on how to respond to the notification.

If you have configured simple SMS replies, as described in Configuring simple SMS replies, this field should be changed to reflect the new response process. The recommended value is "Reply %RESPONSE CHOICES%".

Enquire Interval

Time in seconds between enquire packets sent to the SMPP service provider. Value must be a multiple of 10, and cannot be less than 10 seconds.

Support Status Report

Specifies whether the Device Engine should support incoming status reports from service providers. When enabled, the status reports are displayed in the xMatters Exhaustive Reports and recorded in the Node log.

Message ID Location or Delimiter

Indicates a method to identify the message ID within the incoming status report. This value can be expressed in one of three ways:

  • <location>–<length>: indicates the starting position and length of the message ID within the status report; e.g., 46–10.
  • <delimiter>: indicates the delimiter that identifies the message ID; e.g., mess_id:.
  • <delimiter> (<length>): indicates the delimiter that identifies the message ID, and the expected length of the ID; e.g., the default setting, id: (10).

Status Location or Delimiter

Indicates a method to identify the status of the notification within the incoming status report. This value can be expressed in the same three ways as the Message ID Location or Delimiter field; the default value is stat: (7).

Error Code Location or Delimiter

Indicates how to identify the error code within the incoming status report. This value can be expressed in the same three ways as the Message ID Location or Delimiter field; the default value is
err: (3).

Delivery Word

Specifies the Status string value within the incoming status report that indicates the notification message was delivered to the recipient’s Device; the default is DELIVRD.

Read Word

Specifies the Status string value within the incoming status report that indicates the notification message was read by the recipient.

Failed Word

Specifies a list of Status string values within the incoming status report that indicate the notification message has failed; the default list is EXPIRED;DELETED;UNDELIV;UNKNOWN. Note that list values must be delimited with semi-colons.