C.2 SMS Channel Theory of Operation

The SMS channel is a multi-threaded channel which converts queued email messages to SMS messages and then submits them for delivery to an SMSC.

The following channel operation topics are covered in this section:

• C.2.1 Directing Email to the Channel.

• C.2.2 The Email to SMS Conversion Process.

• C.2.3 The SMS Message Submission Process.

• C.2.4 Site-defined Address Validity Checks and Translations

• C.2.5 Site-defined Text Conversions

C.2.1 Directing Email to the Channel

When the SMS channel is configured as per C.3 SMS Channel Configuration purposes of discussion, let us assume that the host name sms.siroe.com is a host name associated with the channel. In that case, email is directed to the channel with an address of the form:

local-part@sms.siroe.com

in which local-part is either the SMS destination address (for example, a wireless phone number, pager ID, etc.) or an attribute-value pair list in the format:

/attribute1=value1/attribute2=value2/.../@sms.siroe.com

The recognized attribute names and their usages are given in Table C–1. These attributes allow for per-recipient control over some channel options.

Some example addresses:

123456@sms.siroe.com
/id=123456/@sms.siroe.com
/id=123456/maxlen=100/@sms.siroe.com
/id=123456/maxpages=1/@sms.siroe.com

For information on performing translations, validity checks, and other operations on the SMS destination address portion of the email address, see C.2.4 Site-defined Address Validity Checks and Translations

C.2.2 The Email to SMS Conversion Process

In order for email to be sent to a remote site, email must be converted to SMS messages that can be understood by the remote SMSCs. This section describes the process of converting an email message queued to the SMS channel to one or more SMS messages. As described below, options allow control over the maximum number of SMS messages generated, the maximum total length of those SMS messages, and the maximum size of any single SMS message. Only text parts (that is, MIME text content types) from the email message are used and the maximum number of parts converted may also be controlled.

Character sets used in the email message’s header lines and text parts are all converted to Unicode and then converted to an appropriate SMS character set.

When there is no SMS_TEXT mapping table (see C.2.5 Site-defined Text Conversions) an email message queued to the SMS channel receives the processing illustrated in Figure C–2.

Figure C–2 SMS Channel Email Processing

Figure C–3 SMS Channel Email Processing (continued)

The following steps correspond to the numbered boxes in Figure C–2:

1. An empty output buffer is started. The character set used for the buffer is Unicode.

2. The email message’s originator address is taken from one of the following five sources, shown in decreasing order of preference:

   1. Resent-from: 2. From: 3. Resent-sender: 4. Sender: 5. Envelope From:

   If the originator address is an empty string, then the value of the FROM_NONE channel option is instead appended to the buffer.

   If, however, the originator address is a non-empty string, then the result of processing the FROM_FORMAT channel option, and the value of the LINE_STOP channel option are appended to the output buffer.

   Note that the Resent-from: and Resent-sender: header lines are only considered if the USE_HEADER_RESENT option has the value 1. Otherwise, Resent- header lines are ignored.

3. If a Subject: header line is not present or is empty, then the value of the SUBJECT_NONE option is appended to the output buffer.

   Otherwise, the result of processing the SUBJECT_FORMAT option, and the value of the LINE_STOP channel option are appended to the output buffer.

4. If there are no text message parts, then the value of the NO_MESSAGE channel option is appended to the output buffer.

   If there are text message parts, then the value of the CONTENT_PREFIX channel option is appended to the output buffer.

   Non-text message parts are discarded.

5. For each text part, while the MAX_MESSAGE_PARTS limit has not been reached, the text part is decoded to Unicode and appended to the buffer, along with the value of the LINE_STOP channel option.

6. The resulting output buffer is then converted from Unicode to either the SMSC’s default character set or UCS2 (UTF-16). The SMSC’s default character set is specified with the SMSC_DEFAULT_CHARSET option.

7. After being converted, it is then truncated to not exceed MAX_MESSAGE_SIZE bytes.

8. The converted string from C.2.2 The Email to SMS Conversion Process is then broken into one or more SMS messages, no single SMS message longer than MAX_PAGE_SIZE bytes. At most, MAX_PAGES_PER_MESSAGE SMS messages will be generated.

   ---

   Note –

   As an email message may have multiple recipients, Step 6 through Step 8 may need to be done for each recipient address which makes use of the MAXLEN, MAXPAGES, or PAGELEN attributes described in “Directing Email to the Channel,” on page 4.

   ---

C.2.2.1 Sample Email Message Processing

For example, with the channel’s default settings, the email message:

From: John Doe 
To: 1234567@sms.siroe.com
Subject: Today’s meeting
Date: Fri, 26 March 2001 08:17

The staff meeting is at 14:30 today in the big conference room.

Would be converted to the SMS message:

jdoe@siroe.com (Today’s meeting) The staff meeting is at 14:30 today in the big conference room.

A different set of option settings, that follows:

CONTENT_PREFIX=Msg:
FROM_FORMAT=From:${pa}
SUBJECT_FORMAT=Subj:$s

would instead produce:

From:John Doe Subj:Today’s meeting Msg:The staff meeting is at 14:30 today in the big conference room.

C.2.3 The SMS Message Submission Process

Once an email message has been converted to one or more SMS messages, with possibly different sets for each recipient, the SMS messages are then submitted to the destination SMSC. The submissions are effected using SMPP V3.4 over TCP/IP. The hostname (SMPP_SERVER) of the SMPP server is taken to be the official host name associated with the SMS channel; the TCP port (SMPP_PORT) to use is specified with the port channel keyword.

When there are messages to process, the channel is started. The channel binds to the SMPP server as a transmitter, presenting the credentials specified with the ESME_ channel options described in C.3.3.4 SMPP Options. Table C–2 lists the fields set in a BIND_TRANSMITTER PDU (Protocol Data Unit), and gives their values:

Note that the channel is multithreaded. Depending on how much mail there is to send, the channel may have multiple dequeue thread running. (There can even be multiple channel processes running.) Each thread does a BIND_TRANSMITTER and then on that TCP/IP connection, sends all of the SMS messages it has to send, and then sends an UNBIND, and then closes the connection. No attempt is made to hold a connection open for a period of idle time for potential reuse. If the remote SMPP server sends back a throttle error, then an UNBIND is issued, the TCP/IP connection is closed, and a new connection and BIND established. It behaves similarly if the remote SMPP server sends an UNBIND before it is finished sending its SMS messages.

The SMS messages are then submitted using SMPP SUBMIT_SM PDUs. If a permanent error is returned (for example, ESME_RINVDSTADR), then the email message is returned as undeliverable. If a temporary error is returned, then the email message is re-enqueued for a later delivery attempt. To clarify, a permanent error is one for which the condition is likely to exist indefinitely and for which repeated delivery attempts will have no positive effect, such as invalid SMS destination addresses. Whereas, a temporary error is one for which the condition is likely to not exist in the near future, such as a server down or server congested condition.

If the USE_HEADER_FROM option has the value 1, then the source address for the submitted SMS message is set. The value used is derived from the originating email message and is chosen to be the most likely (email) address to which any replies should be directed. Accordingly, the source address taken from one of the following seven sources, shown in decreasing order of preference:

1. Resent-reply-to:
2. Resent-from:
3. Reply-to:
4. From:
5. Resent-sender:
6. Sender:
7. Envelope From:

Note that the Resent-reply-to: and Reply-to: header lines are only considered if the USE_HEADER_REPLY_TO option has the value 1. Moreover, the Resent-reply-to:, Resent-from:, and Resent-sender: header lines are only considered if the USE_HEADER_RESENT option has the value 1. (Note that this means that both of those options must have the value 1 for the Resent-reply-to: header line to be considered.) The default value for both of these options is the value 0. As such, only items 4, 6, and 7 are considered by the default configuration. Finally, since the source address in an SMS message is limited to 20 bytes, the source address chosen will be truncated if it exceeds that limit.

Table C–3 shows the mandatory fields set in a SUBMIT_SM PDU:

Table C–4 shows the optional fields in a SUBMIT_SM PDU:

The channel remains bound to the SMPP server until either it has no more SMS messages to submit (the message queue is empty), or MAX_PAGES_PER_BIND has been exceeded. In the latter case, a new connection is made and bind operation performed if there remain further SMS messages to send.

Note that the SMS channel is multithreaded. Each processing thread in the channel maintains its own TCP connection with the SMPP server. For example, if there are three processing threads each with SMS messages to submit, then the channel will have three open TCP connections to the SMPP server. Each connection will bind to the SMPP server as a transmitter. Moreover, any given processing thread will only have one outstanding SMS submission at a time. That is, a given thread will submit an SMS message, then wait for the submission response (that is, SUBMIT_SM_RESP PDU) before submitting another SMS message.

C.2.4 Site-defined Address Validity Checks and Translations

Sites may wish to apply validity checks or translations to SMS destination addresses encoded in the recipient email addresses described in C.2.1 Directing Email to the Channel

• Strip non-numeric characters (for example, translating 800.555.1212 to 8005551212)

• Prepend a prefix (for example, translating 8005551212 to +18005551212)

• Validate for correctness (for example, 123 is too short)

The first two tasks can be done specifically with the DESTINATION_ADDRESS_NUMERIC and DESTINATION_ADDRESS_PREFIX channel options. In general, all three of these tasks, and others can be implemented using mapping tables: either mapping table callouts in the rewrite rules or by means of a FORWARD mapping table. Using a mapping table callout in the rewrite rules will afford the most flexibility, including the ability to reject the address with a site-defined error response. The remainder of this section will focus on just such an approach -- using a mapping table callout from the rewrite rules.

Let us suppose that destination addresses need to be numeric only, be 10 or 11 digits long, and be prefixed with the string “+1”. This can be accomplished with the following rewrite rule

sms.siroe.com      ${X-REWRITE-SMS-ADDRESS,$U}@sms.siroe.com
sms.siroe.com       $?Invalid SMS address

The first rewrite rule above calls out to the site-define mapping table named X-REWRITE-SMS-ADDRESS. That mapping table is passed the local part of the email address for inspection. If the mapping process decides that the local part is acceptable, then the address is accepted and rewritten to the SMS channel. If the mapping process does not accept the local part, then the next rewrite rule is applied. Since it is a $? rewrite rule, the address is rejected with the error text “Invalid SMS address”.

The X-REWRITE-SMS-ADDRESS mapping table is shown below. It performs the necessary validation steps for local parts in either attribute-value pair list format or just a raw SMS destination address.

X-VALIDATE-SMS-ADDRESS

! Iteratively strip any non-numeric characters 
   $_*$[$ -/:-~]%*  $0$2$R
! Accept the address if it is of the form 1nnnnnnnnnn or nnnnnnnnnn
! In accepting it, ensure that we output +1nnnnnnnnnn
   1%%%%%%%%%%      +1$0$1$2$3$4$5$6$7$8$9$Y
   %%%%%%%%%%       +1$0$1$2$3$4$5$6$7$8$9$Y
! We didn’t accept it and consequently it’s invalid
   *                $N

X-REWRITE-SMS-ADDRESS
    */id=$_*/*       $C$0/id=$|X-VALIDATE-SMS-ADDRESS;$1|/$2$Y$E
    */id=$_*/*       $N
    *                $C$|X-VALIDATE-SMS-ADDRESS;$0|$Y$E
    *                $N

With the above set up, be sure that DESTINATION_ADDRESS_NUMERIC option has the value 0 (the default). Otherwise, the “+” will be stripped from the SMS destination address.

C.2.5 Site-defined Text Conversions

Sites may customize Steps 1 - 6 described in C.2.2 The Email to SMS Conversion Process a mapping table in the MTA’s mapping file.

The name of the mapping table should be SMS_Channel_TEXT where SMS_Channel is the name of the SMS channel; for example, SMS_TEXT if the channel is named sms or SMS_MWAY_TEXT if the channel is named sms_mway.

Two types of entries may be made in this mapping table. However, before explaining the format of those entries, let it be made clear that an understanding of how to use the mapping file is essential in order to understand how to construct and use these entries. An example mapping table is given after the description of these two types of entries.

Now, the two types of entries are:

• C.2.5.1 Message Header Entries

• C.2.5.2 Message Body Entries

C.2.5.1 Message Header Entries

These entries specify which message header lines should be included in an SMS message and how they should be abbreviated or otherwise converted. Only if a header line is successfully mapped to a string of non-zero length by one of these entries will it be included in the SMS message being generated. Each entry has the format

H|pattern replacement-text

If a message header line matches the pattern then it will be replaced with the replacement text replacement-text using the mapping file’s pattern matching and string substitution facilities. The final result of mapping the header line will then be included in the SMS message provided that the metacharacter $Y was specified in the replacement text. If a header line does not match any pattern string, if it maps to a string of length zero, or if the $Y metacharacter is not specified in the replacement text, then the header line will be omitted from the SMS message. The two entries

H|From:* F:$0$Y 
H|Subject:* S:$0$Y

cause the From: and Subject: header lines to be included in SMS messages with From: and Subject: abbreviated as F: and S:. The entries:

H|Date:* H|D:$0$R$Y 
H|D:*,*%19%%*:*:* H|D:$0$ $5:$6$R$Y

cause the Date: header line to be accepted and mapped such that, for instance, the header line

Date: Wed, 16 Dec 1992 16:13:27 -0700 (PDT)

will be converted to

D: Wed 16:13

Very complicated, iterative mappings may be built. Sites wishing to set up custom filters will first need to understand how the mapping file works. The H| in the right-hand-side of the entry may be omitted, if desired. The H| is allowed in that side so as to cut down on the number of table entries required by sets of iterative mappings.

C.2.5.2 Message Body Entries

Body mappings are not supported.

C.2.5.3 Example SMS Mapping Table

An example SMS_TEXT mapping table is shown in Example C–1. The numbers inside parentheses at the end of each line correspond to the item numbers in the section titled Explanatory Text that follows this table.

Example C–1 Example SMS_TEXT Mapping Table.

SMS_TEXT

   H|From:*        H|F:$0$R$Y       (1)
   H|Subject:*     H|S:$0$R$Y       (1)
   H|F:*<*>*       H|F:$1$R$Y       ()
   H|F:*(*)*       H|F:$0$2$R$Y     (2)
   H|F:*"*"*       H|F:$0$2$R$Y     (3)
   H|F:*@*         H|F:$0$R$Y       (4)
   H|%:$ *         H|$0:$1$R$Y      (5)
   H|%:*$          H|$0:$1$R$Y      (5)
   H|%:*$ $ *      H|$0:$1$ $2$R$Y  (6)
   B|*--*          B|$0-$1$R        (7)
   B|*..*          B|$0.$1$R        (7)
   B|*!!*          B|$0!$1$R        (7)
   B|*??*          B|$0?$1$R        (7)
   B|*$ $ *        B|$0$ $1$R       (6)
   B|$ *           B|$0$R           (5)
   B|*$            B|$0$R           (5)

               

Explanatory Text

The entries in the example SMS_TEXT mapping table above are explained below:

In the example above, the metacharacter $R is used to implement and control iterative application of the mappings. By iterating on these mappings, powerful filtering is achieved. For instance, the simple mappings to remove a single leading or trailing space (6) or reduce two spaces to a single space (7) become, when taken as a whole, a filter which strips all leading and trailing spaces and reduces all consecutive multiple spaces to a single space. Such filtering helps reduce the size of each SMS message.

1. These two entries cause From: and Subject: header lines to be included in an SMS message. From: and Subject: are abbreviated as, respectively, F: and S:. Some of the other entries may have further effects on From: and Subject: header lines.

   This entry will reduce a From: header line containing a <...> pattern to only the text within the angle brackets. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: jdoe@siroe.com

2. This entry will remove, inclusively, everything inside of a (...) pattern in a From: header line. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: "John C. Doe" <jdoe@siroe.com>

3. This entry will remove, inclusively, everything inside of a “...” pattern in a From: header line. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: <jdoe@siroe.com> (Hello)

4. This entry will remove, inclusively, everything to the right of an at-sign, @, in a From: header line. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: "John C. Doe" <jdoe@

5. These four entries remove leading and trailing spaces from lines in the message header and body.

6. These two entries reduce two spaces to a single space in lines of the message header and body.

7. These four entries reduce double dashes, periods, exclamation and question marks to single occurrences of the matching character. Again, this helps save bytes in an SMS message.

The order of the entries is very important. For instance, with the given ordering, the body of the message From: header line:

From: "John C. Doe" (Hello)

will be reduced to:

jdoe

The steps taken to arrive at this are as follows:

1. We begin with the From: header line:

   From: "John C. Doe" (Hello)

   The pattern in the first mapping entry matches this and produces the result:

   F: "John C. Doe" (Hello)

   The $R metacharacter in the result string causes the result string to be remapped.

2. The mapping is applied to the result string of the last step. This produces:

   F: jdoe@siroe.com

   The $R in the mapping causes the entire set of mappings to be re-applied to the result of this step.

3. Next, the mapping is applied producing:

   F: jdoe

   The $R in the mapping causes the entire set of mappings to be re-applied to the result of this step.

4. Next, the mapping is applied producing:

   F:jdoe

   The $R in the mapping causes the entire set of mappings to be re-applied to the result of this step.

5. Since no other entries match, the final result string:

   F:jdoe

   is incorporated into the SMS message.

   ---

   Note –

   The imsimta test-mapping utility may be used to test a mapping table. For instance,

   # imsimta test -mapping -noimage_file -mapping_file=test.txt Enter table name: SMS_TEXT Input string: H|From: "John C. Doe" (Hello) Output string: H|F:jdoe Output flags: [0,1,2,89] Input string: ^D #

   For further details on the imsimta test utility, see imsimta test in Sun Java System Messaging Server 6.3 Administration Reference.

   ---