# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/outgoing-emails/email-templates/formatting-date-and-time-values.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.