# How to Upload External Analysis Results to Teamscale

It is possible to upload external analysis results to Teamscale, either via the REST API or via repository connectors. External analysis results include test coverage reports, test execution results, custom findings, custom metrics and more.

Upload via REST API
Import via Artifactory

# Upload via REST API

The REST service external-analysis/session/<SESSION_ID>/report allows uploading results from analysis tools like FindBugs/SpotBugs or different coverage tools.

# Request Description

In order to upload a file to Teamscale, the server which is running the Teamscale instance must be accessible via HTTP(S).

As a first step, create a new user which will be able to upload external analysis results to Teamscale. You can either use your administration account for this, or better use a special user with the Build role.

To upload external analysis results as files to Teamscale, issue the following HTTP request:

HTTP method: POST
Request URL:
```
http://<YOUR_TEAMSCALE_SERVER>:<PORT>/api/projects/<TEAMSCALE_PROJECT_ID>/external-analysis/session/<SESSION_ID>/report?format=<FORMAT>&partition=<PARTITION>&message=<MESSAGE>
```
- YOUR_TEAMSCALE_SERVER:PORT is the address and port of the Teamscale instance.
- TEAMSCALE_PROJECT_ID is the ID of the Teamscale project into which to store the coverage.
- SESSION_ID is the ID of the session you want to upload to. Use auto-create to specify you would like to perform the upload in one step.
- FORMAT is the report format of the uploaded file. It must be one of the formats supported by Teamscale.
- PARTITION is a logical name for the type of coverage. All coverage with the same partition will be grouped together. This, e.g., allows you to upload both coverage for your Java and your JavaScript tests without the results of one overriding those of the other. The name is descriptive and can be any arbitrary string.
- MESSAGE is the message shown in the Activity perspective to the user. It should make clear that coverage was uploaded.
Body: Form data. May contain any number of elements with name "report" and the content of a single result XML file.
Authentication: HTTP Basic Authentication with the build or admin user and their Access Token (not their password!)

# Sample Upload with Curl

curl --request POST --user bob:e434mikm35d --form "report=@coverage.xml" "http://teamscale-server:8080/api/projects/myProject/external-analysis/session/auto-create/report?format=JACOCO&partition=Unit%20Tests&message=Unit%20Test%20Coverage"

Always Quote the URL

Please note that the URL must be enclosed in quotes. This is required as most shells treat the & character specially and would thus truncate the URL. If you are not sure you quoted the URL correctly, you can use curl -v to get verbose output from curl, including the actual URL it tries to contact.

Request Parameters

Details about the service's parameters can be best retrieved via the online service documentation as described here.

In addition to the common pitfalls when dealing with the REST API, you need to check if the external tool is activated in the project's analysis profile.

Furthermore, please refer to the details for supported upload formats.

# Uploading data for historic dates or revisions

Note that the uploaded results will be used for the current HEAD commit in Teamscale on the main branch (e.g., latest commit on master for Git, latest changeset on the TFS main branch or latest commit on trunk for SVN). Should this not be the behaviour you want, you can override this by adding the following to the request's URL:

&revision=<REVISION>

where REVISION is, depending on your version control system, a:

full Git SHA hash, or
SVN revision number, or
TFS changeset ID

Regardless of whether the revision has already been analyzed or not, Teamscale will store the external analysis results for the code with the revision. When later it is analyzed, the upload is integrated with the revision into Teamscale.

If concerned project has a multi-connector setup, the VCS repository that contains the revision for which an upload is meant, can be specified in the request's URL using the repository identifier (see connector options) for the project connector:

&repository=<REPOSITORY_IDENTIFIER>

Teamscale also supports uploading external analysis results to timestamps. This can be achieved by adding the following to the request's URL:

&t=<TIMESTAMP>

# Uploading Multiple Reports At Once (Sessions)

If you want to upload multiple reports in a single logical commit, you should use Teamscale's session concept. For session handling, the service external-analysis/session is used. The following example uploads two different reports as a single commit using curl. For more details, see the service documentation.

curl --request POST --user bob:e434mikm35d http://localhost:8080/api/projects/my-project-id/external-analysis/session?message=myMessage&partition=myPartition

This command will return the session ID, in this case Sdfb38cb0-c348-40fb-82f0-144bf0e41beb. Using this session, we can upload multiple reports.

curl --request POST --user bob:e434mikm35d --form "report=@./MyReport.xml" http://localhost:8080/api/projects/myProject/external-analysis/session/Sdfb38cb0-c348-40fb-82f0-144bf0e41beb/report?format=FINDBUGS

curl --request POST --user bob:e434mikm35d --form "report=@./OtherReport.xml" http://localhost:8080/api/projects/myProject/external-analysis/session/Sdfb38cb0-c348-40fb-82f0-144bf0e41beb/report?format=FXCOP

Finally, we commit the session using a POST request:

curl --request POST --user bob:e434mikm35d http://localhost:8080/api/projects/my-project-id/external-analysis/session/Sdfb38cb0-c348-40fb-82f0-144bf0e41beb

# Import via Artifactory

External analysis results can be directly imported to Teamscale via the Artifactory repository connector. The Artifactory connector will extract the results from the repository, process the reports and store them in the configured partition.

# Prerequisites

Before importing external analysis results to Teamscale via Artifactory, please ensure the following:

All relevant external results reports are available in Artifactory.
The external results reports are packed in archives (i.e. ZIP files).
The path of the external results reports in Artifactory includes the timestamps at which they should be uploaded.

# Configuration Steps

To import external results reports to a project:

Add an Artifactory connector to the project.
Configure the Artifactory connector options so that Teamscale can extract the reports from Artifactory.
Configure the following options so that Teamscale can process the reports:
- Analysis report mapping: Ant pattern used to map the reports inside the ZIP archives to their corresponding report format. Example: **/junit.xml -> JUNIT, **/jacoco.xml -> JACOCO
- Partition Pattern: Regular expression used to extract the partition from the path of the artifacts. The first non-null group is used as partition, e.g. /coverage/([^/]+)/ would use the sub-folders of coverage as the partition names.
Save the project.

# Configuration Example

Below is the structure of the Artifactory containing the external results reports.

lcov.zip contains the LCOV coverage report (lcov.info).
misra.zip contains the external findings report for MISRA warnings (warnings.json).

- MyRepository
|
| -> ExternalReports
  |
  | -> Branches
    |
    | -> master
      |
      | -> coverage
        |
        | -> 20200110-110037
          |
          | -> lcov.zip
        |
        | -> 20200110-111535
          |
          | -> lcov.zip
      |
      | -> findings
        |
        | -> 20200110-110037
          |
          | -> misra.zip

Accordingly, the Artifactory connector's configuration would look as follows:

Screenshot of the Artifactory connector's configuration to upload external rsults

And this would be the end result and how the uploaded results via Artifactory would appear in Teamscale:

Screenshot of the uploaded external results via Artifactory

← Setting Up External Tools & Formats Setting up Coverage Profiling for Java →