This documentation relates to version 1.2 of Rich Filters::Time Tracking Dashboards. Documentation for previous versions is available via the documentation index.
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.
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 work logs, and by the other rich filter statistics and chart gadgets to generate links to the issue navigator. If you don't already know how the dynamic filtering and grouping of work logs works, make sure you first understand our Key Concepts.
The same mechanism can also be used to perform custom filtering and grouping of work logs. 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)
- Work log filtering
- Work log filtering in rich filter configurations
- rfWorklog searching
- Work log permissions
1. 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:
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.
2. Work log 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 also 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 they also filter the work logs of the returned issues. In contrast, JQL searches not containing WQL queries do not apply any additional filtering at work log level – all the work logs of the returned issues are included in the final result.
The two examples below shows this. Both 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 having the priority Highest. The total time spent 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 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 having work logs with Worklog Date after September 1st, 2018. The total time spent logged in the work logs having the Worklog Date after September 1st, 2018 is 18w 4d 7h. The 85 issues might contain other work logs with the Worklog Date before September 1st, 2018, but these are not aggregated by Worklog Time Spent 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 the Jira's issue navigator – the query returns all the issues containing at least one work log satisfying the WQL query
- when used to aggregate work log values (Worklog Time Spent) – the query returns the work logs (belonging to the returned issues) satisfying the WQL query
The work log queries can be applied only to some of the issues. For instance, the base JQL query:
priority = Highest OR rfWorklog ~ "dateStarted >= 2018-09-01"
- when applied at issue level: all the issues having either priority Highest or containing work logged after September 1st, 2018
- when applied at work log level: all the work logs belonging either to issues having priority Highest or having the Worklog Date after September 1st, 2018
Jira's native searching based on work log attributes
Jira also provides native support for JQL searches based on work log attributes via the JQL fields
worklogComment. This functionality can be used to filter the issues but, when used in rich filter gadgets, they do not also filter the work logs of the returned issues. In addition, combining multiple clauses using the native
worklog JQL fields can be tricky. We recommend you use only WQL for queries used with rich filter gadgets.
3. Work log filtering in rich filter configurations
As stated before, JQL filters containing work log 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 at the same time.
In the following example, we define a static filter called Time spent this month in order 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 of the smart filter have been merged together into a single WQL query. The same could have been done with the base filter, with the gadgets’ working queries, or with time series.
Accepted work log queries in rich filters
We've seen how we can use JQL to combine issue searches and work log searches. Nevertheless, in order to avoid useless complexity, when used in rich filter configurations, multiple work log queries cannot be AND-ed. More precisely, the JQLs accepted in rich filter configurations need to have the form:
[JQL | WQL | JQL AND WQL] OR*
where JQL denotes queries which do not contain any WQL, and WQL denotes JQL queries of the form
rfWorklog ~ "custom WQL query".
For example, you can use this JQL:
project = EUSD AND rfWorklog ~ "author = abrown AND dateStarted >= startOfMonth()"
but you cannot use:
project = EUSD AND rfWorklog ~ "author = abrown" AND rfWorklog ~ "dateStarted >= startOfMonth()"
The second JQL combines two work log searches through an AND. You need to AND all WQL clauses in the same work log query just as it the first example.
4. rfWorklog searching
We've seen that the
rfWorklog custom field can be used to 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 that has 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.