date filter

Owned by Daniel Barrow
Aug 30, 2023
13 min read

When accessed from Nunjucks templates, Jira returns Date and Date/Time values as an ISO 8601-compliant string, such as: 2016-06-12T13:49:34.768+0200. This applies to Date and Date/Time standard fields (e.g. issue.fields.created, issue.fields.updated, issue.fields.duedate, etc.), Date and Date Time Picker custom fields (e.g. issue.fields["Change completion date"]) as well as any date or date/time subfield of a field value (e.g. issue.fields.comment.comments[0].created). JMWE's  now variable, which represents the current date and time, also returns an ISO 8601-compliant string.



On this page:



However, being strings, Jira date/time values aren't easy to work with. To manipulate and format dates and times in Nunjucks, JMWE uses the Moment.js library. All the functions provided by the library, which are available to your Nunjucks templates through the date filter, return a Moment.js date object. A Moment.js date object is an object that encapsulates the current date and time, as well as time zone information, and can easily be manipulated and formatted for display.  JMWE's  nowObj variable, which represents the current date and time, returns a Moment.js date object.

Refer to the official documentation for more information about Moment.js.

Converting a Jira date/time string to a Moment.js date object

You can convert a Jira date/time string to a Moment.js date object using the clone method of the Moment.js library. For example: 

"2018-02-14" | date("clone") returns a Moment.js date object.

When rendered in a {{...}} block, a Moment.js date object is output as a string representing the specified moment in milliseconds.

{{ "2018-02-14" | date("clone") }} outputs 1518566400000 

Converting a Moment.js date object to a Jira date/time string

You can convert a Moment.js date object to a string representing a date/time object using the date filter. For example: 

nowObj | date returns the current date/time as an ISO 8601-compliant string such as 2018-02-14T00:00:00Z.

To format a Moment.js date object to a more human-readable string, use the date(format) form of the filter.

Date calculations

You might want to manipulate a date before setting it to a field. For example, you might want to set the Original estimate to the difference of the Created and Due date. Below are some methods to help with these manipulations.

add

Description:

Adds time to a date.

Syntax:

{{ DATE | date('add' , Number , String) | date }}

{{ DATE | date('add' , Duration) | date }}

{{ DATE | date('add' , Object) | date }}

Examples:

Assuming {{ now }} is 2016-10-17T08:38:16.625Z

Input

Details

Output

Input

Details

Output

{{ now | date('add' , 3 , 'days') | date }}

The String can be 'days' or shorthand 'd'

2016-10-20T08:38:16Z

{{ now | date('add' , 3 , 'days') | date('add' , 1 , 'M') | date }}

You can add multiple keys at the same time

2016-11-20T08:38:16Z

{{ now | date('add' , {months:2, days:3}) | date }}

You can also pass them in object literal

2016-12-20T08:39:17Z

The shorthand keys are: 'y', 'Q', 'M', 'w', 'd', 'h', 'm', 's' and 'ms' for years, quarter, months, weeks, days, hours, minutes, seconds and milliseconds respectively.

When decimal values are passed for days and months, they are rounded to the nearest integer. Weeks, quarters, and years are converted to days or months, and then rounded to the nearest integer.

subtract

Description:

Subtracts time from a date.

Syntax:

{{ DATE | date('subtract' , Number , String) | date }}

{{ DATE | date('subtract' , Duration) | date }}

{{ DATE | date('subtract' , Object) | date }}

Examples:

 Assuming {{ now }} is 2016-10-17T08:41:47.658Z

Input

Details

Output

Input

Details

Output

{{ now | date('subtract' , 3 , 'days') | date }}

The String can be 'days' or shorthand key 'd'

2016-10-14T08:51:47Z

{{ now | date('subtract' , 3 , 'days') | date('add' , 1 , 'M') | date }}

You can add multiple keys at the same time

2016-11-14T08:51:47Z

{{ now | date('subtract' , {months:4, days:13}) | date }}

You can also pass them in object literal

2016-06-04T08:51:47Z

The shorthand keys are: 'y', 'Q', 'M', 'w', 'd', 'h', 'm', 's' and 'ms' for years, quarters, months, weeks, days, hours, minutes, seconds and milliseconds respectively.

When decimal values are passed for days and months, they are rounded to the nearest integer. Weeks, quarters, and years are converted to days or months, and then rounded to the nearest integer.

startOf

Description:

Sets a date to the start of a unit of time.

Syntax:

{{ DATE | date('startOf' , String) | date }}

Examples:

 Assuming {{ now }} is 2016-10-17T08:41:47.658Z

Input

Output

Input

Output

{{ issue.fields.duedate | date('startOf' , 'year') | date }}

2016-01-01T00:00:00Z

{{ issue.fields.duedate | date('startOf' , 'quarter') | date }}

2016-10-01T00:00:00Z

The units of time that can be passed are:

Unit

Sets to

Unit

Sets to

year

January 1st, 12:00 am this year

month

Beginning of this month, 12:00 am

quarter

Beginning of the current quarter, 1st day of the month

week

Start of this week, 12:00 am

isoWeek

Start of this week, according to ISO 8601, 12:00 am

day

12:00 am today

date

12:00 am today

hour

Now, but with 0 mins, 0 secs, 0 ms

minute

Now, but with 0 seconds and 0 milliseconds

second

Now, but with 0 milliseconds

endOf

Description:

Sets a date to the end of a unit of time.

Syntax:

{{ DATE | date('endOf' , String) | date }}

Examples:

 Assuming {{ now }} is 2016-10-17T08:41:47.658Z

Input

Output

Input

Output

{{ issue.fields.duedate | date('endOf' , 'year') | date }}

2016-12-31T23:59:59Z

{{ issue.fields.duedate | date('endOf' , 'quarter') | date }}

2016-12-31T23:59:59Z

The units of time that can be passed are:

Unit

Sets to

Unit

Sets to

year

December 31st, 23:59 pm this year

month

End of this month, 23:59 pm

quarter

Ending of the current quarter, 31st day of the month

week

End of this week, 23:59 pm

isoWeek

End of this week, according to ISO 8601, 23:59 pm

day

23:59 pm today

date

23:59 pm today

hour

Now, but with 59 mins, 59 secs, 1000 ms

minute

Now, but with 59 seconds and 1000 milliseconds

second

Now, but with 999 milliseconds

clone

Description:

This method takes a date String as input and creates a Moment.js date object.

Syntax:

{{ DATE | date("clone") }}

Examples:

Format

Output

Format

Output

{{ now | date("clone") }}

1503391995754

{{issue.fields.created | date("clone") }}

1503318155861

{% set newDate = now | date("clone") %}{{newDate}}

1503392291416

daysInMonth

Description:

daysInMonth() method can be used to display the number of days in the current month.

Syntax:

{{ DATE | date('daysInMonth') }}

Examples:

If the Due date is 24/Nov/16: {{ issue.fields.duedate | date('daysInMonth') }} will display 30



diff

Description:

Get the difference in milliseconds

Syntax:

{{ DATE | date('diff' , Moment) }}

Examples:

 Assuming {{ now }} is 2018-01-04T10:27:23.047Z and {{issue.fields.created}} is 2018-01-04T10:54:53.499+0100

Input

Output

Input

Output

{{ now | date('diff', issue.fields.created) }}

1976836

To get the difference in another unit of measurement, pass that measurement as the second argument. The supported measurements are years, months, weeks, days, hours, minutes, and seconds.



Input

Output

Input

Output

{{ now | date('diff', issue.fields.created, 'minutes') }}

32

{{ now | date('diff', issue.fields.created, 'days') }}

0



businessDiff

Description:

Calculates the difference between the input date and the specified date, in business days, i.e. excluding Saturdays and Sundays. It applies to a string representing a date, or a Moment.js date object.

Syntax:

{{ <StringOrMoment.jsDateObject> | date("businessDiff", [otherDate] ) }}

Parameters:

otherDate: A string representing a date, or a Moment.js date object. If not specified, uses the current date/time.

Examples:

{{"2018-10-13" | date("businessDiff")}} returns a string representing the difference between the input date and current date in business days.

{{ "2018-10-13" | date("businessDiff", "2018-05-13") }} returns 110 business days.

{{ "2018-05-13" | date("businessDiff", "2018-10-13") }} returns -110 business days

{{ issue.fields.created | date("businessDiff") }} returns the business days between the issue creation date and now

businessAdd

Description:

Adds a specific number of days to a date, skipping non-business days. This applies to a string representing a date, or a Moment.js date object.

Syntax:

{{ <StringOrMoment.jsDateObject> | date("businessAdd", amount ) }}

Parameters:

amount: The number of business days to add.

Examples:

{{ "2018-02-15" | date("businessAdd",2) | date("YYYY-MM-DD") }} returns 2018-02-19.

{{ issue.fields.duedate| date("businessAdd",2) | date("YYYY-MM-DD") }} returns a date adding two business days to the issue Due date

businessSubtract

Description:

Subtracts a specific number of days to a date, skipping non-business days. This applies to a string representing a date, or a Moment.js date object.

Syntax:

{{ <StringOrMoment.jsDateObject> | date("businessSubtract", amount ) }}

Parameters:

amount: The number of business days to add.

Examples:

"2018-02-19" | date("businessSubtract",2) | date("YYYY-MM-DD") returns 2018-02-15.

{{ issue.fields.duedate| date("businessSubtract",2) | date("YYYY-MM-DD") }} returns a date subtracting two business days to the issue Due date.

nextBusinessDay

Description:

Returns the next business day after the specified date. This applies to a string representing a date, or a Moment.js date object.

Syntax:

{{ <StringOrMoment.jsDateObject> | date("nextBusinessDay") }}

Examples:

"2018-02-16" | date("nextBusinessDay") | date("YYYY-MM-DD") returns 2018-02-19.

{{ issue.fields.created | date("nextBusinessDay") | date("YYYY-MM-DD") }} returns the next business day after the issue creation.

prevBusinessDay

Description:

Returns the business day before the specified date. This applies to a string representing a date, or a Moment.js date object.

Syntax:

{{ <StringOrMoment.jsDateObject> | date("prevBusinessDay") }}

Examples:

"2018-02-19" | date("prevBusinessDay") | date("YYYY-MM-DD") returns 2018-02-16

{{ issue.fields.created | date("prevBusinessDay") | date("YYYY-MM-DD") }} returns the previous business day before the issue creation.

isBusinessDay

Description:

Returns true if the specified date is a business day. This applies to a string representing a date, or a Moment.js date object.

Syntax:

{{ <StringOrMoment.jsDateObject> | date("isBusinessDay") }}

Examples:

{{ "2018-02-13" | date("isBusinessDay") }}returns true

{{ issue.fields.created | date("isBusinessDay") }} returns true if the issue is created on a business day.

Date formatting

You might want to display a date in specific format after or before manipulating it. Momentjs provides some methods to display a date in different formats. 

format

Description:

This method takes a string of tokens and replaces them with the corresponding values. If the field (on which the method is applied) is invalid the result is an Invalid date string.

Syntax:

{{ DATE | date(format) }}

Examples:

Format

Output

Format

Output

{{ now | date }}

2016-10-14T07:26:27Z

{{ now | date('dddd, MMMM Do YYYY, h:mm:ss a') }}

Fri, October 14th 2016, 7:26:27 am

{{ issue.fields.duedate | date ('YYYY MMMM') }}

2016 October

List of tokens:





Token



Output

Example

Token

Output

Month

M

1 2 3 .... 11 12

{{ now | date ('M') }}

October



Mo

1st 2nd 3rd .... 11th 12th

{{ now | date ('Mo') }}

10th



MM

01 02 03 .... 11 12

{{ now | date ('MM') }}

10



MMM

Jan Feb Mar ... Nov Dec

{{ now | date ('MMM') }}

Oct



MMMM

January February ... December

{{ now | date ('MMMM') }}

October

Quarter

Q

1 2 3 4

{{ now | date ('Q') }}

4



Qo

1st 2nd 3rd 4th

{{ now | date ('Qo') }}

4th

Day of Month

D

1 2 3 4 5 .... 28 29 30 31

{{ now | date ('D') }}

14



Do

1st 2nd 3rd... 30th 31st

{{ now | date ('Do') }}

14th



DD

01 02 03 .... 30 31

{{ now | date ('DD') }}

14

Day of Year

DDD

1 2 ... 364 365

{{ now | date ('DDD') }}

288



DDDo

1st 2nd 3rd .... 364th 365th

{{ now | date ('DDDo') }}

288th



DDDD

001 002 003 ... 364 365

{{ now | date ('DDDD') }}

288

Day of Week

d

0 1 2 3 4 5 6

{{ now | date ('d') }}

5



do

0th 1st 2nd 3rd 4th 5th 6th

{{ now | date ('do') }}

5th



dd

Su Mo Tu We Th Fr Sa

{{ now | date ('dd') }}

Fr



ddd

Sun Mon Tue Wed Thu Fri Sat

{{ now | date ('ddd') }}

Fri



dddd

Sunday Monday ... Saturday

{{ now | date ('dddd') }}

Friday

Day of Week (Locale)

e

0 1 2 3 4 5 6

{{ now | date ('e') }}

5

Day of Week (ISO)

E

1 2 3 4 5 6 7

{{ now | date ('E') }}

5

Week of Year

w

1 2 3 .. 52 53