Functions for Timestamps or Time

The following functions relate to dates, times, and timestamps.

Turn a string into a timestamp

The following functions can turn a date from a local format into the format required by MEP (yyyy-MM-dd HH:mm:ss). There is also a function to process the MEP date format into a custom date format.

When collecting dates from end users, we recommend that you clearly indicate the format you want them sent in.

Note that if these functions do not meet a specific need, then you can still use regular expressions to capture or format a date string.

Function

Description

Output

parseDateString(date-string,pattern)

 

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")}

String

 

formatDateString(date-string, pattern)

 

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

String

normalizeDate(date-string)

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.

String

normalizeDateFor(date-string, locale-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.

String

 

Retrieve or convert Unix time

Function

Description

Output

currentTimeMillis()

 

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.

Integer

 

unixTime()

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.

Integer

fromUnixTime(unix- timestamp)

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.

String

 

fromUnixTimeTZ(unix- timestamp, timezoneID)

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.

String

 

fromUnixTimeUS(unix- timestamp, usTimeZone)

 

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.

String

toUnixTime (timestamp)

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.

String

Add time to a timestamp

Function

Description

Output

addDay(timestamp, integer)

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.

String

 

addHour(timestamp, integer)

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.

String

 

addMinute(timestamp, integer)

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.

String

Retrieve the time or date from a timestamp

The following functions enable you to get specific date or time from a timestamp, including individual elements (such as the minute), what part of a month or year a date is in, and what day it is. These functions take the format:

getX(timestamp)

The timestamp is the time and date in the format yyyy-MM-dd hh:mm:ss. For example, the following expression would return the value 1989:

${af:getYear("1989-11-09 18:00:32")}

The timestamp can be any function or variable that evaluates to a date in the above format. For example:

${af:getMonth(request.message.date)}
${af:getDay(system.time)}

The following table shows functions related to the time of the timestamp.

Function

Description

Output

getHour(timestamp)

 

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.

Integer

getMinute(timestamp)

 

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.

Integer

 

getSecond(timestamp)

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.

Integer

 

The following table shows functions related to the day or week of the timestamp.

Function

Description

Output

getDay(timestamp)

 

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.

Integer

getDayOfMonth(timestamp)

This function is synonymous with getDay(timestamp).

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

Integer

getDayOfWeek(timestamp)

 

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.

Integer

getDayOfYear(timestamp)

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.

Integer

getNameOfDay(timestamp)

 

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.

String

 

getPreviousMonday…Sunday(timestamp)

 

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.

String

getPreviousMonday…Sunday(timestamp)

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.

String

 

getWeekOfMonth(timestamp)

 

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.

Integer

 

getWeekOfYear(timestamp)

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.

Integer

The following table shows functions related to the month or year of the timestamp.

Function

Description

Output

getYear(timestamp)

 

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

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

returns with the value 2009.

Integer

getMonth(timestamp)

 

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.

Integer

getNameOfMonth (timestamp)

 

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.

String

Retrieve the age from a date

Function

Description

Output

getAge(date)

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

Integer

Compare dates

Function

Description

Output

compareDate(input-A,input-B)

 

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.

Boolean

daysBetween(date-A, date-B)

 

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

Integer