EMG 6.0.6 - User's Guide
There are three different possibilities that determines what connector a message will be routed via.
They are (highest priority first):
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.
7.1 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"
7.2 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.
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.
7.2.1 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.
7.3 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), "KEYWORDSESSION", "USERNAME", "URL" and "PLUGINARG".
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.
When using failover/load-balancing a maximum of 16 outgoing connectors can be 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.
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.
7.3.1 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".
Source and destination addresses will also be indeterpreted as regular expressions when preceeded by a "/".
# Match all swedish numbers (destination) ending in "1"
# Match all italian numbers (sender) with 10 digits
# (after country code)
7.3.2 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.
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
^ Starts with
$ Ends with
< Less than
> Greater than
= Equals to
~ Regular expression matching
7.3.3 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 is 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".
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 in routing table:
7.5 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 in routing table:
smpp-in1 smpp-out1,smpp-out2 LB
7.6 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 in appendix.
7.7 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.
7.8 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:
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.
7.8.1 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.
7.8.2 Setting up the connectors
Outgoing connector where we connect to a Nokia SMSC using CIMD2 and receive messages:
CONNECTOR nokia-cimd2 <
# Message format is "<keyword> <rest of message>"
Outgoing connector that forwards messages to a cgi-script that integrates with the application:
CONNECTOR myapp-http <
The "bouncer" connector which sends a message back to the user indicating that an invalid keyword was used:
CONNECTOR bouncer-ebe <
7.8.3 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"
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.
7.8.4 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.
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).
7.9 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.