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")) → 10CALENDAR_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")) → 240CALENDAR_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. |
| 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")) → 3JIRA_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")) → 2JIRA_WEEKS(DURATION("5d")) → 3