Advanced worklog searching
- Dan Mihalache
- Cristian Oancea
- Praveena Manohar
Rich Filters::Time Tracking Dashboards is an extension of the Rich Filters for Jira Dashboards app.
When Rich Filters::Time Tracking Dashboards is installed, a new field called rfWorklog is automatically added. The field can be used to perform work log queries via JQL. When used in rich filters and rich filter gadgets, the work log queries can filter and group the issues and their work logs. This mechanism is used by the Rich Filter Controller gadgets to provide dynamic filters on worklogs and by the other rich filter statistics and chart gadgets to generate links to the issue navigator. Check the key concepts page to learn how dynamic filtering and grouping based on work log attributes work.
The same mechanism can also perform custom filtering and grouping of worklogs. This is very powerful because JQL filters containing work log queries can be used anywhere in rich filters and rich filter gadgets where JQL is used: base filters, static and smart filters, time series, or gadget working queries.
On this page:
The Worklog Query Language (WQL)
The work log queries are expressed through the Worklog Query Language (WQL) added by the Rich Filters::Time Tracking Dashboards app. The WQL queries are embedded in JQL and are based on the rfWorklogs custom field using the operator '~' (CONTAINS). The syntax is rfWorklogs ~ "WQL query". For example:
rfWorklogs ~ "author = abrown"
returns all the issues containing at least one work log having 'abrown' as author (all issues on which the user 'abrown' has logged work).
For details on the WQL syntax, see our Worklog Query Language (WQL) page.
Worklog filtering
The rich filter statistics and charts can aggregate issue values (issue count, issue field values). After installing Rich Filters::Time Tracking Dashboards, the same gadgets can aggregate work log values (i.e., Worklog Time Spent). When used in the rich filter gadgets, JQL searches containing WQL queries have the particularity that they filter the issues but also filter the work logs of the returned issues. In contrast, JQL searches not containing WQL queries do not apply additional filtering at the work log level – all the work logs of the returned issues are included in the final result.
The two examples below show this. JQL queries are used as base filters in a Rich Filter Simple Counter, which outputs the Issue Count and the Worklog Time Spent. The difference is that only the second JQL contains a work log query.
Base JQL query:
project = EUSD AND priority = Highest
The project EUSD contains 46 issues with the highest priority. The total time logged by the work logs of these 46 issues is 12w 3d 2h. Because the JQL does not contain any work log filtering, the Worklog Time Spent aggregates all the work logs of the 46 issues (added by all the authors during the entire existence of the issues). In other words, at the work log level, JQL clauses without work log queries return all the work logs of the returned issues.Base JQL query:
project = EUSD AND rfWorklog ~ "dateStarted >= 2018-09-01"
The project EUSD contains 85 issues with work logs with a Worklog Date after September 1st, 2018. The total time spent logging in the work logs with a Worklog Date after September 1st, 2018, is 18w 4d 7h. The 85 issues might contain other work logs with a Worklog Date before September 1st, 2018, but Worklog Time Spent does not aggregate these because the work log filtering is applied.
In conclusion, the work log queries are embedded in JQL and perform a double filtering:
when used to aggregate issue values (issue count or issue value fields) or when used in Jira's issue navigator – the query returns all the issues containing at least one work log satisfying the WQL query
when used to aggregate worklog values (Worklog Time Spent) – the query returns the work logs (belonging to the returned issues) satisfying the WQL query
It is possible to apply worklog queries to only some of the issues. For instance, the base JQL query:
priority = Highest OR rfWorklog ~ "dateStarted >= 2018-09-01"
returns:
when applied at the issue level: all the issues having either priority Highest or containing work logged after September 1st, 2018
when applied at the work log level: all the work logs belonging to issues having priority Highest plus the work logs having the Worklog Date after September 1st, 2018
3. Worklog filtering in rich filter configurations
As stated, JQL filters containing worklog queries can be used anywhere in rich filters and rich filter gadgets: base filters, static and smart filters, time series or gadget working queries. Work log filtering can be used in all of these configuration elements simultaneously.
In the following example, we define a static filter called Time spent this month to filter only the work logs with dateStarted (the Worklog Date attribute) this month:
We can also define a smart filter to group the work logs by the author’s team:
We can now use the smart filter in a Rich Filter Two-Dimensional Statistics Gadget to see the time spent by Team and by Issue Type. The result can be further refined if we use the static filter in a Rich Filter Controller Gadget to see only the time spent since the start of the month:
In this case, 1w 1d 7h is the total time spent by the Alpha Team, since the start of the month, on Bug issues. If we click on the value, the JQL generated by the gadget combines correctly the WQL clauses:
Note that the WQL queries of the static filter and the smart filter have been merged together into a single WQL query. The same could have been done with the base filter, the gadgets’ working queries, or time series.
rfWorklog searching
We've seen that the rfWorklog custom field can express WQL queries via JQL. But rfWorklog can also be used with other operators and values. This section presents all the operators and all the values that can be used to query the rfWorklog field in JQL.
Operators | Values | Example / Description |
|---|---|---|
|
|
|
|
| |
|
|
|
5. Work log permissions
Jira allows administrators and users to restrict work log visibility via two mechanisms: at the project level, via the time-tracking permissions, and at the work log level, by setting the work logged to be visible only to members of a particular project role or group.
Rich Filters::Time Tracking Dashboards respects these restrictions: when you are performing WQL queries in the issue navigator and when you use them in rich filters, any work logs that the current user is not allowed to see are ignored. For example, rfWorklog IS NOT EMPTY will not return an issue with work logs if you are not allowed to see any of them. Similarly, rich filter gadgets based on work log attributes will never show results from work logs unless the current user can see those work logs.
In other words, if you cannot see a work log in the Work Log tab when you browse an issue (or you cannot see the tab at all), that work log will never contribute to any Rich Filters::Time Tracking Dashboards result.