Skip to content

External Findings View

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.

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 Project Configuration 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. Enable Custom External Findings
  • 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 addition, the findings detail from the perspective indicate external findings and their description:

New Findings Group

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. The import will crawl the zip archive for files named custom-finding-groups.json containing finding group declarations as well as files named custom-finding-descriptions.json containing finding declarations. The format for custom-finding-descriptions.json looks as follows:

    "description": "Classes should have high coupling",
    "enablement": "YELLOW",
    "name": "Class with high coupling",
    "typeId": "class.dep.coupling"

The format for custom-finding-groups.json looks as follows:

    "groupName":"Class Dependencies",

Upon successful import, you will be directed back to the Project Perspective showing the imported findings.