# Projects Perspective

The Teamscale project perspective enables users to manage projects, analysis profiles, metric threshold configurations, external metrics and external external findings. This section describes the user interfaces for creating and managing each of these entities.

# Overview

The Projects perspective features a sidebar that can be used to navigate to e.g., these configuration pages:

  • Projects: This page allows you to add projects to Teamscale that should be analyzed.

  • Analysis Profiles: This page allows you to configure the analyses that are run for your projects.

  • Metric Thresholds: This page allows you to define a target threshold for all metrics that your projects should abide by.

Projects in Teamscale are linked to one or more source code repositories and the findings that Teamscale generates and collects for the corresponding source code artifacts.

# Projects Page

After the project is set up, it appears in the project list. For each existing project, the project list offers different buttons for project management (see table below).

Project List

# Editing an Existing Project

On the Projects page, you can see a list of all projects configured in Teamscale. The following actions can be performed on an existing project.

Opens the edit dialog for the project. The dialog is the same as for project creation except that the project's id cannot be changed.
Opens a dialog for advanced configuration options such as a connection to SAP systems and the threshold configuration to use for the project. Teamscale defines a default threshold configuration but users can create custom threshold configurations (also discussed in this section).
Triggers a complete re-analysis of the project.
Pauses analysis of the project.
Deletes the project.
Copies the project. The copy project page will allow to specify whether only the configuration or also all project data should be copied.
Exports the project configuration. The exported file can be imported with the "Import project" button.
Exports a complete backup of the project (including analysis results). The exported file can be imported with the "Import project" button.
Opens a view for management of external uploads.
Opens a view for providing access to the project via users or groups.

# Action: Creating a New Project

To create a new project, the Add Project button of the Projects page can be used. You need to set a project name and an analysis profile. Here, we chose the ABAP (default) profile as an example:

New Project

Furthermore, the user can choose a dashboard template.

A project can be configured with multiple connectors for

  • Version Control Systems:

Repositories

Connecting to Git Platforms (GitHub, GitLab, BitBucket)

While all these platforms can be accessed using the plain Git connector, using a more specific connector enables additional features, such as automatic update on push, and annotation of pull requests.

  • Issue Trackers:

Issue Trackers

In terms of version control systems, Teamscale offers connectors to Git, SVN and Azure DevOps TFVC (TFS), as well as the Git management platforms GitHub, GitLab and BitBucket.

In addition, it can also read from the file system, either with a simple File System or a Multi-Version File System connector. For these file-system connectors, access to the file system needs to be made available by a Teamscale administrator via AdminSettings using the File-System-Access Whitelist option.

# Git Connector

To set up a Git connector, the user has to specify account data (the + button opens an account setting dialog), and a repository identifier (must be unique in the project). Furthermore, the user can specify a start revision to reduce the analysis load and include or exclude files. You might, for example, want to exclude generated code or experimental code from the analysis. Also, you might want to have separate projects for your application and your test code. Note that Teamscale should be connected to either a remote repository (Teamscale will clone it locally into the working directory configured in the Server Settings page on the Admin perspective) or a dedicated local clone that is not modified by other tools or users.

Local Git Repository

When connecting a local repository (file:// URL schema), make sure that the corresponding repository is bare, i. e. has been cloned with the --bare option.

# Branch Support

Teamscale also offers branch support. As default, branch support is not enabled while configuring the connector for a project. For large projects with hundreds of branches, this would dramatically increase the analysis time. You can manually enable branch support by clicking the corresponding checkbox and configure which branches should be included in the anlaysis by using include/exclude patterns. The patterns are reg-ex based. For example, you can match your release-branches or specific feature branches. Internally, Teamscale has a default branch, which maps to »trunk« for SVN and »master« for Git. Sometimes, this has to be adjusted, however.

# Multiple Repository Connectors

You can also use multiple repository connectors for one project. For example, you can read both from Git and SVN or from Git and the file system or from multiple GIT repositories. If you have two connectors read the same files and/or commits, Teamscale will merge these inputs into a unified view. In the Metrics perspective and the subsequent views, each file will only appear once. In the history of a file (Code Detail View) and in the Activity View, each commit for each repository will be shown separately. If there are multiple commits with the same timestamp but with different content (different changes), Teamscale will decide which of them to display as the »latest« commit. This choice also affects computation of metrics in the dashboard as the metric values might differ depending on the order of the commits (e.g., added lines of code). A situation where such overlapping commits are loaded can easily be generated by using multiple multi-version file-system connectors.

# Branch Support For Multiple Repository Connectors

If you use multiple repository connectors and have branch support enabled, Teamscale will assume that branches with the same name can be mapped onto each other. Hence, Teamscale will only show one branch with the data from all connectors. However, if the branching structure is not consistent between connectors, this will not work, e.g., if you have a SVN connector followed by a Git connector. For this case, Teamscale provides expert options in the connector configurations. The option Branch transformation allows you to provide a manual mapping between branches. In our example, you would indicate »trunk → master«, for example.

# Multi-Version File-System Connector

A multi-version file-system connector reads multiple versions of a repository that are stored in separate directories. The connector expects an input directory that contains one subdirectory per repository version. The names of the subdirectories must be numeric and are interpreted as Java timestamps.

An example of this directory layout looks like this:

Multi Version File System Layout

The multi-version file-system connector expects that each subdirectory contains a full snapshot of the repository at the given timestamp. Each subdirectory is represented by a commit in Teamscale. If a file is missing in a subdirectory, it is treated as if it was deleted.

Please see also the detailed documentation on options for code repository or issue tracker connectors.

# Action: Managing external uploads.

To list existing external-analysis uploads click on the button. The list linked in this button shows all reports that were uploaded to Teamscale. The list is ordered by the target partitions of the uploads (typically, uploads of each external tool such as Jacoco and FindBugs are stored on separate configurable Teamscale partitions). Each upload partition and each upload commit have buttons. You can also use the button of a partition to delete all uploads of the partition and the button of a upload to delete only the specific upload.

When a given upload is deleted, Teamscale starts a rollback to the latest commit before the upload in question and re-analyzes every following commit except for the deleted upload. Depending on the number and size of commits between the deleted upload and the newest commit, this partial re-analysis can take a significant amount of time.

# Manual report upload

Assuming you already set up a regular Teamscale project and you have a supported coverage report available, a manual upload can be performed as follows:

  • Navigate to the Projects perspective

  • Click on the button for your target project

  • Click the Upload Report button in the top-right corner

  • In the dialog, you can configure the following options:

    Image: projects-upload-report-dialog

    • The coverage file to upload

    • Format: The coverage format of a supported test profiler

    • Code Date: This field must be filled with the date of the checkin in your VCS that corresponds to the version of your application for which the external report was created. e.g., for finding reports this would be the date of the VCS checkin for which the checker tool was run. For coverage reports this would be the date of the VCS checkin that was built and deployed to the test system. This allows Teamscale to link the correct state of the code with the uploaded report. The time can be set as a calendar date, baseline or revision.

    • Branch: The repository branch from which the coverage was created.

    • Partition: Reflects the report source. It is a label that allows to differentiate between several sources, e.g., manual tests and unit tests.

    • Message: A message that will be shown in the UI, which can be used to identify the upload, e.g. "Unit Test Coverage".

After you specified the options above and clicked Upload Report, Teamscale will process the coverage report.

# Verifying that an upload commit was successful

To verify that your upload was successful, you can navigate to the Activity perspective and check whether you can see an upload commit similar to this one:

External Upload Commit

Note: Be sure to (1.) select the correct project and branch, (2.) navigate to the timestamp you selected for the upload, and (3.) deselect the Hide external uploads commit checkbox in the sidebar, as your commit will not be visible otherwise.

If the coverage information and code known to Teamscale could be matched correctly, the details of the upload commit will show files covered by the upload as "changed". If no files are affected, this can e.g., indicate that the code paths in the coverage report are not equal to the paths in Teamscale.

# Action: Managing Analysis Profiles

In addition to configuring projects, the project perspective enables users to configure analysis profiles that can be used in different projects. An analysis profile configures the programming languages that will be analyzed, external tools which can be included in the analysis results, and which metrics are computed and displayed. Teamscale already offers many analysis profiles which are usually tailored to specific programming languages (e.g., [ABAP (default)] or [Java (default)]) but users can create and manage their own ones.

By clicking on ProjectsAnalysis Profiles in the left sidebar, the Analysis Profile Page will be shown. The page shows all existing default profiles as well as individually created ones:

Analysis Profile Page

For each profile, the list offers different buttons for management (see below). In addition, all projects using a profile are stated in a separate column.

Opens the edit dialog for the analysis profile. The dialog is the same as for analysis profile creation except that the profile name can not be changed.
Allows to copy the analysis profile (configurable).
Deletes the analysis profile.
Exports the profile as a file. Exported profiles can be imported with the Import analysis profile button above the analysis profile list.

# Action: Editing an Analysis Profile

A detail guide on how to create or edit an analysis can be found here.

# Action: Managing Threshold Configurations

A threshold configuration specifies threshold values for metric. It influences how metric values are displayed, for example, in the dashboard. A threshold configuration is identified by its name and consists of thresholds structured in groups. Threshold configurations are project-independent. The Thresholds page gives an overview of all existing threshold configurations:

Thresholds Page

These actions are available for a threshold profile:

Opens the edit dialog for the threshold configuration. The dialog is the same as the creation dialog except that the threshold configuration name can not be changed.
Copies the threshold configuration
Deletes the threshold configuration
Exports the threshold configuration. The exported file can be imported with the “Import Thresholds” button
Exports the documentation of the profile
Lets you configure access rights for this profile

# Action: Creating a Threshold Configuration

To create a new threshold configuration, you have to select Thresholds in the projects perspective sidebar. This will lead you to the Thresholds page which offers the Create new Thresholds button. This opens the Create Threshold Profile View:

Threshold Profile View

In this view, you have to choose a name for the threshold configuration and add metric groups to the threshold configuration. Next, you can add metrics to the metric groups. Each metric is shown in one line. The arrow next to the metric name explains in what direction the metric is assessed. If the arrow points down, low values indicate good values and vice versa.

The field Custom Name allows you to use another name than the metric's name when displaying the metric, for example, in the dashboard. Unless two rows with the same metric exist, the custom name is optional and the metric's name will be displayed in case the custom name is not specified.

The fields Yellow and Red enable you to specify thresholds. Depending on the metric, the fields can be either filled with an arbitrary numeric value or a percentage value (as number between 0 and 1). It is also possible to specify only one of the thresholds or none (in which case no thresholds will be displayed). Note that some metrics are not supposed to be assessed (such as »Lines of Code«); it is not possible to specify thresholds for those.

The field Sub Path allows restricting the assessment and validity of the thresholds to a certain part of a project. The sub path can be used to assess different parts of a project differently (e.g., restrict the threshold to the production code by excluding test code). It is also possible to use a path that points to an architecture component.

# Action: Creating an External Metric

Situations may arise in which you want to observe a quality property of code and Teamscale does not provide such metric. For instance, observing code defect density (i.e. the number of code defects per specific number of lines of code) or frequency of bug-fixes on a file level. You can do this by first creating an external metric. Once created, it needs to be activated in the analysis profile that is used by the current project before it becomes visible in the Metrics and Delta perspectives, and also in the metrics-related dashboard widgets. To create an external metric, select ProjectExternal Metric Descriptions in the left navigation sidebar. This leads you to the External Metric Descriptions page.

# External Metrics Descriptions Page

On this page, you will find a table of external metric descriptions if they have been configured already. This image shows the two external metrics described in the previous paragraph:

External Metric

Click the button New metric description. This provides the Create External Metric Description view:

Creating External Metric

# Create External Metric Page

In this view, you have to enter a unique external metric id (that Teamscale uses internally to identify metrics), an analysis group name (collects similar metrics under a common group in analysis profile configuration), a UI name (some friendly name to be displayed on the user interface) and a description of the metric. The field aggregation indicates how values of this metric will be aggregated for directories, e.g., by selecting the minimum value or the maximum value or using the sum operator as aggregation.

You can select one or more metric properties under Select Metrics Properties . They are explained here:

SIZE_METRICIndicates a size metric describing the amount of source code in some manner, e.g.800 lines of code or 1000 source lines of code.
RATIO_METRICIndicates a ratio metric that only has values between 0 and 1. In the UI, these values are expressed as percentages.
LOW_IS_BADIndicates that lower numeric values represent lower quality. The default case is that lower is considered better.
QUALITY_NEUTRALMeans that values of a metric are not assessed to have negative or positive impact on quality. This value contradicts with LOW_IS_BAD and you should select only one or the other.

Sample

For example, the code defect density metric described previously is a SIZE_METRIC and qualifies as RATIO_METRIC if expressed per 100 lines of code.

The field value type tells the kind of value for a metric. Possible values are:

NUMERICA numeric metrics consists of a numeric value e.g., file size.
TIMESTAMPIndicates that a metric conveys time information e.g., last date modified. It's value is a number in milliseconds since 1.1.1970.
ASSESSMENTAn assessment metric stores an assessment with red, yellow and green.

On the External Metric Descriptions page, in the table of existing metrics under Actions , you can edit a metric by clicking the edit button . This leads to the Edit External Metric View. Also, you can use the delete button to delete a metric.

All external metrics once created require three additional steps before they are accessible in Teamscale. The first step is activating them in the analysis profile of the project. You can do this by editing the analysis profile, making changes only in the Select Analysis Tools section of the profile. There, you can select the checkbox besides Custom External Metrics . After clicking Continue underneath, a new quality indicator named Custom Metrics is visible in the Configure Quality Indicator section of the profile, organizing the new metrics under the specified analysis groups and providing more options for configuration.

In the second step, perform a re-analysis of the Teamscale project in the Projects view as explained here.

Finally, metrics-related data need then be uploaded for files through the Teamscale Python API.

# Action: Import External Metric Descriptions

External metric descriptions can be imported into Teamscale. On the External Metric Descriptions page of the Project Perspective, you can click the Import metric descriptions button at the top of the page. This leads to the import view:

External Metric Import

Browse to select a zip archive containing metric descriptions and click Upload. Upon successful import, you will be directed back to the Project Perspective showing the imported metric descriptions.

# Action: Export External Metric Descriptions

At the top of the External Metric Descriptions page, you can click the Export metric descriptions button to download as a zip archive, the stored external metric descriptions.

# Action: Create New External Finding Group

Teamscale internal analyses can produce findings in code. However, you can also upload findings from external tools into Teamscale. Take for instance an architecture-related issue of dependencies. One concern that could be analyzed for is high coupling, i.e. many dependencies between classes in different packages or components. The starting point to get external findings into Teamscale is creating external finding groups and finding descriptions. A finding group describes various related concerns in code, in the example architecture dependencies. Each singular issue is described in a finding description.

In the left sidebar, select ProjectsExternal Finding Descriptions . This leads to the External Finding Descriptions page.

# External Finding Descriptions Page

On this page is presented a list of existing finding groups or an empty list if none has been created. At the top is the button New finding group.

When there are finding groups, each one is shown with a collapsible orange arrow icon on the left, its name,
buttons Add finding description, to modify and to delete the finding group. In addition, underneath these buttons are a mapping string for the group and a table of matching finding descriptions. The mapping string is a regular expression that collects matching finding descriptions (i.e. descriptions whose type identifications are matched by the regular expression) into the table.

External Findings

The image shows the finding group described in the previous paragraph. Finding descriptions that cannot be matched into available groups are listed under the Unmatched group.

To create a new finding group, you have to click the New finding group button. This launches the Add Finding Group dialog.

# Add Finding Group Dialog

External Finding Group Dialog

You can type in a name for a findings group and also enter a regular expression for the mapping. This mapping is used to find matching finding descriptions to be associated with this group. A sample regular expression for the class dependency finding group could be »class.dep.*«. This will select finding descriptions which have »class.dep« as prefix. Click OK to save.

# Action: Create New External Finding Description

Finding descriptions are a detailed explanation of a problematic piece of code. Take, for instance, the finding group for class dependencies:

Overview Table of External Findings

The description »Low Cohesion« describes a situation where few dependencies exist between classes in the same component or package.

To create a finding description associated with a group, you have to click the Add finding description button beside the group name. It launches the Add finding description dialog.

# Add Finding Description Dialog

Add Findings Description Dialog

The dialog provides four fields:

  • The Type Id should have a unique value and match the regular expression of an existing finding group to which it will be associated. This value will be used internally by Teamscale and cannot be modified later.
  • the UI friendly Name is a short name for identifying this description in analysis profile configurations.
  • The Description field should provide some detailed description as it will explain occurrences of findings in the Finding Detail View .
  • the Severity sets the level of treatment this finding deserves and how it should be handled. Possible values shown in the table below. Click OK to save.

# Severity Configuration

OFFFinding will be hidden.
YELLOWFinding indicates a warning.
REDFinding is critical.

Two more steps are needed before uploading findings into Teamscale:

  1. Activating the external findings feature in the analysis profile, and then
  2. re-analyzing the project in the Projects perspective.

In order to activate the findings group in the analysis profile, you need to edit the analysis profile in the Edit Analysis Profile View.

  • Under Select Analysis Tools, enable the checkbox Custom External Findings and click Continue.
  • The created findings groups will be shown under Quality Indicators. Click Save Profile to finalize.

External Findings Dialog

If prompted with a dialog-box for reanalysis, click Expert Settings and select the Only schema update (expert option) checkbox. Also select the Re-analyze checkbox and click OK.

After re-analyzing the project, findings can be uploaded using Teamscale's Python API. The new findings are processed and visible in the Findings Perspective. On its sidebar the new class dependencies finding group is displayed with other groups for filtering findings, as shown here:

# New findings Group in Sidebar of Findings Perspective

New Findings Group

In addition, the findings detail from the perspective indicate external findings and their description:

# Findings Details with New Finding Group

New Findings Group

# Action: Import External Finding Descriptions

It is possible to import external finding descriptions bundled in a zip archive into Teamscale. On the External Finding Descriptions page of the Project Perspective, you can click the Import finding descriptions button at the top of the page. This leads to the import view as shown here:

Importing External Finding Descriptions

Browse to select the zip archive and click the Upload button. Upon successful import, you will be directed back to the Project Perspective showing the imported findings.