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

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.

Creating a Java Formatter

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.

Formatting values

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

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

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

#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