# 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.
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).
# 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:
Furthermore, the user can choose a dashboard template.
A project can be configured with multiple connectors for
- Version Control Systems:
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:
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
Settings 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
# 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:
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.
# 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
Navigate to the Projects perspective
Click on the button for your target project
Upload Reportbutton in the top-right corner
In the dialog, you can configure the following options:
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:
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 Projects → Analysis 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:
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
# 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:
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:
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 Project → External 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:
Click the button
New metric description. This
provides the Create External Metric Description view:
# 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:
|Indicates a size metric describing the amount of source code in some manner, e.g.800 lines of code or 1000 source lines of code.|
|Indicates a ratio metric that only has values between 0 and 1. In the UI, these values are expressed as percentages.|
|Indicates that lower numeric values represent lower quality. The default case is that lower is considered better.|
|Means 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.|
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:
|A numeric metrics consists of a numeric value e.g., file size.|
|Indicates that a metric conveys time information e.g., last date modified. It's value is a number in milliseconds since 1.1.1970.|
|An 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
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:
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 Projects → External 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,
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
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
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:
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
Add finding description button
beside the group name. It launches the Add finding
# Add Finding 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
# Severity Configuration
|Finding will be hidden.|
|Finding indicates a warning.|
|Finding is critical.|
Two more steps are needed before uploading findings into Teamscale:
- Activating the external findings feature in the analysis profile, and then
- 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
- The created findings groups will be shown under Quality Indicators. Click
Save Profileto finalize.
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
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
In addition, the findings detail from the perspective indicate external findings and their description:
# Findings Details with New Finding 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:
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.