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:
Create a formatter object.
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 theCOMPLETE
style. Read more aboutDateTimeStyle
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 aDateFormat
instance for theDateFormat.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 orDateTime
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
Last updated
Was this helpful?