# Deprecated Date Syntax

We dramatically improved date handling in November 2018. This documentation relates to rules created in versions before that date. In Server this is 4.1.5

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

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

# 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(){{/}}