Advanced worklog searching

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:

1 The Worklog Query Language (WQL)
2 Worklog filtering
- 2.1 Do not use worklog queries in referenced Jira filters
- 2.2 Jira's native searching based on work log attributes
3 3. Worklog filtering in rich filter configurations
- 3.1 Accepted work log queries in rich filters
4 rfWorklog searching
5 5. Work log permissions
- 5.1 Integration with Tempo

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 37 issues with the highest priority. The total time logged by the work logs of these 37 issues is 8w 2d 2h. Because the JQL does not contain any work log filtering, the Worklog Time Spent aggregates all the work logs of the 37 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 93 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 20w 2d. The 93 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

Do not use worklog queries in referenced Jira filters

The 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 filter = <filter ID> is used in the JQL, the rich filter gadgets can only see which issues are selected by this filter, so any worklog queries present inside it do not have the worklog-level filtering effect.

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 worklogAuthor, worklogDate, and worklogComment. This functionality can be used to filter issues, but when used in rich filter gadgets, it does 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. 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: rfWorklog ~ "dateStarted >= startOfMonth()"

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, 2w 3d 5h is the total time spent by the Alpha Team, since the start of the month, on Bug issues. If we click the value, the JQL generated by the gadget combines correctly the WQL clauses:

issuetype = Bug AND rfWorklog ~ "(dateStarted >= startOfMonth() AND author in (cdavies, wtaylor, gwalker))"

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.

Accepted work log queries in rich filters

We've seen how to use JQL to combine issue and work log searches. Nevertheless, 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. Just as in the first example, you need to AND all WQL clauses in the same work log query.

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

Operators	Values	Example / Description
CONTAINS: ~ DOES NOT CONTAIN: !~	WQL Query	The JQL: `rfWorklogs ~ "WQL query"` Returns all the issues containing at least one work log that satisfies the WQL query. For details on the WQL syntax, see the Worklog Query Language (WQL) page. The JQL: `rfWorklogs !~ "WQL query"` Returns all the issues containing at least one work log that satisfies the negation of the WQL query. It is equivalent to `rfWorklogs ~ "NOT (WQL query)"`. Note that this can be confusing (someone might expect it to mean “issues that do not contain a work log that satisfies the query”), so we recommend you put all negations inside the WQL instead of using the `!~` operator.
CONTAINS: ~ DOES NOT CONTAIN: !~	The keyword `Irrelevant`	The JQL: `rfWorklog ~ Irrelevant` Returns all the issues having the Time Tracking field hidden from the field configuration scheme (hence disabling the time tracking functionality) The JQL: `rfWorklog !~ Irrelevant` Returns all the issues having the Time Tracking field enabled. This can also include issues with no work logs (because none has been logged yet)
IS IS NOT	The keyword `EMPTY`	The JQL: `rfWorklog IS EMPTY` Returns all the issues with the Time Tracking field enabled but with no work logs yet. The JQL: `rfWorklog IS NOT EMPTY` Returns all the issues with the Time Tracking field enabled and having at least one work log.