---
url: /reference/ui/project/external-metric-descriptions.md
---
# *External Metrics* View

Situations may arise in which you want to observe a quality property of code and Teamscale does not provide such a 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 Configuration** → **External Metric Descriptions** in the left navigation sidebar.
This leads you to the **External Metric Descriptions** view.

## 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](./projects-external-metrics.png)

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

![Creating External Metric](./projects-external-metric-create.png)

## 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:

:::tip 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:

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](../analysis-profiles/), 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](../../../../howto/creating-a-project/).

Finally, metrics need to be uploaded for files via the [REST interface](../../../rest-api/#available-rest-services) (endpoint: `/api/vTEAMSCALE_VERSION/projects/{project}/external-analysis/session/{sessionId}/external-metrics`).

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

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.

## Export External Metric Descriptions

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