# Issues Perspective
The main purpose of the Issue perspective is to calculate metrics over issues stored in an issue tracker. These metrics can reveal weaknesses in your development process, such as long pending critical bugs, and help you to assess any steps toward process improvement over time. To use this perspective, your project must define at least one issue tracker connector when configuring your project.
|Use Cases||Evaluating Queries over Issues, Managing Issue Metrics|
|Views||Issue Query View|
|Actions||Query Issues, Display Issue Trend, Manage Issue Metrics|
# Performing an Issue Query
In the Issues perspective, you can enter queries:
For example, to display all open
closed = false into the query box. After pressing
Enter, the list of matching issues is displayed below the box.
The input box also provides autocompletion to simplify writing queries.
Each issue in the returned list provides a link to additional details,
as well as to the issue in the originating issue tracker. You should
keep in mind, that the default is to query all issues, including closed
one. To limit a query to open issues, add the phrase
# Issue Query Language
|Attributes||For each issue, the
default attributes |
|Comparison operators||Attributes can be
compared to values using the usual comparison operators |
|Set query||You can use the keyword
|Logical operators||Comparisons can be
connected using the logical operators |
Additionally, parentheses can be used to group subexpressions.
|membersOf||The special function
|currentUser||The special function
|baseline||The special function
|State queries||The operator
|Parent queries||The operator
An example returning all urgent issues that have not been closed within two weeks would be
inState(closed=false && tracker=Bug && priority in [urgent, blocker]) > 14d
To limit this to issues within the UI team, you can change this to
assignee in membersOf('UI team') && inState(closed=false && tracker=Bug && priority in [urgent, blocker]) > 14d
Note that the exact attributes will depend on your issue tracker and the fields that are configured. Also note the subtle difference between including the assignee check in the inState part or not. If we would include the assignee check in the inState part, this would cause issues to not be shown if the assignee changed in the 2 weeks.
# Action: Display Issue Trend
When an issue query has been executed, you can click on
Show trend and treemap
in the Issue Query View, to display a trend of the number of issues
matching the query over time. In addition, a treemap shows which files of your system were edited
in the course of the current issues in the list:
# Action: Manage Issue Metrics
There are certain queries which you might want to execute continuously and see the result regularly without re-formulating the query every time. Therefore, the Issue perspective also allows you to define issue metrics. An issue metric is the numeric result, i. e. the number of issues matching a query. By defining a metric, the underlying query is saved in Teamscale and, thus, can be used continuously.
These issue metrics are displayed in the sidebar:
To store a query as metric, execute
an issue query and click
Add as metric
in the Issue Query View. After entering a name, the metric will appear
in the sidebar. The list of metrics in the sidebar allows you to quickly
return to the corresponding query by clicking on its name, or to delete
the metric by clicking
Editing a metric works by recreating a metric with an existing name.
# Referencing Issue Metrics in Dashboards
The defined issue metrics are also available in the Dashboard perspective upon configuring dashboard widgets. The configuration of a widget offers you to define the scope of a widget by setting the corresponding path, which usually points to a (sub-) folder or (sub-) component of the system. To use issue metrics instead, use the path -issues- within a project. When the metric names include slashes, these are used to defined directories for grouping similar issue metrics. Good widgets for using the issue metrics are the Numeric Metric Value and the Single Metric Trend Chart widget
This allows you to track key indicators for your issue management process and react timely to any changes in the observed trend.
# Action: View Issue Details
A click on a issue from the issue list will open the Issue Details View:
The view subdivides into to following parts:
Issue meta data : This includes, among other information, the subject and the description of the issue, as well as the issue author and the current assignee.
Affected files : Lists all files known to Teamscale which have been edited during the implementation of the issue. This is determined based on the issue IDs in the commit messages.
Test Gap Treemap : Shows the test gaps in your code base introduced with this issue (see guide).
Associated repository changes Display all commits targeting the current issue. Note that only commits which changed files known to Teamscale are considered.