Routing - Nordic Messaging

When EMG is used with EMG Portal and the billing plugin, the normal routing described here is overridden.

There are three different possibilities that determine which connector a message will be routed to.

They are (highest priority first):

Any routing criteria specified for a message
Any routing criteria specified for a connector
The routing table

The routing table is definitely the preferred method since it provides functionality for load-balancing, failover and can be changed for a running server without having to restart the server.

Delivery reports (DLRs) are routed a little differently. They are routed back the same way as the original message from which the DLR was requested was received unless a ROUTEDLR keyword is defined on the connector where the DLR is received or if there is a ROUTEDLR keyword specified for the user that requested the DLR.

Specifying a routing criteria for a message

This can be accomplished by using the ROUTE message option. However, it can only be used when using the MGP, HTTP and SMTP protocol to send a message, since CIMD2, SMPP and UCP do not provide mechanisms for setting routing parameters. For example, from the command-line:

emgsend -o ROUTE=cimd2-1 109878 "Test message"

Specifying a routing criteria for a connector

This can be accomplished by using the ROUTE keyword in the server configuration file for a specific connector.

ROUTE=cimd2-1

Please note that the route only affects incoming messages via the connector. Outgoing messages are not affected by the ROUTE keyword since a routing decision has already been made prior to the message being sent via the outgoing connector.

The REDIRECT keyword

Some connectors can only send or received messages (uni-directional) such as SMPP 3.3 or HTTP connectors for example. Say that a DLR is routed back to a HTTP receive-only connector because the original message was received there the DLR would stay in the queue forever (or until it expires). To solve this problem it is possible to specify a REDIRECT keyword on the connector meaning that any message routed to the connector will be redirected to the connector specified by REDIRECT instead.

Routing table

The routing table is loaded from the file pointed to by the ROUTING keyword in the server configuration file.

The format of this file is 2 or 3 tab-separated fields per row:

<name of incoming connector><TAB><name of outgoing connector(s)[<TAB><options>]

Comma “,” is used to separate entries when there is more than one entry per field. The options field is optional and the options currently recognized are “LB” (Load Balancing), “KEYWORD” (see Keyword-based routing below), “WEAKKEYWORD”, “KEYWORDSESSION”, “USERNAME”, “URL”, “PLUGINARG” and “SET” (see section “Setting message options” below).

Example:

smpp-in1  smsc1-ucp
smpp-in2  smsc2-smpp,smsc3-smpp
mgp1      smsc4-ucp,smsc5-ucp    LB

The first line specifies that incoming messages on connector smpp-in1 should be routed to the connector smsc1-ucp, the second line that messages on smpp-in2 should be routed to smsc2-smpp and if it is not available or in state ERROR it should route it via smsc3-smpp (fail-over). Finally the third line is similar to the second line with the exception that if both smsc4-ucp and smsc5-ucp are available load-balancing will take place and outgoing messages will be sent by alternating between the two connectors specified.

The routing table also supports routing on source or destination address prefixes. This can be specified by, in the incoming connector field (the first field) a “<” character (source address) or “>” character (destination address) followed by a prefix. Multiple destination address prefixes can also be supplied in a file when using the “@” character. A “%” character is equivalent to a “>” character (destination address).

Example:

>4670123456               smsc1-ucp
@/etc/emg/smsc2-prefixes  smsc2-smpp
mgp1                      smsc4-ucp,smsc5-ucp  LB

When checking the routing table EMG starts with the first entry and continues down until it finds a matching criteria. The following is an example of a bad routing table where line 2 and 3 will have no effect at all since all entries that match line 2 or 3 also matches line 1 and its position in the file gives it highest precedence.

%0     smsc1-ucp
%012   smsc2-smpp
%0123  smsc3-ucp

Regular expressions

Regular expressions can be used in routing rules, to some extent. An incoming connector (first column) is always considered a regular expression. A connector named “connector1-in” would match all rules below. The last example would match all connector names and can therefore be used a s a “default route”.

connector1-in  connector2-out
connector1.*   connector2-out
.*             connector2-out

Source and destination addresses will also be interpreted as regular expressions when preceeded by a “/”.

# Match all swedish numbers (destination) ending in "1"
>/46.*1         connector-out
# Match all italian numbers (sender) with 10 digits
# (after country code)
</39..........  connector-out

Advanced routing on message options

From EMG 5.2.8 it is possible to route based on any message option, even custom message options (added by plugins for example) by using a leading “?” on the corresponding line in the route table.

?SOURCEADDR$5,0x2001=token1,MESSAGELEN>10  http-out1

The above will route messages where source address ends in “5”, has a message option with key 0x2001 set to “token1” and a message length of more than 10 to connector “http-out1”.

When multiple options are separated with a “,” a logical AND operation will be performed. Message option can be either a name of a MGP option key or the numeric value for the key. The operator can be one of the following.

^	Starts with
$	Ends with
<	Less than
>	Greater than
=	Equals to
~	Regular expression matching

Setting message options

It is possible to modify message options in the routing table by using the keyword “SET:” in field 3. Multiple “SET:” occurrences are allowed.

smpp-in1  smpp-out1  SET:NOTE=route1,SET:0x2001=42

The above example will set the NOTE message option to “route1” and a custom message option with option key 0x2001 to “42”.

Failover

If more than one connector is specified in the routing table and the first connector fails for some reason then the next specified connector is used. This mechanism is called failover. Failover occurs when a connector goes into state ERROR or DEAD and more than one connector is specified. During the failover the queue for the failing connector is moved to the next working connector. If there are no connectors alive at the moment then the queue entries remain in their current connector queue and waits for a connector to come back to life.

Sample configuration entry:

smpp-in1  smpp-out1,smpp-out2

Load balancing

When specifying load balancing for a group of connectors the connectors will be used in a round-robin manner. That is, the first message will be sent via the first specified connector, next message via connector 2 and so on. If a connector is in state ERROR or DEAD it will not be used for the load balancing until it comes back into an active state.

Sample configuration entry:

smpp-in1  smpp-out1,smpp-out2  LB

User-based routing

Routing can be done based on authenticated user by using the ROUTE or ROUTING keywords in the users file. If specified it will override any other routes specified for the connector or in the general routing table. However, message-specific routes will have the highest priority.

Sample users file:

# User-specific routing table
user1  secret  ROUTING=/etc/emg/routing.user1
# User-specific route
user2  secret  ROUTE=cimd2-ep

For more information check general keyword ROUTING and connector keyword USERS.

Routing to a specific user

When multiple clients connect through the same connector in order to receive messages it is important that each user receives only the messages addressed to that specific user and not any other user messages.

It is possible to route messages to a specific user by using the USERNAME keyword in the routing table.

>100  ucp-in  USERNAME=user100
>101  ucp-in  USERNAME=user101

The above will route messages based on destination address prefixes to that messages with a destination address startint with “100” will be routed to user “user100” while destination addresses starting with “101” will be routed to user “user101”.

Please note that users defined as “ADMIN” in the users file will receive all messages regardless of what user the messages are addressed to.

Keyword-based routing

When accessing services via SMS from a mobile device (Mobile Originated or MO messages) it is sometimes useful to make routing decisions based on a keyword in the message. This can be accomplished in different ways. Either all messages can be routed to an EBE connector where a shell script or program can parse the message and take action accordingly or EMG can directly parse the message and route it to different connectors depending on the destination address and a keyword in the message. The second method is more scalable due to the overhead for EBE connectors when creating new processes.

In order to use keyword-based routing in EMG the following is required:

Routing is done via the routing table, there must be no ROUTE keyword on the connector or in the message since they will take precedence.
The keyword must contain letters and digits only.
The option PARSEMESSAGE must be used in the connector configuration where the message is received in order for EMG to be able to extract the keyword correctly.

Please note that after the message has been parsed for the keyword, the keyword will still be a part of the message body and is not removed from the message.

Keywords are case insensitive.

Sample scenario

In a sample scenario we want to set up a service where customers can request their current account balance by sending an SMS to a specific recipient number and including a keyword, “BALANCE”.

Incoming messages, which are received from a Nokia SMSC via CIMD2, should be routed to a HTTP connector that forwards messages including the keyword to a HTTP server which processes the message and takes proper action.

Messages which contain the wrong keyword is bounced to the user with an error message.

Setting up the connectors

Outgoing connector where we connect to a Nokia SMSC using CIMD2 and receive messages:

CONNECTOR nokia-cimd2 <
TYPE=OUTGOING
PROTOCOL=CIMD2
ADDRESS=10.0.0.1:9971
INSTANCES=1
USERNAME=user
PASSWORD=secret
STATIC
KEEPALIVE=60
IDLETIMEOUT=0
# Message format is "<keyword> <rest of message>"
PARSEMESSAGE=KEYWORD MESSAGE
>

Outgoing connector that forwards messages to a cgi-script that integrates with the application:

CONNECTOR myapp-http <
TYPE=OUTGOING
PROTOCOL=HTTP
ADDRESS=http://localhost:8080/cgi-bin/myapp.cgi
INSTANCES=1
>

The “bouncer” connector which sends a message back to the user indicating that an invalid keyword was used:

CONNECTOR bouncer-ebe <
TYPE=OUTGOING
PROTOCOL=EBE
ADDRESS=/usr/local/bin/bouncer.sh
INSTANCES=1
>

Setting up the routing table

The routing table is processed top to bottom which means that we should include the keyword-related entry before any more general entries:

# Route message from everyone incl "BALANCE" to HTTP connector
nokia-cimd2  myapp-http  KEYWORD=*:BALANCE
# Route other messages to "bouncer-ebe"
nokia-cimd2  bouncer-ebe

The keyword KEYWORD takes two arguments, destination address, which can include wildcards, followed by the actual keyword. The keyword can also be a `*’ which represents any keyword.

Keyword sessions

It is possible to use what is called keyword sessions meaning that a specific keyword starts a session and subsequent messages from the same subscriber need not start with the keyword while the session is active. This is particularily useful for chat services and similar.

Sample configuration:

nokia-cimd2  myapp-http  KEYWORD=*:CHAT,KEYWORDSESSION=3600

The argument to the KEYWORDSESSION keyword is the session lifetime in seconds. So, the session lifetime in the above example would be 1 hour (3600 seconds).

Concatenated Message Routing (CMR)

Since SMS are restricted to 160 characters (7-bit text) longer messages can consists of multiple messages which are assembled in the phone to one message, a concatenated message, larger than the 160 character limit. For example this can apply to ringtones, images and WAP push messages.

Sometimes it is necessary to make sure that the different parts of a concatenated message is routed via the same connector. We refer to this as CMR, Concatenated Message Routing.

CMR is enabled per connector using the CMR connector keyword in the server configuration file. Technically CMR checks the message UDH to see if the message is part of a concatenated message.