This page relates to version 1.3 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.
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 an 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
- Dynamic filters on work log attributes
- Statistics on work log attributes
- Issue fields vs. work log attributes
- Historical time tracking data
- The Worklog Query Language (WQL)
- Worklog indexing
1. 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 statistic and charts gadgets.
While all the other values are defined at issue level (issue count, issue numeric fields or issue time tracking fields), Worklog Time Spent aggregates the time spent values defined at work log level. This becomes relevant when used together with work log filters and work log statistic types, explained below.
2. Dynamic filters on work log attributes
After installing Rich Filters::Time Tracking Dashboards, the Dynamic filters configuration page for rich filters will allow adding dynamic filters on 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 displayed 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 which have 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 1st, 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 and which have been logged after September 1st, 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 1st, 2018. But these are not part of the Worklog Time Spent value because they have been filtered by the Worklog Date dynamic filter.
3. 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 together 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 the same issue can be included in more than one work log statistic category. 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 on which each author has logged work is greater or equal with the total number of issues. On the other hand, the sum of the work logged by each individual author is exactly equal with the total work logged on all the issues as each work log has exactly one author.
4. 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 together the issues and their work logs based on issue fields; work log statistic types will group together the issues and their work logs based on work log attributes
- 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 logs
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 spent on the New Features of the project GI by Eric Jones since September 1st 2018.
We could use Issue Count as an output value in the same example and 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 1st 2018.
Or, we could use a value defined at issue level (Business Value in this example is a numeric custom field). Because Business Value is defined at 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 1st, 2018.
Time Spent vs Worklog Time Spent
We can now understand the difference between the issue field Time Spent defined at issue level and the Worklog Time Spent value. The Time Spent field at 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 nor to 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 only the time logged by a particular author and/or during a particular time 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/or statistic types based on work logs are applied, the functional distinction between Worklog Time Spent and Time Spent becomes visible. Since September 1st, 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 1st, 2018 is 50w 2d 7h (this is the total time spent on these issue, by all the authors, during the entire existence of the issues).
5. Historical time tracking data
Time-based gadgets such as Rich Filters Time Series Chart and Rich Filter Date Bar Chart can display results based on the Worklog Date. Just as 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 which outputs the Worklog Time Spent. We can see in this chart how the 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 of course 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.
6. The Worklog Query Language (WQL)
When Rich Filters::Time Tracking Dashboards is installed, a new field called rfWorklog is automatically added, which can be used to perform work log queries via JQL. This 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. However, this mechanism can also be used to perform custom filtering and grouping of work logs.
It is possible to create searches on the rfWorklog field using an Worklog Query Language (WQL) added by the Rich Filters::Time Tracking Dashboards app. The general JQL syntax is
rfWorklog ~ "Custom WQL Filter". For example, in order to write a JQL filter which returns the issues having work logs logged since the start of the month we can write:
WQL queries are a very powerful mechanism because, when used in rich filters and rich filter gadgets, they filter and group both the issues and their work logs. 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 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
JQL filters containing WQL 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.
Below we show only some examples of WQL usage for advanced filtering and grouping. For details on how the work log filtering interacts with the rich filter gadgets, see our Advanced Work Log Searching page. For details 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 where 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 members of the team as well as the total time logged by these authors on the returned issues.
The same smart filter can be used as 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:
7. 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. Note that Jira's native background indexing (global or per project) does not index the work logs, it only indexes the issues. To correctly perform this operation, please see our Worklog Indexing page.