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 and Managing Issue Queries
Views	Issue Query View
Actions	Query Issues, Display Issue Trend, Save Issue Queries

Performing an Issue Query

In the Issues perspective, you can enter queries:

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 one. To limit a query to open issues, add the phrase closed=false.

Issue Query Language

Attributes	For each issue, the default attributes subject , id , assignee , author , created , updated , status , and closed are defined. Additionally, all custom fields defined in the connector configuration are made available as attributes. For connectors that support it, the `parent` field is filled with the ID of the parent issue.
Comparison operators	Attributes can be compared to values using the usual comparison operators =, !=, >, <, >=, <=. The order is always attribute, operator, value. You can not compare attributes to each other.
Set query	You can use the keyword in together with square brackets to create set queries. An example would be priority in [high, urgent]. You can use the keyword like_in / likeIn / ~in to match an element by substring instead of equality.
Logical operators	Comparisons can be connected using the logical operators && (and), || (or), and ! (not). Additionally, parentheses can be used to group subexpressions.
Like operator	The like operator ~ can be used to match a value against a regular expression.
membersOf	The special function membersOf can be used together with set queries to check for membership in a Teamscale group (that might again come from LDAP). An example would be assignee in membersOf('UI Team').
currentUser	The special function currentUser can be used to select issues where author or assignee is current Teamscale user. An example would be assignee = 'currentUser()' .
baseline	The special function baseline can be used to replace dates with a baseline. Note that the time of the baseline is ignored and is set to midnight i.e. just the date is used. An example would be updated > baseline('Release 1').
query	The built-in function query can be used to reference stored queries. For example query('Closed Issues') can be used in a query to reference a query named 'Closed Issues'.
Nested queries	You can pass a query to the set query operator in to check if a given attribute is contained in the queries result, for example, parent in query(author = currentUser()) would select all issues which have a parent issue that was created by the current user. Also stored queries can be referenced by specifying the name of the stored query instead of giving a query expression, for example, parent in query('TicketsCreatedByMe').
State queries	The operator inState allows to formulate that a issue has to be in a given state for a longer time. The operator can contain any subquery and is followed by a comparison (>, <, >=, <=) with a time value. An example would be inState(closed=false) > 7d to display all issues that are open for at least 7 days. The number can be followed by suffixes for days (d), hours (h), minutes (m) and seconds (s). The default when no suffix is given is days. Dates can also be used, for example: inState(closed=false) > 2018-1-12 returns all issues, which have been closed after 2018-1-12. This is especially useful if you want to create a static query, e.g., all closed issues in January. Additionally, the special value `@startOfMonth` can be used to get the duration of time elapsed since the start of the current month, e.g., inState(closed=false) < @startOfMonth to display all issues closed since the start of the current month.
Parent queries	The operator hasParent allows to select issues based on the attributes of their parent issue. It selects issues that have a parent and whose parent matches a given sub query. An example would be hasParent(closed = true) to display all tickets whose parent issue has been closed. Issues that have no parent or whose parent was not imported into Teamscale are never returned by a hasParent query.

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

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 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.

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.