External Findings View

Teamscale internal analyses can produce findings in code. However, you can also upload findings from external tools into Teamscale. 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. Each singular issue is described in a finding description.

In the left sidebar, select Projects → External Findings. This leads to the External Findings 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 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.

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 external java findings group could be »java.*«. This will select finding descriptions which have »java.« as prefix. Click OK to save.

Create New External Finding Description

Finding descriptions are a detailed explanation of a problematic piece of code. 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

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

OFF	Finding will be hidden.
YELLOW	Finding indicates a warning.
RED	Finding 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 Language & Tool Enablement → Tools, enable the checkbox Custom External Findings and click Ok.
• The created external findings group will be shown under Disabled Analysis Groups under the name of the respective finding group. Click on the plus button next to the group to enable it and add it to a quality indicator. Click Save Analysis Profile to finalize.

If prompted with a dialog-box for reanalysis, click Expert Settings, select the Apply check enablements for future commits (Expert Option) checkbox and click Save.

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

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

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. 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",
    "mapping":"class.dep.*"
  },
  ...
]

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