---
title: "Extract and Format Dates and Times"
slug: "extract-and-format-dates-and-times"
description: "Mapp Engage functions that format dates and timestamps, convert strings to dates, add intervals, and extract date parts."
status: "update"
updated: 2026-11-04T12:18:43Z
published: 2026-11-04T12:18:43Z
canonical: "docs.mapp.com/extract-and-format-dates-and-times"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract and Format Dates and Times

These functions provide tools for interpreting date values. Many of these functions process and return the information as a date which can be compared to other date and time values. Many of these functions require values in date or time zone format as parameters. The parameters are generated by nesting the functions `ecm:toDate` and `ecm:timeZone`.

Modifications to the extracted values are made for the purposes of the query only. The actual data stored in the target source is not changed in any way.

---

## Function Overview

| Function | Description |
| --- | --- |
| `ecx:formatDate` | Formats a date according to the specified pattern. |
| `ecx:fmtDateInTimezone` | Interprets a given date in the specified source time zone. It then sets the specified target time zone on the date but retains the date and time fields as they were on the original date. |
| `ecx:formatTimestamp` | Returns a timestamp in the desired string format. |
| `ecx:getDate` | Returns the current date in the format 'yyyyMMdd' with the specified time zone. |
| `ecx:getTime` | Returns the current time in the format 'HHmmss" with the specified time zone. |
| `ecx:getDateTime` | Returns the current date and time in the format 'yyyyMMddHHmmss' with a specified time zone. |
| `ecm:addInterval` | Adds (or subtracts) an interval of time to a specified date. |
| `ecm:day` | Returns the day component of the referenced date. |
| `ecm:month` | Returns the month component of the referenced date. |
| `ecm:year` | Returns the year component of the referenced date. |
| `ecm:toDate` | Converts a target string or value into a date data type. |
| `ecm:timeZone` | Converts the specified time zone ID to a (Java utility class) time zone. |
| `ecm:trunc` | Returns a new date where the specified time or date component is reset to a default value (truncated). |

---

## ecx:formatDate

The function `ecx:formatDate` formats a date according to the specified pattern. The value returned is a string data type.

### Example

The following example takes a given date and time in Central European Time (UTC+01:00), applies a specific date formatting and changes the time zone to Greenwich Mean Time (UTC+00:00). The final parameter displays the time zone.

```plaintext
${ecx:formatDate(ecm:toDate('2010-03-27 16:12:21', ecm:timeZone('Europe/Warsaw')), 'EEEE, MMMMM d, hh:mm aaa', ecm:timeZone('Europe/London'), 'en', true)}
```

The output is displayed as Saturday, March 27, 03:12 PM GMT.

### Structure

`ecx:formatDate(date, string, timezone, String, Boolean)`

Example:

```plaintext
${ecx:formatDate(date.Today,'yyyy-MM-dd',ecm:timeZone('Europe/Berlin'),'de',false)}
```

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Target date value to format. If the value used for this parameter is a string data type, it must be converted to a date data type with the function `ecm:toDate`. |
| `string` | Specifies the date format. A list of possible date patterns is available here: [SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html). Please be sure to use the format ‘yyyy-MM-dd’ instead of ‘YYYY-MM-dd’; otherwise, there may be errors at the end and beginning of the year. The parameter also recognizes the values 'date', 'shortdate', 'time', 'datetimesec', 'datetime', 'shortdatetime', 'xlsdate', 'xlsdatetime', 'iso8601date' and 'iso8601datetime'. The output format is further refined by the variable localeCode. |
| `timezone` | Specifies the output time zone. |
| `string` | Variable localeCode, applies a country-specific format to the date according to the ISO language code used. |
| `Boolean` | Variable withTimeZone, specifies whether the formatted date includes an abbreviation for the time zone. |

---

## ecx:fmtDateInTimezone

The function `ecx:fmtDateInTimezone` interprets a given date in the specified source time zone. It then sets the specified target time zone on the date but retains the date and time fields as they were on the original date. The date is formatted as a string with the given pattern and locale. The value returned is a string data type.

### Example

The purchase date is stored in the custom attribute `user.CustomAttribute['PurchaseDate']`. The function to convert this value to Sydney time is constructed as follows:

```plaintext
${ecx:fmtDateInTimezone(user.CustomAttribute['PurchaseDate'], null, 'Australia/Sydney', 'yyyy-MM-dd HH:mm:ssZ', 'en')}
```

If the attribute value is 2013-09-08T02:00:00+0200 (midnight at UTC time), the output is 2013-09-08T00:00:00+1000.

### Structure

`ecx:fmtDateInTimezone(date, string, string, string, string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Specifies the target value to format. If the value used for this parameter is a string data type, it must be converted to a date data type with the function `ecm:toDate`. |
| `string` | Specifies the source time zone. If no source time zone is specified, UTC+00:00 is used as default. |
| `string` | Specifies the target time zone. |
| `string` | Specifies the date format. A list of possible date patterns is available here: [SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html). The parameter also recognizes the values 'date', 'shortdate', 'time', 'datetimesec', 'datetime', 'shortdatetime', 'xlsdate', 'xlsdatetime', 'iso8601date' and 'iso8601datetime'. The output format is further refined by the variable localeCode. |
| `string` | Variable localeCode, applies a country-specific format to the date according to the ISO language code used. |

---

## ecx:formatTimestamp

The function `ecx:formatTimestamp` returns a timestamp in the desired string format. The value returned is a string data type.

### Example

Apply a specific date format to a timestamp and change the time zone to Central European Time (`Europe/Berlin`).

```plaintext
${ecx:formatTimestamp('1272381141000', 'EEEE, MMMMM d, hh:mm aaa', ecm:timeZone('Europe/Berlin'), 'en', true)}
```

The output is displayed as Tuesday, April 27, 05:12 PM CEST.

### Structure

`ecx:formatTimestamp(long, string, timezone, string, Boolean)`

### Parameters

| Parameter | Description |
| --- | --- |
| `long` | Specifies the target long integer to format. |
| `string` | Specifies the date format. The patterns are the same as for `ecx:formatDate`. |
| `timezone` | Specifies the output time zone. |
| `string` | Variable localeCode, applies a country-specific format to the date according to the ISO language code used. |
| `Boolean` | Variable withTimeZone, specifies whether the formatted date includes an abbreviation for the time zone. |

---

## ecx:getDate

The function `ecx:getDate` returns the current date in the format 'yyyyMMdd' with a specified time zone. The value returned is a string data type.

### Example

```plaintext
${ecx:getDate(timezone.europeBerlin)}
```

### Structure

`ecx:getDate(timezone)`

### Parameters

| Parameter | Description |
| --- | --- |
| `timezone` | Specifies the time zone to apply to the returned value. |

---

## ecx:getTime

The function `ecx:getTime` returns the current time in the format 'HHmmss' with the specified time zone. The value returned is a string data type.

### Example

```plaintext
${ecx:getTime(timezone.europeLondon)}
```

### Structure

`ecx:getTime(timezone)`

### Parameters

| Parameter | Description |
| --- | --- |
| `timezone` | Specifies the time zone to apply to the returned value. |

---

## ecx:getDateTime

The function `ecx:getDateTime` returns the current date and time in the format 'yyyyMMddHHmmss' with a specified time zone. The value returned is a string data type.

### Example

```plaintext
${ecx:getDateTime(timezone.pacificFiji)}
```

### Structure

`ecx:getDateTime(timezone)`

### Parameters

| Parameter | Description |
| --- | --- |
| `timezone` | Specifies the time zone to apply to the returned value. |

---

## ecm:addInterval

The function `ecm:addInterval` adds (or subtracts) an interval of time to the specified date. The value returned is a date data type.

### Example

A message is sent to all customers who made a purchase in the last five days. The message contains a list of the products the customer purchased during that time.

All customer purchases are saved in a related data set Purchases. The related data set is linked to the attribute Client_ID. The client ID saved in the attribute is identical to the key of the related data set. Since customers can make multiple purchases, the related data set is not unique.

The `ecm:addInterval` function returns the value of today's date minus five days:

```plaintext
${ecx:formatDate(ecm:addInterval(date.Today, '-5d'), 'yyyy-MM-dd', ecm:timeZone('Europe/London'), '', false)}
```

The value returned by this function is then used as a parameter in the `ecx:filter` function, which returns all entries for purchases made in the last five days. Since the related data set is not unique, a ForEach loop inserts the data into the message. The entire expression, set inside the ForEach loop, is constructed as follows:

```plaintext
<%ForEach var="count" items="${ecx:filter(ecx:related('Purchases', user.CustomAttribute['Client_ID']), 'Date', '>=', ecx:formatDate(ecm:addInterval(date.Today, '-5d'), 'yyyy-MM-dd', ecm:timeZone('Europe/London'), '', false))}"%> <%${count.Article}%> <%/ForEach%>
```

### Structure

`ecm:addInterval(date, string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Specifies the target reference date. To use the current date as the reference, enter `date.Today`. |
| `string` | Specifies the interval to add to or subtract from the target date. The string pattern is (+\|-)xxYxxMxxWxxdxxhxxmxx, where xx stands for a number. The letters identify the preceding number as: - Y year - M month - W week - d day - h hour - m minute - s second The plus sign (+) adds the specified interval and the minus sign (-) subtracts the specified interval from the date parameter. |

> [!NOTE]
> Note
> 
> The value used as the date parameter must include the interval specified by the string parameter. For example, to subtract 48 hours from the target date, the value used as the date parameter must include the hour.

---

## ecm:day

The function `ecm:day` returns the day component of the referenced date. The first day of the month has a value of 1. The value returned is an integer data type.

### Example

A specific paragraph is entered if the recipient's date of birth equals the date of sendout.

The content is inserted into the message with an InsertIf statement, which is constructed as follows:

```plaintext
<%InsertIf expression="${(ecm:day(user['DateOfBirth'])==ecm:day(date.Today))and(ecm:month(user['DateOfBirth'])==ecm:month(date.Today))}"%> Text <%/InsertIf%>
```

The parameter `date.Today` returns the full date (day, month, and year). The function `ecm:day` extracts the day part from both the user attribute and the date of sendout. The results returned from both functions are compared using the operator ==.

Note that the function `ecm:month` is used in a similar fashion to check the month part of the date.

### Structure

`ecm:day(date)`

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Specifies the target date. |

---

## ecm:month

The function `ecm:month` returns the month component of the referenced date. January has a value of 1. The value returned is an integer data type.

### Example

A specific paragraph is entered if the recipient's date of birth equals the date of sendout.

The content is inserted into the message with an InsertIf statement, which is constructed as follows:

```plaintext
<%InsertIf expression="${(ecm:day(user['DateOfBirth'])==ecm:day(date.Today))and(ecm:month(user['DateOfBirth'])==ecm:month(date.Today))}"%> Text <%/InsertIf%>
```

The parameter `date.Today` returns the full date (day, month, and year). The function `ecm:month` extracts the month part from both the user attribute and the date of sendout. The results returned from both functions are compared using the operator ==.

Note that the function `ecm:day` is used in a similar fashion to check the day part of the date.

### Structure

`ecm:month(date)`

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Specifies the target date. |

---

## ecm:year

The function `ecm:year` returns the year component of the referenced date. The value returned is an integer data type.

### Example

The date of each recipient's high school graduation is stored as a group member attribute. The year part of this date is extracted for use in a message. The expression for inserting this information in a message is constructed as follows:

```plaintext
<%${ecm:year(ecm:toDate(user.MemberAttribute['graduation_date'], ''))}%>
```

Note that the function `ecm:toDate` is also used to ensure that the value stored in the member attribute is formatted as a date data type to match the type required for the parameter.

### Structure

`ecm:year(date)`

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Specifies the target date. |

---

## ecm:toDate

The function `ecm:toDate` converts a target string or value into a date data type. The value returned is a date data type.

This function is often used to convert values to dates for use with functions that require date data types in parameters.

### Example

A selection determines whether recipients who are near retirement age receive a message. The segment criteria compare the date of birth stored as an attribute value to a specific date (1 January 1950). In order to compare the two dates using the function `ecm:less`, both values must be date data types. The function `ecm:toDate` converts the string '1950-01-01' into a date data type so it can be compared with the date stored in the recipient attribute `user['DateOfBirth']`. The combined functions are constructed as follows:

```plaintext
${ecm:less(user['DateOfBirth'], ecm:toDate('1950-01-01', ecm:timeZone('Europe/Berlin')))}
```

### Structure

`ecm:toDate(string, timezone)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target value to be converted into date format. Formats that are correctly converted into dates include: - yyyy-MM-dd - dd.MM.yyyy - yyyy-MM-dd hh:mm:ss - dd.MM.yyyy hh:mm:ss |
| `timezone` | The time zone used as reference for the date. If not specified, the system default time zone is used. |

---

## ecm:timeZone

The function `ecm:timeZone` converts the specified time zone ID to a (Java utility class) timezone. The value returned is a timezone type.

This function is often used to convert values to timezones for use with functions that require timezone types in parameters.

### Example

A message is sent to all customers who made a purchase in the last 5 days. The `ecm:addInterval` function returns the value of today's date minus five days:

```plaintext
${ecx:formatDate(ecm:addInterval(date.Today, '-5d'), 'yyyy-MM-dd', ecm:timeZone('Europe/London'), '', false)}
```

The `ecm:timeZone` function determines which time zone is used when calculating the value of today's date (`date.Today`).

### Structure

`ecm:timeZone(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target time zone ID to convert. |

---

## ecm:trunc

The function `ecm:trunc` returns a new date where the specified time or date component is reset to a default value (truncated). The value returned is a date data type.

### Example

A selection sends a welcome message to contacts on the day they signed up for a newsletter. The sign-up date is stored in the custom attribute `WelcomeDate`.

The function `ecm:trunc` resets the time component of both the current date and the attribute value to zero. The function `ecm:equal` can then compare the two dates, because the time component no longer affects the result. The expression for use in the selection is constructed as follows:

```plaintext
${ecm:equal(ecm:trunc(user.CustomAttribute['WelcomeDate'], 'time'), ecm:trunc(date.Today, 'time'))}
```

### Structure

`ecm:trunc(date, string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `date` | Specifies the target date. |
| `string` | Specifies the date component to truncate. The following values are considered valid for this parameter: |
| `time` | Resets the time component to 00:00:00.0. |
| `year` | Resets the year component to the epoch. |