Functions Indexed by Name

Returns a date that is a specified number of days in the future (the integer value) from the timestamp. For example, the expression:

${af:addDay("1955-09-28 01:00:10",20)}

returns the value 1955-10-18.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: string

Adds the specified number of hours (integer) to the timestamp. The timestamp must be in the format yyyy-MM-dd HH:mm:ss. For example:

${af:addHour("2012-09-28 08:01:57", 12)}

returns 2012-09-28 20:01:57.

Type: string

Adds the specified number of minutes (integer) to the timestamp. The timestamp must be in the format yyyy-MM-dd HH:mm:ss. For example:

${af:addMinute("2012-09-28 08:01:57", 15)}

returns 2012-09-28 08:16:57.

Type: string

This function calculates a percentage from two inputs.

The function divides integer-A by integer-B, multiplies the value by 100, then rounds the value to the nearest integer. It appends the value with the percentage mark. For example, the expression:

${af:calculatePercentage(50,150)} 

would return the value 33%.

Type: string

Rounds a number up to the nearest integer, but returns this as a floating point number to one decimal point. For example: ${af:ceil(4.33)} would return 5.0.

Type: floating-point number

This function compares two dates and returns the value true if input-A is before or the same date as input-B. The value false is returned otherwise. The two dates must use the format yyyy-MM-dd. For example, to see whether an end user began using your services before the start of 2015, use the expression:

${af:compareDate(user.addDate,"2014-12-31")}

• If user.addDate is 2015-01-01 or later (e.g. 2016-02-04), then the function returns false.
• If user.addDate is 2014-12-31 or earlier, then the function returns true.

Type: Boolean

Concatenates the two strings and returns the results. For example: ${af:concat("Open", "Market")} returns OpenMarket.

Type: string

Checks whether the string-original contains the string-matching; if it does, then it returns the value true. This function is case sensitive.

For example:

${af:contains("OpenMarket", "Mark")}

returns true as "Mark" is in the string "OpenMarket". However:

${af:contains("OpenMarket", "   mark ")}

would return false for either of these reasons:

• The "m" is now lowercase
• There is no whitespace in the string "OpenMarket"

Type: Boolean

Returns the MEP system time in milliseconds since midnight 01 January 1970. There is no input required in the parentheses; however, you must still include them.

Type: integer

Returns the number of days between the two dates.

For example:

${af:daysBetween("2012-09-05", "2012-09-28" )}

would return 23.

Note that if date-A is a later date than date-B, then a negative number is returned.

The date format can be either:

• yyyy-MM-dd hh:mm:ss
• yyyy-MM-dd

Type: integer

Compares the two strings while disregarding their case. If the strings match, the function returns the value true. The value false is returned otherwise.

For example, you could use it in a competition service to see whether an end user correctly answered "cat" (ignoring the case):

${af:equalsIgnoreCase(session.initialMessage.strippedMessage, "cat")}

Type: Boolean

Rounds a number down to the nearest integer, but returns this as a floating point number to one decimal point. For example: ${af:floor(7.9)} would return 7.0.

Type: floating-point number

This function turns a standard MEP date or timestamp into the date format specified by the pattern. The pattern must use the characters d, M, and y (case-sensitive) to specify the sequence of day, month and year. This string must be surrounded in double quote marks. You can include some additional characters in the pattern, for example hyphens or the forward slash.

For example, the following expression would turn the timestamp specified by the variable user.addDate into the format dd/MM/yyyy:

${af:formatDateString(user.addDate,"dd/MM/yyyy")}

Note that standard MEP date or timestamps are:

• yyyy-MM-dd
• yyyy-MM-ddTHH:mm:ssTZD or yyyy-MM-dd HH:mm:ssTZD
• yyyy-MM-ddTHH:mm:ssZ or yyyy-MM-dd HH:mm:ssZ
• yyyy-MM-ddTHH:mm:ss or yyyy-MM-dd HH:mm:ss

Type: string

Formats a floating point number or an integer as a percentage. It assumes that the number has already been calculated as a percentage. The number is also rounded to the nearest integer. For example: ${af:formatPercentage(14.87)} would return 15%.

Type: string

Converts a Unix timestamp into GMT time. The converted format is yyyy-MM-dd hh:mm:ss.

It is assumed that the Unix timestamp is in seconds, unless the value is greater than 20,000,000,000, in which case MEP treats the value as a timestamp in milliseconds.

Unix timestamps that are negative numbers will produce indeterminate results.

Type: string

Converts a Unix timestamp into a timezone of your choice. The converted format is yyyy-MM-dd hh:mm:ss. The timezone codes you can use are those in the IANA Time Zone Database.

The format for timezoneID is "Continent/City" or abbreviations such as "GMT" ; e.g.:

af:fromUnixTimeTZ(305382600, "Asia/Tokyo")

Note that in this database, "BST" is not "British Standard Time" but instead "Bangladesh Standard Time".

It is assumed that the Unix timestamp is in seconds, unless the value is greater than 20,000,000,000, in which case MEP treats the value as a timestamp in milliseconds.

Unix timestamps in negative numbers will produce indeterminate results.

Type: string

Converts a Unix timestamp into a US timezone of your choice. The converted format is yyyy-MM-dd hh:mm:ss.

The values you can use for usTimeZone are: Samoa, Aleutian, Hawaii, Alaska, Pacific, Pacific-New, Arizona, Mountain, Central, Indiana-Starke, East-Indiana, Eastern, Michigan. For example:

af:fromUnixTimeUS(305382600, "Pacific-New")

It is assumed that the Unix timestamp is in seconds, unless the value is greater than 20,000,000,000, in which case MEP treats the value as a timestamp in milliseconds.

Unix timestamps in negative numbers will produce indeterminate results.

Type: string

Generates the MD5 hash for a string. For example: ${af:generateMD5Hash(12515550100)} would return 99c69893efc6a57c7893c1315f597549.

Type: string

Generates a random PIN. The integer value specifies the length of the PIN, while the Boolean value (either true or false) determines whether the PIN is an alphanumeric string (true) or an integer (false).

Example expressions and values:

• Expression: ${af:generatePin(10,true)}
  Example value: ABR4K3DBR9
• Expression: ${af:generatePin(6,false}
  Example value: 938533

Type: string, integer

Returns the number of years since the date. This function is ideal for determining an end users age if they have provided their date of birth, or the years since a specific event.

For example, if the current date is between Feb-Dec in 2012, then this function would return 33:

${af:getAge("1979-01-31")}

The date format can be either:

• yyyy-MM-dd hh:mm:ss
• yyyy-MM-dd

Type: integer

Retrieves the day of the month from the timestamp. For example, the expression:

${af:getDay("1955-09-28 01:00:10")} 

returns the value 28.

This function is synonymous with getDayOfMonth(timestamp).

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

This function is synonymous with getDay(timestamp).

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Retrieves the day of the week from the timestamp, where Sunday is equal to the value 1, Monday is equal to 2, etc. For example, the following expression is for a Wednesday:

${af:getDayOfWeek("1955-09-28 01:00:10")}

This returns the value 4.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Returns the day of the year from the timestamp. This value will be between 1 (representing January 1st) and 365 (or 366 during a leap year). For example, the expression:

${af:getDayOfYear("2007-02-02 13:00:00")}

returns with the value 33.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Retrieves the hour from the timestamp. For example, the expression

${af:getHour("1979-05-30 02:32:45")} 

returns with the value 2.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Retrieves the minute from the timestamp. For example, the expression:

${af:getMinute("1979-05-30 02:32:45")}

returns with the value 32.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Retrieves the number of the month from the timestamp. For example, the expression

${af:getMonth("2009-09-30 07:35:21")} 

returns with the value 9.

Type: integer

Retrieves the full name of the day for the timestamp. For example, the expression:

${af:getNameOfDay("1955-09-28 01:00:10")}

returns the value Wednesday.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: string

Returns with the full name of the month from the timestamp. For example, the expression:

${af:getNameOfMonth("2009-09-30 07:35:21")} 

returns with the value September.

Type: string

Returns a date in the format yyyy-MM-dd representing the next day of the week from the specified date. For example, in the following expression, the timestamp is for a Friday, and the expression is asking for the next Wednesday:

   ${af:getNextWednesday("2013-02-22 13:00:00")}

The expression returns the value 2013-02-27.

This function will return the same date if the supplied timestamp is the same day of the week, for example:

${af:getNextFriday("2013-02-22 13:00:00")}

returns with 2013-02-22, as the specified timestamp is for a Friday.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: string

The function reads the specified input and attempts to extract a UK MSISDN. The function will look for mobile numbers beginning with either the number zero or the UK international prefix (44, 0044, +44). It will output the first matching number.

This function is commonly used to extract a number out of SMS message text, for example:

${af:getPhoneNumber(request.defaultMessage)}

The output returned is in international format without a leading "+" character. For example, 447700900765.

Type: integer

Returns a date in the format yyyy-MM-dd representing the previous day of the week from the specified date. For example, in the following expression, the timestamp is for a Friday, and the expression is asking for the previous Wednesday:

${af:getPreviousWednesday("2007-02-09 13:00:00")}

The expression returns the value 2007-02-07.

This function will return the same date if the supplied timestamp is the same day of the week, for example:

${af:getPreviousFriday("2007-02-09 13:00:00")}

returns with 2007-02-09, as the specified timestamp is for a Friday.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: string

Retrieves the seconds from the timestamp. For example, the expression:

${af:getSecond("1979-05-30 02:32:45")} 

returns with the value 45.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

The function reads the specified input and attempts to extract a US phone number. It looks for 10 digit numbers beginning with or without the US international prefix (1, +1), and outputs the first matching number.

This function is commonly used to extract a number out of SMS message text, for example:

${af:getUSPhoneNumber(session.initialMessage.strippedMessage)}

The output returned is in international format without a leading "+" character. For example, 12515550130.

Type: integer

Returns the week number in the month, from 1 to 5, for the specified timestamp. A week is from Monday to Sunday. This value resets on the first day of each month. For example, the expression:

${af:getWeekOfMonth("2010-04-01 13:00:00")} 

returns the value 1, as it is the first partial week of the month. The next expression:

${af:getWeekOfMonth("2010-04-05 13:00:00")}

returns the value 2, as it is a Monday and begins the second week.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Returns the week number, from 1 to 53, for the specified timestamp. A week is from Monday to Sunday. This value resets on the first Monday of each year. For example, the expression:

${af:getWeekOfYear("2010-01-13 13:00:00")} 

returns the value 2, as it is the second full week of the year.

The expression:

${af:getWeekOfYear("2010-01-01 13:00:00")} 

returns the value 53, as, since it is a Friday, it is considered part of the last week of 2009.

The timestamp format must be yyyy-MM-dd hh:mm:ss.

Type: integer

Retrieves the year from the timestamp. For example, the expression:

${af:getYear("2009-09-30 07:35:21")} 

returns with the value 2009.

Type: integer

Searches the original-string for the first occurrence of the matching-string. It then returns an integer, specifying the number of characters from the start of the string at which the matching-string is found. For example:

${af:indexOf("Hello from OpenMarket", "Open")}

would return 11.

${af:indexOf("OpenMarket rocks", "Open")}

would return 0.

The function is case-sensitive.

If the matching-string does not occur in the original-string, then the function returns -1.

Type: integer

This function is useful when interpreting the response received from the Get External Data handler (such as a list of parameters/XML returned by the handler).

It finds whether the string-matching is in the specified string-list, and returns either true or false. You must specify the character that separates each item in the list, such as a comma, "&" character, or "|" character.

For example:

${af:inList("run=no&swim=yes&cycle=no", "swim=yes", "&")}

returns true, as the function found "swim=yes".

The matching is case-insensitive. The string-matching is also trimmed of whitespace at the beginning and end of the string.

Type: Boolean

Pads to the left of the original-string with the padding-string. The size specifies how many characters the new value should be including the original-string. For example: ${af:leftPad("15", 6, "0")} would return 000015.

Type: string

Returns the character length of the string. For example: ${af:length("OpenMarket")} would return 10.

Type: integer

Returns the larger of the two integers. For example: ${af:max(25,85)} would return 85.

Type: integer

Returns the smaller of the two integers. For example: ${af:max(12,49)} would return 12.

Type: integer

This function attempts to change a date from the standard format used in the United Kingdom to the format yyyy-MM-dd hh:mm:ss.

This function is intended to read dates sent by end users which could be in a variety of formats such as separated by hyphens, forward slashes and spaces. For example, the following date formats can be reformatted: dd-MM-yyyy, dd-MM-yy, dd/MM/yyyy and dd/MM/yy.

Time details entered with the date-string are ignored. The time set in the function’s output is 00:00:00 for all dates.

Type: string

This function attempts to change a date from a regional locale format into the format yyyy-MM-dd hh:mm:ss. The date-string is the date that you want to reformat. The locale-string is a two-letter ISO-3166 code of the country the date is from. You can find these at the site:

http://www.iso.org/iso/country_codes.htm

This function is intended to read dates sent by end users which could be in a variety of formats such as separated by hyphens, forward slashes and spaces.

Examples of two letter locales and the expected local date formats are:

• Australia: AU; dd-MM-yyyy and dd-MM-yy
• New Zealand: NZ; dd-MM-yyyy and dd-MM-yy
• South Africa: ZA; yyyy-MM-dd and yy-MM-dd
• United Kingdom: GB; dd-MM-yyyy and dd-MM-yy
• United States: US; MM-dd-yyyy and MM-dd-yy

For example, the following expression changes an Australian formatted date into the format MEP requires:

${af:normalizeDateFor("27-03-2009","AU")}

This returns with the value 2009-03-27 00:00:00.

Time details entered as part of the date-string are ignored. The time in the functions output is set to 00:00:00 for all dates.

Type: string

Returns the integer as an ordinal string; i.e. with a suffix of either "st", "nd" "rd" or "th". For example:

• ${af:ordinal(1)} would return 1st
• ${af:ordinal(20)} would return 20th
• ${af:ordinal(302)} would return 302nd

Type: string

This function uses the pattern to determine how the specified date-string is formatted and reformats it as yyyy-MM-dd. The pattern must use the characters d, M, and y (case-sensitive) to specify the sequence of day, month and year. This string must be surrounded in double quote marks. You can include additional characters that may be part of the pattern, for example hyphens. Any expected text that interrupts the date stamp should be wrapped in single quotes in the pattern.

For example, the following expression would turn the date 20-12-87 into 1987-12-20:

${af:parseDateString("20-12-87","dd-MM-yy")}

The next expression would reformat the date 01282001 into 2001-01-28:

${af:parseDateString(af:removeLetters(request.defaultMessage), "MMddyyyy")}

Type: string

Returns a random integer between 0 (inclusive) and the specified integer (exclusive). For example, to generate a random integer with 100 as the highest possible number, use the expression ${af:random(101)}.

Type: integer

Returns a random integer between the two specified integers. The integer-low number must be a lower numerical value than the integer-high number. The possible integers returned by the function includes the integer-low number but excludes the integer-high number. For example, to generate a random integer between (and including) 10 and 90, use the expression ${af:randomBetween(10,91)}.

Type: integer

This function uses a regular expression to capture a desired part of the specified string. The syntax is the same as used within Java.

The regexp may include multiple capture groups that grab different data segments. The integer refers to the capture group that you want the expression to output, with 1 being the first capture group specified. If there is only one capture group, then you must specify 1 as the integer. The function will output the specified segment of the first matching string that it finds.

Type: string

This function returns a Boolean value depending on whether the string matches the regular expression.

Type: Boolean

Returns a string with all characters except digits.

Type: string

Returns a string with all characters except letters.

Type: string

Returns a string with only digits, letters and whitespace. For example, you could use the following expression to remove punctuation from SMS message text before it is sent to an external platform:

${af:removePunctuation(session.initialMessage.strippedMessage)}

Type: string

Replaces a specified segment of a string and returns the new string. The string-match is the segment that, once found, is replaced by the string-replacement. For example:

${af:replace( "Openstore", "store", "Market" )}

would return the string, OpenMarket.

The function only replaces the first instance of the string-match found in the string. If the function does not find a string-match in the original string, then the original string is returned.

Type: string

Replaces specified segments of a string and returns the new string. The regex-match is regular expression used to identify the segments to replace. Once found, each segment is replaced by the string-replacement. For example:

${af:replaceAll("This     is   a       sentence       with     too    much    whitespace", "\\s+", " ")

replaces each chunk of whitespace with just one space, and returns the new string: "This is a sentence with too much whitespace".

The function finds and replaces all segments that match the regex-match in the string. If the function does not find a regex-match in the original string, then the original string is returned.

Type: string

Rounds a number to the nearest integer, but returns this as a floating point number to one decimal point. For example: ${af:round(1.73)} would return 2.0.

This function uses the "half up" rounding convention, so ${af:round(2.5)} would return 3.0.

Type: floating-point number

Rounds a number to the specified number of decimal places. You must specify the number of decimal places for the returned number with decimal-place. For example: ${af:roundtoDP(12.1115, 3)} would return 12.112.

Type: floating-point number

Returns a section of the string. The integers determine how many characters from the left to begin and end the string. For example:

• ${af:substring("abc", 1, 3)} returns bc
• ${af:substring("openmarket", 0, 4)} returns open
• ${af:substring("openmarket", 1, 8)} returns penmark

Type: string

Rounds a floating point number to the nearest integer. For example: ${af:toInt(3.87)} would return 4.

Type: integer

Returns a string with all letters in lower case. For example, you could use toLowerCase(input) as a way of making this expression case insensitive:

${af:toLowerCase(session.initialMessage.strippedMessage) == "cat"}

Type: string

Converts a MEP timestamp or date format into a Unix timestamp (in seconds).

The number returned will be negative if you specify a time earlier than midnight, 01 January 1970.

Type: string

Returns a string with all letters in upper case. For example, you could use toUpperCase(input) as a way of making this expression case insensitive:

${af:toUpperCase(session.initialMessage.strippedMessage) == "DOG"}

Type: string

Returns a string with the white space removed from either side of the original string. For example:

${af:trim("   cat and dog     ")}

would return "cat and dog".

Type: string

Returns a string with the white space removed from the left of the original string. For example:

${af:trim("   fish and chips   ")}

would return "fish and chips   ".

Type: string

Returns a string with the white space removed from the right of the original string. For example:

${af:trim("   black and white   ")}

would return "    black and white".

Type: string

Returns the MEP system time in seconds since midnight 01 January 1970 (also known as Unix time). There is no input required in the parentheses; however, you must still include them.

Type: integer

Returns the original string as a URL encoded string. The encoding must be one of:

• UTF-8
• MODIFIED_LATIN_9
• ISO-8859-1

For example to URL encode the message body of an SMS:

${af:urlencode(session.initialMessage.message, "UTF-8")}

Type: string