# Formatting Date and Time values

Jira Email This Issue gives you full control in formatting date and time values in your email templates by providing a component called `$!jetiFieldFormatter` that you can use in the email templates.

Read more about the methods of this component in the [Velocity Context in Email Rendering ](https://docs.meta-inf.hu/email-this-issue-for-jira-server-data-center/documentation/outgoing-emails/email-templates/velocity-context-in-email-templates#velocitycontextinemailtemplates-jetifieldformatterjetifieldformatter)section.

Do the following to format date and time values:

1. Create a formatter object.
2. Format the date or date-time values using the created formatter.

### Creating a Jira formatter <a href="#howtoformatdateandtimevalues-createjiraformatter" id="howtoformatdateandtimevalues-createjiraformatter"></a>

Create a Jira formatter in your template:

```
#set($formatter = $!jetiFieldFormatter.getJiraDateTimeFormatter(<date time style name>))
```

`<date time style name>` can be any of the following:

* Empty: If called without a parameter, `getJiraDateTimeFormatter()` returns the default Jira date time formatter.
* The name of a predefined style in `DateTimeStyle`. E.g. `$!jetiFieldFormatter.getJiraDateTimeFormatter("COMPLETE")` returns a Jira formatter for the `COMPLETE` style. Read more about `DateTimeStyle` [here](https://docs.atlassian.com/DAC/javadoc/jira/7.1.0-m01/reference/com/atlassian/jira/datetime/DateTimeStyle.html).

### Creating a Java Formatter <a href="#howtoformatdateandtimevalues-createjavaformatter" id="howtoformatdateandtimevalues-createjavaformatter"></a>

There are multiple ways to create a Java date formatter.

**Creating a Java formatter with style**

```
#set($formatter = $!jetiFieldFormatter.getJavaDateFormat(<date format style number>, <locale string>))
```

`<date format style number>` can be any of the following:

* Empty: If called without parameters `getJavaDateFormat()` returns the default Java formatter.
* The value of a date format style constant in `DateFormat`. E.g. `$!jetiFieldFormatter.getJavaDateFormat(1)` returns a `DateFormat` instance for the `DateFormat.LONG` style.
* (Optional) `<locale string>`: The Java string representation of a locale. Always use language and country, like "`en_GB`" or "`de_DE`" or "`hu_HU`". If not provided, the user's default locale will be used.

**Creating a Java formatter with pattern**

```
#set($formatter = $!jetiFieldFormatter.getJavaDateTimeFormat(<date type pattern>))
```

`<date time pattern>` can be a valid pattern according to Java `SimpleDateFormat` specification. E.g. a pattern of `dd/MM/yyyy HH:mm` returns a formatter that formats the timestamp of May 31, 2022 1:35pm.&#x20;

### Formatting values <a href="#howtoformatdateandtimevalues-formatvalues" id="howtoformatdateandtimevalues-formatvalues"></a>

Once you have a formatter, the date or date-time field values can be formatted in the following way:

```
$!jetiFieldFormatter.formatSafely($formatter,<date time value>)
```

`<date time value>` may be either:

* An issue attribute, like `$!issue.created` or `$!issue.updated`
* An issue custom field: `$!issue.getCustomFieldValue("customfield_12345")`, where "`customfield_12345`" is the custom field key of a Date Picker or `DateTime` Picker field. Calling the formatter with a non-date value will render an empty string.

### Rendering the date or date-time values in any time zone <a href="#howtoformatdateandtimevalues-renderdateordate-timevaluesinanytimezone" id="howtoformatdateandtimevalues-renderdateordate-timevaluesinanytimezone"></a>

To render the date or date-Time values in a time zone both the Jira DateFormatter and Java DateFormat can be used. There is a list of Timezone IDs are available for Java.

Example for rendering the issue's due date in Alaska time using the Java DateFormat API:

```
##Create a Java formatter using a java datetime pattern
#set($formatter = $!jetiFieldFormatter.getJavaDateTimeFormat("yyyy.MMM.dd z"))

##set the time zone in the formatter
$!formatter.setTimeZone($!jetiFieldFormatter.getTimeZone("US/Alaska"))

##format the date value with the formatter
Issue Due Date in Alaska time: $!formatter.format($!issue.dueDate)
```

Example for rendering the issue's due date in Alaska time using the Jira DateFormatter API:

```
##Create a Java formatter using a Jira formatter style, with the time zone information
#set ($formatter = $jetiFieldFormatter.getJiraDateTimeFormatter("COMPLETE").withZone($!jetiFieldFormatter.getTimeZone("US/Alaska")))

##format the date value with the formatter
Issue Due Date in Alaska time: $!formatter.format($!issue.dueDate)
```

### Rendering the date or date-time values in your time zone <a href="#howtoformatdateandtimevalues-renderdateordate-timevaluesinanytimezone" id="howtoformatdateandtimevalues-renderdateordate-timevaluesinanytimezone"></a>

We support using the time zone set in the current user’s profile. For example to render the issue's last update date-time with the current user's time using the TemplateSupport's `currentUsersTimeZoneId`.

```
##give dynamically the time zone upon the current user's profile using the shortcut template method #renderDateTime 
The issue was updated at #renderDateTime($!issue.updated "yyyy-MM-dd'T'HH:mmZ'['z']'" $!templateSupport.currentUsersTimeZoneId)Please note that the capital letter T in the above code is just a placeholder, an example to mark that after the date, the time value comes next.
```

### Shortcut template methods to format values easier <a href="#howtoformatdateandtimevalues-shortcuttemplatemethodstoformatvalueseasier" id="howtoformatdateandtimevalues-shortcuttemplatemethodstoformatvalueseasier"></a>

```
#renderDateTime($!issue.getCustomFieldValue("My Date Time Custom Field") "yyyy-MM-dd") ##Render the issue's "My Date Time Custom Field" custom field in the given pattern
#renderDate($!issue.dueDate "yyyy-MM-dd") ##Render the issue's due date in the given pattern
#renderDate($!issue.dueDate "yyyy-MM-dd" "US/Alaska") ##Render the issue's due date in the given pattern using Alaska time zone

#renderDateTime($!issue.getCustomFieldValue("My Date Time Custom Field") "yyyy-MM-dd") ##Render the issue's "My Date Time Custom Field" custom field in the given pattern
#renderDateTime($!issue.getCustomFieldValue("My Date Time Custom Field") "yyyy-MM-dd" "US/Alaska") ##Render the issue's due date in the given pattern with regard to the given time zone
```