Duration Functions

Duration is represented as a number of milliseconds. To create a value or make sense of a value, you need one of the following functions to convert a string to a duration and vice versa.

You can add duration to a date or date/time value and treat the result as a new date/time, but only if it's a calendar duration. This does not work with work duration.

To understand why, let's consider you wanted to add 16 hours at a date or date/time. The result should be slightly less than a day later. However, when using work duration, adding 16 hours will result in a date at least 2 days later (maybe more, if it crosses a weekend), based on Jira's default 8h/day 5-day work week.

CALENDAR_DAYS

CALENDAR_DAYS(Duration)

Returns a number of calendar days represented by the duration value as a decimal number.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Number of calendar days. May return a fractional number of days.

Examples:

CALENDAR_DAYS(DURATION("10d")) → 10
CALENDAR_DAYS(DURATION("12h")) → 0.5

CALENDAR_HOURS

CALENDAR_HOURS(Duration)

Returns a number of hours represented by the duration value as a decimal number.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Number of hours. May return a fractional number of hours.

Examples:

CALENDAR_HOURS(DURATION("10d")) → 240
CALENDAR_HOURS(DURATION("12h 45m")) → 12.75

CALENDAR_MINUTES

CALENDAR_MINUTES(Duration)

Returns a number of minutes represented by the duration value as a decimal number.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Number of minutes. May return a fractional number of minutes.

Example:

CALENDAR_MINUTES(DURATION("3h")) → 180

CALENDAR_SECONDS

CALENDAR_SECONDS(Duration)

Returns a number of seconds represented by the duration value as a decimal number.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Number of calendar seconds. May return a fractional number of seconds.

Example:

CALENDAR_SECONDS(DURATION("1h")) → 3600

CALENDAR_DURATION

CALENDAR_DURATION(Start, Finish, Calendar)

Returns the time spent between start and finish according to the chosen calendar. Be aware that calendars supplied by Structure do not depend on the user's time zone (system time zone is used), but some functions (like DATETIME) do. Other calendars may or may not depend on the user's time zone depending on the implementation.

Parameter	Type	Description
`Start`	`Date`	Date or date/time value to start counting calendar time.
`Finish`	`Date`	Date or date/time value to finish counting calendar time.
`Calendar (Optional)`	`Text`	Calendar name in current user locale. If omitted, the default (24/7) calendar is used, and the result would be equal to (Finish - Start).
→ Result	`Number`	Duration in milliseconds.

Example:

CALENDAR_DURATION(DATE("18/Jul/2022"), DATE("19/Jul/2022"), "Standard work calendar 8/5") → 28800000 (8h in milliseconds)

DURATION

DURATION(Text)

Converts a text representation of a calendar duration to a number.

This function ignores Jira's settings for work time, so DURATION("1w") = DURATION("7d") and DURATION("1d") = DURATION("24h").To consider work time, use JIRA_DURATION.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Duration in milliseconds.

Examples:

DURATION("1w 2d 3h 4m")
DURATION("3d")

FORMAT_DURATION

FORMAT_DURATION(Duration)

Converts duration value to the Jira format with numbers followed by symbols specifying the time unit.

Parameter	Type	Description
`Duration`	`Number/Each`	Duration value in number format.
→ Result	Text	Duration value converted to Jira Duration format (1d 3h 30m).

Example:

FORMAT_DURATION(DURATION("1w 1d")) → "1w 1d"

JIRA_DAYS

JIRA_DAYS(Duration)

Returns a number of work days in the specified duration according to Jira's settings.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Number of work days. (By default, one day is 8 hours.) May return a fractional number.

Example:

JIRA_DAYS(DURATION("24h")) → 3
JIRA_DAYS(DURATION("12h")) → 1.5

JIRA_DURATION

JIRA_DURATION(Text)

Converts a text representation of a Jira work duration to a number.

The specified time is work time, according to Jira's settings. With the default Jira settings, JIRA_DURATION("1w") = JIRA_DURATION("5d") and JIRA_DURATION("1d") = JIRA_DURATION("8h"). To use calendar time, use DURATION.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Duration in milliseconds.

Examples:

JIRA_DURATION("1w 2d 3h 4m")
JIRA_DURATION("3d")

JIRA_WEEKS

JIRA_WEEKS(Duration)

Returns a number of work weeks in the specified duration according to Jira's settings.

Parameter	Type	Description
`Duration`	`Text/Each`	Value expressed in Jira Duration format (1d 3h 30m).
→ Result	`Number`	Number of work days. (By default, one week is 5 work days.) May return a fractional number.

Example:

JIRA_WEEKS(JIRA_DURATION("10d")) → 2
JIRA_WEEKS(DURATION("5d")) → 3