This documentation relates to an older version 1.1 of Rich Filters::Time Tracking Dashboards. See the documentation index for other versions.
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:
- 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:
- Constructing WQL queries
- Setting the precedence of operators in WQL queries
- 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:
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:
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
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
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|
Text searches need to be surrounded by quote-marks (single or double). See the Quote-marks in WQL note below.
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\''