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

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 Type	Work Log Attributes	Supported Operators	Values / Supported Functions	Examples
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`	Jira search syntax for text fields 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\''