AMS DocumentationAMS

Routes

Routes are an alternative way to receive AMS messages sent from a mobile. They can be used to transform the content of the message into formats other than XML and can send to different endpoints (currently HTTP and SMTP). A route can be set to run each time a message arrives, after a limit is reached or at scheduled times.

A route consists of 0 or more transformations and a single endpoint. Routes can only be set on root templates but you can have multiple routes per root template.

Types Of Transformations

Transformation Type Description
XML This transformation converts the message content into XML using the configuration information from the template. There are different versions of the XML transformation. Version 1 sets the value of multiple select choice groups to a comma separated list of values inside a single XML tag Version 2 sets the value of multiple select choice groups to multiple XML elements as children under a parent element that has the name set to the external name of the multiple choice group field in the template.
XSL This allows you to apply a XSL transformation to XML content. It can only be used after a XML transformation.
Excel This allows you to create a Microsoft Excel XLS workbook document from a document template. The template itself is create in Excel and you insert special template tags to place the message content. For more information about creating the templates see jXLS .
PDF This transformation allows you to create a PDF document from your message(s). The method used in this transformation is XSL-FO.

Types of Endpoints

Endpoint Type Description
HTTP(S) This endpoint allows you to send message content to any HTTP or HTTPS URL visible from the web. The content is sent in an HTTP POST and is typically used for posting XML content to a web server.
Email / SMTP This endpoint allows to send the message content as an email. The delivery address can either be static or derived from the content of the message itself. The body of the email can contain dynamic content from the message which is set using the FreeMarker template language. If a document transformation has been performed it will be attached to the email.

Types of Routes

There are three types of routes:

  • Standard - this will perform the route each time a message is received
  • Limit - will perform the routes after a certain number have arrived. The limit can be configured.
  • Timer - will perform the route according to a cron expression.

Note that for limit messages the route will fire sometime after the limit is reached and is not guaranteed to fire exactly at the limit.

Timer based routes are configured using a cron expression. A good description of these expressions (as used by the Java library AMS uses to parse them) is here http://www.opensymphony.com/quartz/wikidocs/TutorialLesson6.html (the context of this page is duplicated below in case the link becomes in accessible).

Cron-Expressions

Cron-Expressions are used to configure instances of CronTrigger. Cron-Expressions are strings that are actually made up of seven sub-expressions that describe individual details of the schedule. These sub-expression are separated with white-space, and represent:

  1. Seconds
  2. Minutes
  3. Hours
  4. Day-of-Month
  5. Month
  6. Day-of-Week
  7. Year (optional field)

An example of a complete cron-expression is the string “0 0 12 ? * WED” - which means “every Wednesday at 12:00 pm”.

Individual sub-expressions can contain ranges and/or lists. For example, the day of week field in the previous (which reads “WED”) example could be replaces with “MON-FRI”, “MON, WED, FRI”, or even “MON-WED,SAT”.

Wild-cards (the '’ character) can be used to say “every” possible value of this field. Therefore the '’ character in the “Month” field of the previous example simply means “every month”. A ‘*’ in the Day-Of-Week field would obviously mean “every day of the week”.

All of the fields have a set of valid values that can be specified. These values should be fairly obvious - such as the numbers 0 to 59 for seconds and minutes, and the values 0 to 23 for hours. Day-of-Month can be any value 0-31, but you need to be careful about how many days are in a given month! Months can be specified as values between 0 and 11, or by using the strings JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV and DEC. Days-of-Week can be specified as values between 1 and 7 (1 = Sunday) or by using the strings SUN, MON, TUE, WED, THU, FRI and SAT.

The ‘/’ character can be used to specify increments to values. For example, if you put ‘0/15’ in the Minutes field, it means ‘every 15 minutes, starting at minute zero’. If you used ‘3/20’ in the Minutes field, it would mean ‘every 20 minutes during the hour, starting at minute three’ - or in other words it is the same as specifying ‘3,23,43’ in the Minutes field.

The ‘?’ character is allowed for the day-of-month and day-of-week fields. It is used to specify “no specific value”. This is useful when you need to specify something in one of the two fields, but not the other. See the examples below (and CronTrigger JavaDoc) for clarification.

The ‘L’ character is allowed for the day-of-month and day-of-week fields. This character is short-hand for “last”, but it has different meanings in each of the two fields. For example, the value “L” in the day-of-month field means “the last day of the month” - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means “7” or “SAT”. But if used in the day-of-week field after another value, it means “the last xxx day of the month” - for example “6L” or “FRIL” both mean “the last Friday of the month”. When using the ‘L’ option, it is important not to specify lists, or ranges of values, as you’ll get confusing results.

The ‘W’ is used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify “15W” as the value for the day-of-month field, the meaning is: “the nearest weekday to the 15th of the month”.

The ‘#’ is used to specify “the nth” XXX weekday of the month. For example, the value of “6#3” or “FRI#3” in the day-of-week field means “the third Friday of the month”.

Here are a few more examples of expressions and their meanings - you can find even more in the JavaDoc for CronTrigger Example Cron Expressions

CronTrigger Example 1 - an expression to create a trigger that simply fires every 5 minutes

“0 0/5 * * * ?”

CronTrigger Example 2 - an expression to create a trigger that fires every 5 minutes, at 10 seconds after the minute (i.e. 10:00:10 am, 10:05:10 am, etc.).

“10 0/5 * * * ?”

CronTrigger Example 3 - an expression to create a trigger that fires at 10:30, 11:30, 12:30, and 13:30, on every Wednesday and Friday.

“0 30 10-13 ? * WED,FRI”

CronTrigger Example 4 - an expression to create a trigger that fires every half hour between the hours of 8 am and 10 am on the 5th and 20th of every month. Note that the trigger will NOT fire at 10:00 am, just at 8:00, 8:30, 9:00 and 9:30

“0 0/30 8-9 5,20 * ?”

Extra Options

You can optionally specify a direction for a route. This controls when a route is applied. Routes with direction ‘IN’ will apply to messages received form a mobile and ones with direction ‘OUT’ will apply to messages sent to a mobile.

Message Details

There is an option to include message details. This put details of the mobile account used to create the message as well as extra information about the message into the routing context. This is useful when processing batches of messages as you can group on mobile account. The extra data will be placed in the Map containing the main message data under the key ‘messageDetails’ and the internal AMS id of the message will be set with key ‘_id’. The messages details value will be a Java Map with the following keys and values:

Key Value
id message id (uuid format)
replyToId The id this message is a reply to. May not be set.
username The username of the Mobile Account used to send this message.
displayName The display name of the Mobile Account used to send this message. Available if set in the Mobile Account
creationDate The Java Date of the time this message was created at the AMS Gateway. Available if not null. Will be in UTC time.
sentFromDevice The Java Date of the time this message was sent from the users phone. Available if not null. Will be in UTC time.
deliveredDateTime The Java Date of the time this message was downloaded to the users phone. Available if not null. Will be in UTC time.
resent A Java Boolean indicating if this was a resent message
tags A Java List containing the Tags associated with the Mobile Account used to send this message.
latitude A Java Long indicating the latitute this message was sent from. May not be set.
longitude A Java Long indicating the longitude this message was sent from. May not be set.
altitude A Java Long indicating the altitude this message was sent from. May not be set.