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}}).

Old Syntax

We dramatically improved date handling in November 2018. For rules created prior to this please refer to the old syntax documentation.

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 with inbuilt formats
{{issue.resolutiondate.asLongDateTime}}

// you can also drop the "as"
{{issue.MyDateFieldName.longDateTime}}

// Or, you can specify the format
{{issue.dueDate.format("dd/MM/yyyy")}}
{{issue.created.as("dd MMM")}} 

TIP

Note. the format must come at the end of the smart-value

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 Jira's default formatting
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
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
format("<pattern>") e.g. format("dd/MM/yyyy") 01/11/1979 Please refer to Java documentation for pattern syntax.

Locale (language)

You can also specify the Locale to print the dates in. By default we use the "US" locale.

// This will print out the created date in French
{{issue.created.withLocale("fr").asLongDateTime}}

// This will print out the created date in French Canadian
{{issue.created.locale("fr_CA").longDateTime}}

// This will print out the created date in the locale of the reporter
{{issue.created.locale(issue.reporter.locale).longDateTime}}

For a list of locales please refer to Java documentation

Time zone

In Cloud, unless specified, dates are displayed in the time zone - "UTC". In Server, unless specified, dates are displayed in Jira's default timezone.

To specify another time zone you need to set it:

// This method converts the timezone to the new timezone.
// E.g. 10am UTC will be converted to 8pm AEST
{{issue.created.convertToTimeZone("Australia/Sydney")}}

// This method keeps the same times/dates but changes the timezone
// E.g. 10am UTC will be changed to 10am AEST
{{issue.created.setTimeZone("Australia/Sydney")}} 

All time zones are available in the Java documentation.

You can also specify a user's timezone:

// This will print out the time in the reports time zone.
{{issue.created.convertToTimeZone(issue.reporter.timeZone)}} 

Manipulating dates

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

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

Functions available:

Function
plusDays / minusDays
plusBusinessDays/minusBusinessDays
toBusinessDay/toBusinessDayBackwards
plusHours / minusHours
plusMillis / minusMillis
plusMinutes / minusMinutes
plusMonths / minusMonths
plusSeconds / minusSeconds
plusWeeks / minusWeeks
plusYears / minusYears
setTimeZone / convertToTimeZone
withDayOfMonth
withDayOfYear
withHour
withMillis
withMinute
withMonth
withSecond
withYear
// set the time component of the date
toStartOfDay
toCurrentTime
// converts date to date/time
toDateTimeAtStartOfDay
toDateTimeAtStartOfDay(timezone)
toDateTimeAtCurrentTime
toDateTimeAtCurrentTime(timezone)
// Set the day component of the date
endOfMonth
startOfMonth
firstBusinessDayOfMonth
lastBusinessDayOfMonth
firstOfTheMonth(day: 1-7)
lastOfTheMonth(day: 1-7)
ofTheMonth(nth: 1-5, day: 1-7)

Attributes of a date

You can also retrieve individual attributes of a day. E.g. the month

// Get the day of the month
{{now.dayOfMonth}} 
 
// Get the day name of the week
{{issue.created.dayOfWeekName}}

// Get the day name of the week in French
{{issue.created.locale("fr").dayOfWeekName}}

Attributes available:

Attributes
millis
second
minute
hour
dayOfMonth
monthOfYear
year
dayOfYear
dayOfWeek
dayOfWeekName
dayOfWeekShortName
weekOfYear
zoneId
toDays
isLeapYear
lengthOfMonth
lengthOfYear
timeZoneShort
timeZoneFull
timeZoneNarrow
offsetShort
offsetFull
offsetNarrow

Calculating business days

We have 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.toBusinessDay()}}

// finds the next business day after 3 days
{{now.plusDays(3).toBusinessDay()}}

// finds the previous business day
{{now.toBusinessDayBackwards()}}

// adds 6 business days to today
{{now.plusBusinessDays(6)}}

// find the first business day of the month
{{now.firstBusinessDayOfMonth}}

// find the last business day of the month
{{now.lastBusinessDayOfMonth}}

// gets the number of weekday days beeween two dates
{{now.diff(issue.created).businessDays}}

Calculating the difference between two dates

You can calculate the difference between 2 dates using the "diff" method passing in another date and then specifying the unit to measure.

// how many hours since an issue has been created you can do the following
{{now.diff(issue.created).hours}}

// gets the number of days beeween two dates
{{now.diff(issue.created).days}}

// To always show positive dates use the "abs" method
{{now.diff(issue.created).abs.days}}

Units available:

Unit
millis
seconds
minutes
hours
days
weeks
months
years
businessDays
prettyPrint

"prettyPrint" will display the difference in words. E.g. 2 days 3 hours

Comparing two dates

You can compare two dates. These methods take another date as the parameter.

// returns "true"
{{now.isAfter(issue.created)}}

// returns "false"
{{now.isBefore(issue.created)}}

// returns "true"
{{now.isEquals(now)}}

// returns a negative number
{{now.compareTo(issue.created)}}

// returns a positive number
{{issue.created.compareTo(now)}}

// returns 0
{{now.compareTo(now)}}

TIP

You can compare to dates using our Compare condition.

Converting strings to dates

Sometimes you have a value that 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.plusDays(1).longDate}}

Examples

// 1st of May this year
{{now.startOfMonth.withMonth(5)}}

// 1st of May next year
{{now.startOfMonth.withMonth(5).plusYears(1)}}

// last day of May
{{now.withMonth(5).endOfMonth}}

// first business day in May
{{now.withMonth(5).firstBusinessDayOfMonth}}

// last business day in May
{{now.withMonth(5).lastBusinessDayOfMonth}}