Info |
---|
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 documentationapp. |
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 be used to perform custom filtering and grouping of work logsworklogs. 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:
Table of Contents | ||
---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
...
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 rfWorklogsthe rfWorklogs custom field using the operator '~' (CONTAINS). The syntax is rfWorklogs ~ "WQL query"
. For example:
Info | icon | false
---|
|
...
For details on the WQL syntax, see our Worklog Query Language (WQL) page.
Anchor | ||||
---|---|---|---|---|
|
...
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 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 the work log level – all the work logs of the returned issues are included in the final result.
The two examples below shows show 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
...
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
theJira's issue navigator – the query returns all the issues containing at least one work log satisfying the WQL query
when used to aggregate
work logworklog values (Worklog Time Spent) – the query returns the work logs (belonging to the returned issues) satisfying the WQL query
Tip |
---|
The work log queries can be applied only to It is possible to apply worklog queries to only some of the issues. For instance, the base JQL query:
returns:
|
Note |
---|
Do not use worklog queries in referenced Jira filtersThe ability to filter at the work log level provided by the WQL can work only if the worklog queries are directly available to the app – i.e. if they are used in the “top-level” JQL – as opposed to being used in a separate Jira filter that is referenced in the JQL available to the app. Indeed, when a clause of the type |
Note |
---|
Jira's native searching based on work log attributesJira also provides native support for JQL searches based on work log attributes via the JQL fields |
Anchor | ||||
---|---|---|---|---|
|
...
Worklog filtering in rich filter configurations
As stated before, JQL filters containing work log 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 at the same timesimultaneously.
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:
...
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:
Info | icon | false
---|
|
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.
Note | |
---|---|
title | Accepted work log queries in rich filtersWe've seen how we can to 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 For example, you can use this JQL:
but you cannot use:
The second JQL combines two work log searches through an AND. You Just as in the first example, you need to AND all WQL clauses in the same work log query just as it the first example. |
Anchor | ||||
---|---|---|---|---|
|
...
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 |
---|---|---|
|
|
|
|
| ||
|
| |
|
|
|
|
|
|
|
Anchor | ||||
---|---|---|---|---|
|
Jira allows administrators and users to restrict work log visibility via two mechanisms: at the project level, via the timetime-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 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.
Note |
---|
Integration with TempoIf Tempo (Timesheets by Tempo - Jira Time Tracking) is installed on your Jira instance, then different work log visibility restrictions apply. Tempo provides different permission mechanisms for work log visibility – to learn more about work log visibility restrictions when Tempo is installed, please refer to the Integration with Tempo documentation section. |
...