Page History
...
Fields of type Date and Date and Time contain a numeric value with the milliseconds elapsed since January 1, 1970, 00:00:00 GMT. We usually need to get significative numbers from this numeric value, like YEAR, MONTH, DAY, HOUR, MINUTE, etc. To do it, Jira Workflow Toolbox provides a comprehensive set of functions, all of them with TIMEZONE as input argument, since any significative number relative to a timestamp depends on the timezone.
| Function | Returned value |
|---|---|
| timePart(number t, timeZone time_zone) : number | Returns the time part of timestamp represented by numeric value t in time_zone time zone. Example: for timestamp March, 25th 2011 23:15 this function returns a numeric value representing time 23:15 in milliseconds |
| datePart(number t, timeZone time_zone) : number | Returns the date part of timestamp represented by numeric value t in time_zone time zone. Example: for timestamp March, 25th 2011 23:15 this function returns a numeric value representing date March, 25th 2011 00:00 in milliseconds |
| second(number t, timeZone time_zone) : number | Returns the seconds figure of timestamp represented by numeric value t in time_zone time zone. Example: for timestamp March, 25th 2011 23:15:30 this function returns a numeric value representing 30 seconds in milliseconds. |
| minute(number t, timeZone time_zone) : number | Returns the minutes figure of timestamp represented by numeric value t in time_zone time zone. Example: for timestamp March, 25th 2011 23:15:30 this function returns a numeric value representing 15 minutes in milliseconds. |
| hour(number t, timeZone time_zone) : number | Returns the hours figure of timestamp represented by numeric value t in time_zone time zone. Example: for timestamp March, 25th 2011 23:15:30 this function returns a numeric value representing 23 hours in milliseconds. |
| dayOfTheWeek(number t, timeZone time_zone) : number | Returns the day of the week of timestamp represented by numeric value t in time_zone time zone, with Sunday = 1, Monday = 2, ... Saturday = 7. Example: for timestamp March, 25th 2011 23:15 this function returns 6 for Friday, represented also by macro {FRIDAY} . |
| dayOfTheMonth(number t, timeZone time_zone) : number | Returns the day of the month of timestamp represented by numeric value t in time_zone time zone. Example: for timestamp March, 25th 2011 23:15 this function returns 25. |
| month(number t, timeZone time_zone) : number | Returns the month of a timestamp represented by numeric value t in a certain time zone, with January = 1, February = 2, ... December = 12. Example: for timestamp March, 25th 2011 23:15 this function returns 3 for March, represented also by macro {MARCH} . |
| year(number t, timeZone time_zone) : number | Returns the year of a timestamp represented by numeric value t in a certain time zone. Example: for timestamp March, 25th 2011 23:15 this function returns 2011 . |
| addDays ( number t , number n , timeZone time_zone ) : number Available since version 2.3.3 | Returns a timestamp resultant of adding n days to timestamp t . You should use this function instead of simply adding n * {DAY} , since {DAY} is a macro equivalent to 24 * {HOUR} , not taking into account that once in a year we have a day with 25 or 23 hours due to DST transition. Negative values for n are used in order to subtract instead of adding. Example: addDays(2018/03/27 01:00, -2, LOCAL) returns 2018/03/25 01:00 . |
| addMonths(number t, number n, timeZone time_zone) : number | Returns a timestamp resultant of adding n months to timestamp t. You should use this function instead of simply adding n * {MONTH} , since {MONTH} is a macro equivalent to 30 * {DAY} , not taking into account that some months has more or less than 30 days. Negative values for n are used in order to subtract instead of adding. Example: for timestamp t with value March, 25th 2011 23:15 calling to addMonths(t, 3, LOCAL) will return a timestamp with value June, 25th 2011 23:15 |
| addYears(number t, number n, timeZone time_zone) : number | Returns a timestamp resultant of adding n years to timestamp t. You should use this function instead of simply adding 12 * {MONTH} or 365 * {DAY} , since that won't take into account that some years have 366 days. Negative values for n are used in order to subtract instead of adding. Example: for timestamp t with value March, 25th 2011 23:15 calling to addYears(t, 10, LOCAL) will return a timestamp with value March, 25th 2021 23:15 |
| addTimeSkippingWeekends(number t, number timeToBeAdded, timeZone time_zone) : number | Adds timeToBeAdded to t with the difference that weekends don't count in the sum, e.g., if t represents a date-time which coincides with a Saturday, adding timeToBeAdded = 2 * {HOUR} will return a date-time for next Monday at 02:00 . Use negative values at timeToBeAdded for subtracting time from t. |
| addTimeSkippingWeekends(number t, number timeToBeAdded, timeZone time_zone, number beginning_of_weekend, number end_of_weekend) : number Available since version 2.2.7 | Same as previous function, but with a custom defined weekend. Arguments beginning_of_weekend and end_of_weekend take values {MONDAY} , {TUESDAY} ... {SUNDAY} . Example of usage for adding 12 hours to Current date and time using Israeli weekend: addTimeSkippingWeekends({00057}, 12 * {HOUR}, LOCAL, {FRIDAY}, {SATURDAY}) , being {00057} field code for Current date and time. |
| addDaysSkippingWeekends(number t, number n, timeZone time_zone) : number | Returns a timestamp equivalent of Example: Set "Due date" 6 natural days (or work days) earlier than a "Date Picker" custom field |
| addDaysSkippingWeekends(number t, number n, timeZone time_zone, number beginning_of_weekend, number end_of_weekend) : number Available since version 2.2.7 | Same as previous function, but with a custom defined weekend. Arguments beginning_of_weekend and end_of_weekend take values {MONDAY}, {TUESDAY} ... {SUNDAY} . Example of usage for adding 10 workdays to Due date using Israeli weekend: addDaysSkippingWeekends({00012}, 10, LOCAL, {FRIDAY}, {SATURDAY}) , being {00012} field code for Due date. |
| subtractDatesSkippingWeekends(number minuend_date, number subtrahend_date, timeZone time_zone) : number | Returns a timestamp equivalent "minuend_date - subtrahend_date" subtracting weekend periods from the result, i.e., you get the elapsed working time from subtrahend_date to minuend_date. |
| subtractDatesSkippingWeekends(number minuend_date, number subtrahend_date, timeZone time_zone, number beginning_of_weekend, number end_of_weekend) : number Available since version 2.2.7 | Same as previous function, but with a custom defined weekend. Arguments beginning_of_weekend and end_of_weekend take values {MONDAY}, {TUESDAY} ... {SUNDAY} . Example of usage calculating the worktime from Creation to Resolution using Israeli weekend: subtractDatesSkippingWeekends({00112}, {00009}, LOCAL, {FRIDAY}, {SATURDAY}) , being {00112} field code for Resolution date and time, and {00009} field code for Creation date and time. |
| dateToString(number t, timeZone time_zone, language) : string | Returns a string representing the date-time value at t, in a certain time zone, and in a certain language. This function is useful in post-function Copy parsed text to a field to represent as a string the result of a time expression. |
| dateTimeToString(number t, timeZone time_zone, language) : string | Returns a string representing the date-time value at t, in a certain time zone, and in a certain language. This function is useful in post-function Copy parsed text to a field to represent as a string the result of a time expression. |
| dateTimeToString(number t, string date_time_pattern , language) : string Available since version 2.1.33 | Returns a string representing the date-time value at t with a certain custom format defined by date_time_pattern string parameter, using a certain language when using words for months, days of the week, etc. This function is useful in post-function Copy parsed text to a field to represent as a string the result of a time expression. Example: dateTimeToString(2011-03-25 11:30, "yyyy.MM.dd 'at' HH:mm:ss", USER_LANG) returns string "2011.03.25 at 11:30:00". |
| dateTimeToString(number t, string date_time_pattern , timeZone time_zone, language) : string Available since version 2.4.0 | Returns a string representing the date-time value at t with a certain custom format defined by date_time_pattern string parameter, in a certain timezone time_zone, using a certain language when using words for months, days of the week, etc. This function is useful in post-function Copy parsed text to a field to represent as a string the result of a time expression. Example: Example: |
| monthToString(number t, timeZone time_zone, language) : string | Returns a string with the name of the month for a date-time t, in a certain time zone, and in a certain language. This function can be used in post-function Copy parsed text to a field to write the name of the month of a date-time field or expression. |
| dayOfTheWeekToString(number t, timeZone time_zone, language) : string | Returns a string with the day of the week for a date-time t, in a certain time zone, and in a certain language. This function is useful in post-function Copy parsed text to a field to write the day of the week of a date-time field or expression. |
| stringToDate(string s, timeZone time_zone) : number Available since version 2.1.26 | Returns a numeric value with the date-time represented by string s. The numeric value returned corresponds to the milliseconds elapsed since January 1, 1970, 00:00:00 GMT. Valid input string formats are yyyy/MM/dd HH:mm, yyyy-MM-dd HH:mm, yyyy/MM/dd, yyyy-MM-dd, also formats relative to current time like in JQL queries: "w" (weeks), "d" (days), "h" (hours) or "m" (minutes), or format defined at system property jira.date.time.picker.java.format. Example: Validation based on a Date type Project Property |
| stringToDate(string s, string date_time_pattern ) : number Available since version 2.1.33 | Returns a numeric value with the date-time represented by string s. Expected format of value at parameter "s" is defined by date_time_pattern string parameter. The numeric value returned corresponds to the milliseconds elapsed since January 1, 1970, 00:00:00 GMT. Example: |
| stringToDate(string s, string date_time_pattern , string language , string country ) : number Available since version 2.2.29 | Returns a numeric value with the date-time represented by string s. Expected format of value at parameter "s" is defined by date_time_pattern string parameter for a specific language (language code ISO 639-2 ) and country (country code ISO 3166 alpha-2 ). The numeric value returned corresponds to the milliseconds elapsed since January 1, 1970, 00:00:00 GMT. Example: |
| formatDuration(number duration) : string Available since version 2.2.30 | Returns a string with the pretty representation of a time duration, i.e. a subtraction of 2 date-time values, using the language of current user's profile. Example: |
| shortFormatDuration(number duration) : string Available since version 2.2.30 | Returns a string with the most compact representation possible of a time duration, i.e. a subtraction of 2 date-time values, using the language of current user's profile. Example: |
| formatWorkDuration(number duration) : string Available since version 2.2.34 | Similar to function Example: |
| shortFormatWorkDuration(number duration) : string Available since version 2.2.34 | Similar to function shortFormatDuration() but using the workday and workweek defined at time tracking configuration , instead of 24 hours per day and 7 days per week. Example: |
| timeZone(string timeZone_name) : timeZone Available since version 2.2.39 | Returns the timeZone whose name is represented by string timeZone_name. This function is useful to obtain a timeZone from a string, like the value of a Project Properties. Example: |
| timeInStatus(string status_name) : number Available since version 2.4.4 | Returns the number of milliseconds the current issue has remained in a status with name status_name. If an issue has been in that status more than once, then duration will be summed up and the total time spent in the status will be returned. Example: In order to display this value in a more readable way, the milliseconds should be transformed into a more readable unit, like in the following example:
|
| timeInStatus(string status_name, string schedule_name, timeZone time_zone) : number Available since version 2.4.4 | Returns the number of milliseconds the current issue has remained in a status with name status_namewithin a schedule named schedule_name for a given time_zone timeZone. If an issue has been in that status more than once, then duration will be summed up and the total time spent in the status will be returned. Example: |
| timeInStatus(string status_name, issue list issues) : number Available since version 2.4.4 | Returns the sum of milliseconds issues in an issue list issues have remained in a status with namestatus_name. If an issue from that list has been in that status more than once, then duration will be summed up and the total time spent in the status will be returned. Example: |
| timeInStatus(string status_name, issue list issues, string schedule_name, timeZone time_zone) : number Available since version 2.4.4 | Returns the sum of milliseconds issues in an issue list issues have remained in a status with namestatus_name within a schedule named schedule_name for a given time_zone timeZone. If an issue from that list has been in that status more than once, then duration will be summed up and the total time spent in the status will be returned. Example: |
...
| Code Block |
|---|
MON - THU { 08:00 - 15:30, 16:00 - 19:30; } FRI { 08:00 - 15:00; } |
Note that 2017/04/21 and 2017/12/01 are Fridays.
Custom schedules are defined at Administration > Add-ons > JIRA WORKFLOW TOOLBOX > Schedules .
Time Macros
Date-Time values are numeric values representing the number of milliseconds elapsed since January 1, 1970, 00:00:00 GMT. Macros are aliases for literal values. A comprehensive set of time macros is provided to make your expressions more readable.
...
