Date functions

Where to use

Automation for Jira allows you to manipulate and format dates inside fields that support Smart Values. We support created, updated, duedate, resolutiondate as well as the Date Picker custom fields (e.g. {{issue.MyDateFieldName}} or {{issue.customfield_12356}}).

Referencing the current date/time

You can reference the current date and time using {{now}}.

Formatting dates

You can specify the format of the date in 2 ways:

Specifying format

// To format a date field value
{{#issue.resolutiondate}}longDateTime{{/}}
{{#issue.MyDateFieldName}}longDateTime{{/}}

// When no other fields are specified you can just include the format
{{#now}}longDateTime{{/}}
 
// When you specify timezone or a function to manipulate the date you need 
// to explicitly label the format and include the value in double quotes.
{{#now}}format="longDateTime",zone=Australia/Sydney{{/}}
 

There are a number of built-in formats or you can specify your own:

Format Thursday, November 1, 1979 6:23:12 AM EST Notes
Default (none specified) Nov 1, 1979 6:23:12 AM If no format is specified it defaults to mediumDateTime. This may not work if used as the input for some fields
jiraDate 1979-11-01 This is the format expected for Jira fields of the type Date
jiraDateTime 1979-11-01T06:23:12.0-0500 This is the format expected for Jira fields of the type Date Time
jqlDate 1979-11-01 This is the format for dates in JQL
jqlDateTime 1979-11-01 06:23 This is the JQL format for Date Times
toMillis 310303392034 This is how many milliseconds have passed since Epoch
toSeconds 310303392 This is how many seconds have passed since Epoch
toMinutes 5171723 This is how many minutes have passed since Epoch
toHours 86195 This is how many hours have passed since Epoch
toDays 3591 This is how many days have passed since Epoch
shortDate 11/1/79
shortTime 6:23 AM
shortDateTime 11/1/79 6:23 AM
mediumDate Nov 1, 1979
mediumTime 6:23:12 AM
mediumDateTime Nov 1, 1979 6:23:12 AM
longDate November 1, 1979
longTime 6:23:12 AM EST
longDateTime November 1, 1979 6:23:12 AM EST
fullDate Thursday, November 1, 1979
fullTime 6:23:12 AM EST
fullDateTime Thursday, November 1, 1979 6:23:12 AM EST
<pattern> e.g. dd/MM/yyyy 01/11/1979 Please refer to Joda documentation for pattern syntax.

Time zone

By default dates are displayed for the time zone - "UTC". This is the timezone of the Jira servers for OnDemand/Cloud and the default timezone that will be used when allocating scheduled triggers.

To specify another time zone you need to add a parameter:

// This will print out the time in Sydney when the issue was created.
{{#issue.created}}zone=Australia/Sydney{{/}} 

Available time zones are available in the Joda documentation.

You can also specify a user's timezone:

// This will print out the time in the reports time zone.
{{#issue.created}}zone={{reporter.timeZone}}{{/}} 

Locale (language)

By default dates are output in english. To specify another locale you must specify the parameter:

// This will print out the time in Sydney when the issue was created.
{{#issue.created}}locale=ru_RU{{/}} 

Available locales are available in the Java documentation.

Manipulating dates

You can also manipulate dates by setting particular parts of the date or add/subtracting values from it:

// This will add 7 days to the current time
{{#now}}func=plusDays(7){{/now}} 
 
// You can chain functions.
// This will set the day to the fist of the month and month to November
{{#issue.created}}func=withDayOfMonth(1).withMonthOfYear(11){{/}}

Functions available:

Function
plusDays / minusDays
plusBusinessDays/minusBusinessDays
toBusinessDay/toBusinessDayBackwards
plusHours / minusHours
plusMillis / minusMillis
plusMinutes / minusMinutes
plusMonths / minusMonths
plusSeconds / minusSeconds
plusWeeks / minusWeeks
plusYears / minusYears
withCenturyOfEra
withDayOfWeek
withDayOfMonth
withDayOfYear
withEra
withHourOfDay
withMillis
withMillisOfSecond
withMillisOfDay
withMinuteOfHour
withMonthOfYear
withSecondOfMinute
withTimeAtStartOfDay
withWeekOfWeekyear
withWeekyear
withYear
withYearOfCentury
withYearOfEra

Calculating business days

We have 2 sets of functions built in to work with business days - you can either plus/minus business days from the current date or find the closest business day to the current date. Business days are considered Monday through Friday.

// finds the next business day
{{#now}}func=toBusinessDay(){{/}}
// finds the next business day after 3 days
{{#now}}func=plusDays(3).toBusinessDay(){{/}}
// finds the previous business day
{{#now}}func=toBusinessDayBackwards(){{/}}

// adds 6 business days to today
{{#now}}func=plusBusinessDays(6){{/}}

// gets the number of weekday days beeween two dates
{{#now}}func=businessDaysBetween({{issue.created}}), format="toDays"{{/}}

Calculating the difference between two dates

You can do this using the "toSecond" format and the "minusSeconds" function to subtract one date from the other. You then use one of the formats that displays how many seconds, minutes, hours or days. There's also a shortcut method called daysBetween with simpler syntax you can use.

// how many hours since an issue has been created you can do the following
{{#now}}func=minusSeconds({{#issue.created}}toSeconds{{/}}), format="toHours"{{/}}

// gets the number of days beeween two dates
{{#now}}func=daysBetween({{issue.created}}), format="toDays"{{/}}

Converting strings to dates

Sometimes you have a value that you is a date but is stored as a string. E.g. in the changelog, dates are stored as strings. You can convert any string into a date simply using:

{{issue.summary.toDate}}

This will convert the string into a date if it is in the right format. You can also specify the format to convert from by adding the param. The example below will convert String formatted like: "2017 6 11" into Date objects.

{{issue.summary.toDate("yyyy MM dd")}}

Note that once you've converted to a Date object, you'll probably still need to transform it further. For fieldChanged (e.g. listening for a change in date}

{{#fieldChange.fromString.toDate}}longDate{{/}}

Examples

// 1st of may this year
{{#now}}func=withDayOfMonth(1).withMonthOfYear(5){{/}}

// 1st of may next year
{{#now}}func=withDayOfMonth(1).withMonthOfYear(5).plusYears(1){{/}}

// last day of May
{{#now}}func=withDayOfMonth(1).withMonthOfYear(6).minusDays(1){{/}}

// first business day in May
{{#now}}func=withDayOfMonth(1).withMonthOfYear(5).toBusinessDay(){{/}}

// last business day in May
{{#now}}func=withDayOfMonth(1).withMonthOfYear(6).minusDays(1)
             .toBusinessDayBackwards(){{/}}