---
url: /reference/ui/activity/issues.md
---
# Issues View

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](../../../../howto/creating-a-project/).

## Performing an Issue Query

In the Issues perspective, you can enter queries:

![Issue Query](./issue-query.png)

For example, to display all open
issues, enter `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
ones. To limit a query to open issues, add the phrase `closed=false`.

### Issue Query Language

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.

## 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:

![Issue Trend](./issue-trend.png)

## Manage Issue Queries

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 save issue queries for later use.
For saved issue queries Teamscale calculates metrics on the issues that match the query, i.e., the number of issues matching.

These stored issue queries are displayed in the sidebar:

![Issue Queries in Sidebar](./issue-sidebar.png)

To store a query, execute an issue query and click `Save Query` in the *Issue Query View*.
After entering a name, the metric will appear in the sidebar.
The list of queries in the sidebar allows you to quickly return to the corresponding query by clicking on its name, or to delete the query by clicking .
Editing a query works by recreating a query with an existing name.

### Referencing Stored Issue Queries in Dashboards

The defined issue queries are also available in the [Dashboard perspective](../../dashboard/) 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 queries instead, use the path *-issues-* within a project.
When the query names include slashes, these are used to define directories for grouping similar issue queries.
*Numeric Metric Value* and the *Single Metric Trend Chart* widget are good widgets for using the issue queries.

![Issue Queries in Dashboard Widgets](./issue-dashboard-widgets.png)

This allows you to track key indicators for your issue management process and react timely to any changes in the observed trend.

## View Issue Details

A click on an issue from the issue list will open the *Issue Details View*:

![Image: issue-details-view](./issue-details-view.png)

The view subdivides into the 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 or branch names](../../../connector-options/index.md#issue-tracker-connector-options).

* **Impacted Tests**: Tests that are known to run through the changed code and should be run to test it.

* **Test Gaps**: Shows the test gaps in your code base introduced with this issue ([see guide](../../../../tutorial/analyzing-issue-test-gaps/)).

* **Findings**: Static code analysis findings that were introduced, touched or removed during the implementation of this issue.

* **Commits** Display all commits targeting the current issue.
  Note that only commits which changed files known to Teamscale are considered.
