---
url: /tutorial/setting-up-requirements-tracing.md
---
# Setting up Requirements Tracing Analysis

As a person responsible for making sure that safety-critical requirements are correctly implemented and tested in your software system, you may want to use the [Requirements Tracing](../../glossary/#requirements-tracing) features of Teamscale to support you.
This tutorial leads you through the setup of major requirement tracing features available in Teamscale and consists of the following parts:

\[\[toc]]

## Step 1: Preparing the source code for analysis

Clone the GitHub repository [The Algorithms - C][algorithms].
This is an open source implementation of common computer science algorithms in the C language.
We will use it as an example of a safety-critical system under development.
Navigate to `data_structures/stack/stack.c` file of the repository and add a couple of source code comments that reference [spec items](../../glossary/#specification-item), as shown in the image below.
Let us assume that all the spec items in your requirements management tool are named with the prefix `DP-` followed by a number, for example `DP-123`.
Adding the references to source code comments allows Teamscale to establish links between the code entities (methods, classes, etc.) and the corresponding items imported from the requirements management tool.

![Add spec item references to source code](./references-in-code.png)

Commit your changes.

## Step 2: Setting up a Teamscale project with a Requirements Management Tool connector

As a prerequisite for this step, create a free test account in the [public Polarion instance][polarion].
We will use the [System Requirement Specification][spec] of the [drivepilot][drivepilot] project as an example of a requirements specification for a safety-critical software system under development.

In Teamscale, go to *Project Configuration* and click *New project*.

Name the new project `Requirements Tracing Test` and choose the analysis profile *C++ (default)* for the default code scope.

![Create the project](./project-creation.png)

In the *Connector Configuration* section, click `+` and choose *Source Code Repository* > *Git*. Create a new account named `Git` and point it to your local copy of the repository that we have modified in Step 1.
Leave the rest of the options unchanged.

![Create Git credentials](./git-credentials.png)

In the *Connector Configuration* section, click `+` and choose *Requirements Management Tool* > *Polarion*.
After that, point the Teamscale connector to the Polarion account you have created using the `https://almdemo.polarion.com/` URL and your username and password.

![Create Polarion credentials](./polarion-credentials.png)

Configure the connector as shown in the image below.

![Configure Polarion connector](./polarion-connector.png)

Note that we need to provide Teamscale with a way to identify the work items that belong to the Teamscale project.
This is done via the *Specification item ID pattern* option, which we set to the regular expression `(DP-\d+)`.
Teamscale uses the text matched by the capturing group as the spec item ID, so the group has to enclose the complete ID including the `DP-` prefix.
This is the reason why we have provided the source code comments referencing IDs of the shape `DP-123` - the example [drivepilot][drivepilot] project in the [Polarion][polarion] instance uses this naming scheme for the work items.

Click `Create project`.

## Step 3: Getting to know the Requirements Tracing Perspective

Navigate to the *Requirements Tracing* Perspective in Teamscale and view the spec items.

![View the imported spec items](./spec-item-list.png)

The code reference matrix in the next tab tells you exactly which spec item is referenced by which method/class in the source code.

![Code reference matrix](./code-reference-matrix.png)

## Step 4: Using spec item metrics in Dashboards

Create and save a spec item query.
In the image below, the query is `status=Open`, which means it selects all the spec items in status `Open`.

![Query for open spec items](./open-spec-items.png)

Navigate to the *Dashboards* perspective and create a metric widget, such as the numeric metric widget in the example below.
Select `requirements-tracing-test/-spec-items-/requirements/open` as *Path* and *Spec Items* as *Metric* in the widget configuration.
The example widget shows the count of requirement items in the state `Open`.

![Use a spec item metric in a dashboard widget](./spec-item-widget.png)

## Step 5: Linking the references in source code to the spec items from your requirements management tool

Navigate to the *Metrics/Files* View of Teamscale and then to the `data_structures/stack/stack.c` file.
View how the spec item references you have provided in the source code in Step 1 have been linked to the spec items from your requirements management tool.

![See links in code and items from the tracker in one place](./links-to-items.png)

[algorithms]: https://github.com/TheAlgorithms/C

[polarion]: https://almdemo.polarion.com/polarion

[drivepilot]: https://almdemo.polarion.com/polarion/#/project/drivepilot?shortcut=favorites%2FHome

[spec]: https://almdemo.polarion.com/polarion/#/project/drivepilot/wiki/Requirements/System%20Requirement%20Specification