---
url: /reference/ui/project/external-findings-descriptions.md
---
# *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.

![External Findings](./project-external-findings.png)

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](./project-create-external-finding-group.png)

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

![Add Findings Description Dialog](./project-create-external-finding-description.png)

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

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](../analysis-profiles/) in the Edit Analysis Profile View.

* Under **Language & Tool Enablement** → **Tools**, enable the checkbox **Custom External Findings** and click `Ok`.
  ![Enable Custom External Findings](./analysis-profile-custom-external-findings.png)
* 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.
  ![External Findings Dialog](./activate-external-findings-analysis-profile.png)

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](../../../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:

![New Findings Group](./sidebar-external-findings.png)

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

![New Findings Group](./findings-detail-external-findings.png)

## 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](./project-import-external-findings.png)

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:

```json
[
  {
    "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:

```json
[
  {
    "groupName":"Class Dependencies",
    "mapping":"class.dep.*"
  },
  ...
]
```

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