Key concepts

Owned by Dan Mihalache
Last updated: Jun 05, 2024 by Praveena Manohar
10 min read

Rich Filters::Time Tracking Dashboards is an extension of the Rich Filters for Jira Dashboards app. 

Unlike Rich Filters for Jira Dashboards, which filters and displays statistics and charts based on issues, Rich Filters::Time Tracking Dashboards filters and displays statistics and charts based on work logs. The filters, statistics, and charts based on work logs are useful when building dashboards for time tracking purposes, where it is important to easily see the total time spent by a user or group of users (e.g., a given team) during a particular time period (e.g., last month). 

To learn how the Rich Filters::Time Tracking Dashboards app works, it is important to understand the following concepts:

The Worklog Time Spent value

After installing Rich Filters::Time Tracking Dashboards, a new output value called Worklog Time Spent appears in the configuration form of most of the rich filter statistics and charts gadgets. 

While all the other values are defined at the issue level (issue count, issue numeric fields, or issue time tracking fields), Worklog Time Spent aggregates the time spent values defined at the work log level. As explained below, this becomes relevant with work log filters and work log statistic types.

Dynamic filters on work log attributes

After installing Rich Filters::Time Tracking Dashboards, the Dynamic Filters configuration page for rich filters will allow dynamic filters to be added to work log attributes—Worklog Author, Worklog Date, and Worklog Comment. Like all the other dynamic filters, the work log dynamic filters can be displayed in the Rich Filter Controller gadget, and they impact the results shown by the other gadgets on the dashboard.

Work log dynamic filters function just like the usual dynamic filters on issue fields: they filter the issues with work logs (at least one work log) satisfying the selected condition. However, work log dynamic filters further filter the work logs of these issues.

The example below shows this using a Rich Filter Controller Gadget with dynamic filters based on work log attributes and a Rich Filter Counter Gadget which displays the Issue Count and the Worklog Time Spent:

  • 263 is the number of issues having at least one work log added after September 1, 2018. The filter on Worklog Date has filtered the issues

  • At the same time, 78w 4d 1h is the total time spent logged in the work logs belonging to the 263 issues logged after September 1, 2018. The filter on Worklog Date has also filtered the work logs of the issues

Note that the 263 issues might have other work logs, too, logged before September 1, 2018. But these are not part of the Worklog Time Spent value because the Worklog Date dynamic filter has filtered them.

Statistics on work log attributes

After installing Rich Filters::Time Tracking Dashboards, a new section called Worklog attributes appears in the Statistic type section of the rich filter statistics gadgets. This section contains work log attributes that can be used as statistics criteria – Worklog Author and Worklog Date.

Work log statistics group the issues and their work logs based on work log attributes.

The example below shows this using the (one-dimensional) Rich Filter Statistics Gadget, which shows statistics using the Worklog Author as statistic criteria and displays the Issue Count and the Worklog Time Spent: 

  • Each Issue Count row shows the number of issues containing work logged (at least one work log) by each corresponding Worklog Author

  • Each Worklog Time Spent row shows the total time spent by each Worklog Author in the work logs of these issues

Note that multiple work log statistic categories can include the same issue. Indeed, each issue can contain multiple work logs by different authors (e.g., a developer and a tester may both log work on the same issue). Hence, the sum of the issues each author has logged is greater or equal to the total number of issues. On the other hand, the sum of the work logged by each individual author is exactly equal to the total work logged on all the issues, as each work log has exactly one author. 

Issue fields vs. work log attributes

You can easily combine filters on issue fields with filters on work log attributes, statistics on issue fields with statistics on work log attributes, and values based on issues with values based on work logs:

  • Issue filters will filter the issues, but they do not further filter the work logs of these issues; work log filters will filter both the issues and the work logs of these issues

  • Issue statistic types will group the issues and their work logs based on issue fields; work log statistic types will group the issues and their work logs based on the work log attribute.s

  • Values based on issues will aggregate the values of the issues; values based on work logs (Worklog Time Spent) will aggregate the values of the work log.s

This is shown in the following example, where both the dynamic filter on Project (filters the issues) and the dynamic filter on Worklog Date (filters the remaining issues and their work logs) are used. In the same example, we display a Rich Filter Two Dimensional Statistics gadget, which displays results based on the Issue Type (groups the issues) and Worklog Author (groups the issues and their work logs). The gadget aggregates the Worklog Time Spent values.

In the highlighted cell, 3d 7h is the total time Eric Jones has spent on the New Features of the project GI since September 1, 2018.

We could use Issue Count as an output value in the same example, but the functional interpretation would be different. 7 is the number of New Features from the project GI on which Eric Jones has logged work since September 1, 2018.

Or, we could use a value defined at the issue level (Business Value in this example is a numeric custom field). Because Business Value is defined at the issue level, the Business Values of all the issues in each column and row are aggregated – 18 is the total Business Value of all the New Features from the project GI, on which Eric Jones has logged work since September 1, 2018.

Time Spent vs. Worklog Time Spent

We can now understand the difference between the issue field Time Spent defined at the issue level and the Worklog Time Spent value. The Time Spent field at the issue level is the sum of all the time spent values logged in all the work logs of an issue; it is not linked to an author or the time period when the work was accomplished. The Worklog Time Spent attribute, however, is linked to the author and period when the work was performed. It provides a lot more granularity as it allows you to aggregate only some of the work logs, for instance, the time logged by a particular author and/or during a particular period. 

When no filtering or grouping on the work logs is applied, Worklog Time Spent and Time Spent return the same thing – the total time spent logged on the issues returned by the rich filter:

But when filters and statistic types based on work logs are applied, the functional distinction between Worklog Time Spent and Time Spent becomes visible. Since September 1, 2018, Amanda Bown has logged 8w 1d 2h on the issues returned by the rich filter. The total time spent on the issues on which Amanda Brown has logged work since September 1, 2018, is 50w 2d 7h (this is the total time spent on this issue by all the authors during the entire existence of the issues).

Historical time tracking data

Time-based gadgets such as Rich Filter Time Series Charts, and Rich Filter Date Bar Charts can display results based on the Worklog Date. Like any other statistic based on the work log statistic types, charts based on the Worklog Date will group the work logs by date.

This is shown in the following example, where we display a time series based on the Worklog Date and output the Worklog Time Spent. In this chart, we can see how the time spent has evolved from one week to the other for the last 16 weeks.

Time series based on the Worklog Date can further filter their issues if additional JQL filtering is used. In the following example, we have defined a time series – Maintenance Time Spent – which aggregates only the Worklog Time Spent of the issues with the issue type Bug.

The time series can be combined with quick filters based on issues or work logs. In the following example, we can see how the time spent on the project EUSD has evolved for the three selected Worklog Authors, both for all the issues and for Maintenance (Bugs) only.

The Worklog Query Language (WQL)

When Rich Filters::Time Tracking Dashboards is installed, a new field called rfWorklog is automatically added. This field can be used to perform work log queries via JQL. The Rich Filter Controller gadgets use this to provide dynamic filters on work logs, and the other rich filter statistics and chart gadgets generate links to the issue navigator. However, this mechanism can also perform custom filtering and grouping of work logs.

Creating searches on the rfWorklog field is possible using a Worklog Query Language (WQL) added by the Rich Filters::Time Tracking Dashboards app. The general JQL syntax is rfWorklog ~ "Custom WQL Filter." For example, to write a JQL filter that returns the issues having work logs logged since the start of the month, we can write:

rfWorklog ~ "dateStarted >= startOfMonth()"

WQL queries are a very powerful mechanism because they filter and group both the issues and their work logs when used in rich filters and rich filter gadgets. Indeed, 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 work log values (Worklog Time Spent) – the query returns the work logs (belonging to the returned issues) satisfying the WQL query

JQL filters containing WQL queries can be used anywhere in rich filters and rich filter gadgets, such as base filters, static and smart filters, time series, or gadget working queries.

Below, we only show examples of WQL usage for advanced filtering and grouping. For more details on how the work log filtering interacts with the rich filter gadgets, see our Advanced Work Log Searching page. For more information on the WQL syntax, see our Worklog Query Language page.

In the following examples, we define a Smart Filter called Team Worklogs, which filters the issues and their work logs by groups of authors:

Once defined, the smart filter can be used anywhere a smart filter can be used. It could, for instance, be used for filtering in a Rich Filter Controller gadget. When Alpha Team is selected, the Rich Filter Simple Counter gadget displays the number of issues, having work logs added by the team members and the total time these authors logged on the returned issues.

The same smart filter can be used as a split type in a Date Bar Chart gadget based on the Worklog Date and Worklog Time Spent to display the time spent by each of the two groups for each time period: 

Worklog indexing

Because it filters, groups and aggregates work log attributes, Rich Filters::Time Tracking Dashboards needs to index the work logs on your instance after it is installed. Until this operation is performed, the filters and statistics based on work logs will not return correct results. Only Jira Administrators can index the work logs.