This documentation relates to an older version 1.1 of Rich Filters::Time Tracking Dashboards. See the documentation index for other versions.

Worklog Query Language (WQL)

Rich Filters::Time Tracking Dashboards is an extension of the Rich Filters for Jira Dashboards app. If you are not already familiar with the rich filters, you should first have a look at the Rich Filters for Jira Dashboards documentation.

Rich Filters::Time Tracking Dashboards allows you to build structured work log queries using the Worklog Query Language (WQL). The work log queries are embedded in JQL through the rfWorklogs custom field which is automatically added by the app. When used in rich filters and rich filter gadgets, JQL queries containing work log queries will filter the issues and their work logs based on work log attributes. The results can then be aggregated either by issue values (issue count, issue numeric custom fields, issue time tracking fields) or by work log values (Worklog Time Spent).

The WQL queries are always embedded in JQL through the rfWorklogs custom field, and they follow either the operator '~' (CONTAINS) or '~!' (DOES NOT CONTAIN). The JQL query: 

rfWorklogs ~ "WQL query"

returns:

  • when used to aggregate issue values (issue count or issue value fields) or when used in the Jira's issue navigator – all the issues containing at least one work log satisfying the WQL query
  • when used to aggregate work log values (Worklog Time Spent) – all the work logs (belonging to the above issues) satisfying the WQL query

On this page:

  1. Constructing WQL queries
  2. Setting the precedence of operators in WQL queries
  3. Supported work log attributes and operators

1. Constructing WQL queries

The WQL syntax is very similar to the JQL syntax. A simple query in WQL (also known as a 'clause') consists of an work log attribute, followed by an operator, followed by one or more values or functions. For example:

rfWorklogs ~ "author = abrown"

The query uses the 'author' work log attribute, the EQUALS operator, and the value 'abrown'. This query will find all issues having work logged (at least one work log) by the user 'abrown'. Or from a functional point of view, we would say, all the issues on which 'abrown' has worked. The same query, when used to aggregate work log values, will return only the work logs having 'abrown' as author.

A more complex query might look like this:

rfWorklogs ~ "author = abrown AND dateStarted >= 2018-09-01"

This query will find all the issues having work logged (at least one work log) by the user 'abrown' since September 1st, 2018, inclusive. From a functional point of view, we would say, all the issues on which 'abrown' has worked since September 1st, 2018. The same query, when used to aggregate work log values, will return only the work logs containing work performed by 'abrown' since September 1st, 2018.

2. Setting the precedence of operators in WQL queries

You can use parentheses in complex WQL statements to enforce the precedence of operators. For example, the JQL query

rfWorklogs ~ "(dateStarted < 2018-08-01 OR dateStarted >= 2018-09-01) AND author = abrown"

returns the issues containing at least one work log and the work logs from the author 'abrown' containing work started before or after August 2018 (in other words, it excludes August 2018).

Note that if you do not use parentheses, the AND operator takes precedence over the OR operator. 

3. Supported work log attributes and operators

WQL supports the following work log attributes and operators:

Attribute TypeWork Log AttributesSupported OperatorsValues / Supported FunctionsExamples
User
  • author: the user who has performed the work.
    This is shown as Worklog Author in rich filter gadgets and dynamic filters.
  • updateAuthor: the last user who has edited the work log after its creation
  • =
  • !=
  • IN
  • NOT IN
  • username
  • native JQL functions available for user issue fields
  • work logs where the work is performed by 'abrown': author = abrown
  • work logs where the work is performed either by 'abrown' or 'ejones': author IN (abrown, ejones)
  • work logs where the work is performed by any member of the group 'jira-developers': author IN membersOf('jira-developers')
  • work logs where the work is performed by the logged-in user: author = currentUser()
Date time
  • dateStarted: date when the unit of work has started
    This is shown as Worklog Date in dynamic filters.
  • dateCreated: date when the work log was created
  • dateUpdated: date when the work log was last updated
  • >
  • >=
  • <
  • <=
  • Date/time values – valid formats include: 'yyyy/MM/dd HH:mm', 'yyyy-MM-dd HH:mm', 'yyyy/MM/dd', 'yyyy-MM-dd', period format e.g. '-5d', '4w 2d'. See the Quote-marks in WQL note below.
  • native JQL functions available for date/time issue fields
  • work logs started before September 1st 2018: dateStarted < 2018-09-01
  • work logs started during the last 5 days: dateStarted >= -5d
  • work logs that have been edited this week: dateUpdated >= startOfWeek()
Duration
  • timeSpent: the time spent to perform the work
  • =
  • !=
  • >
  • >=
  • <
  • <=
  • IN
  • NOT IN
  • duration values
  • work logs where the time spent is more than 2 hours: timeSpent > 2h
Text
  • comment: the work description added in the work log
  • ~
  • !~
  • IS
  • IS NOT

Text searches need to be surrounded by quote-marks (single or double). See the Quote-marks in WQL note below.

  • work logs with work descriptions containing the word "test": comment ~ 'test'
  • work logs with work descriptions containing any word starting with "win": comment ~ 'win*'
  • work logs without any work description: comment IS empty
Flag
  • wasUpdated: true if the work log has been edited after its creation
  • =
  • !=
  • YES, NO
  • 0, 1
  • TRUE, FALSE
  • SET, UNSET

TRUE, FALSE and SET are reserved JQL words. When used in queries, you need to surround them by quote-marks (single or double). See the Quote-marks in WQL note below.

  • work logs that have ever been edited: wasUpdated = yes

Quote-marks in WQL

Text search queries, date-time and duration values containing spaces (such as '2018/10/25 13:20' or '4w 2d'), and reserved JQL words need to be surrounded by quote-marks (single or double).

Because WQL is always used inside JQL queries, the entire WQL query will already be surrounded by one type of quote-marks. If you used one type of quote-mark (single or double) for the entire query, you should use the other type inside the WQL query. For example:

rfWorklogs ~ "wasUpdated = 'TRUE'"

You can also use the same type of quote-mark inside the WQL if you escape them using the character '\'. For example:

rfWorklogs ~ 'wasUpdated = \'TRUE\''