# Scanning Builds

## Integrating the SeaLights Maven plugin into your pom.xml <a href="#integrating-the-sealights-maven-plugin-into-your-pom.xml" id="integrating-the-sealights-maven-plugin-into-your-pom.xml"></a>

You can use the SeaLights agent to update your maven pom.xml with the needed changes to run your Maven build using the Jenkins Maven Plugin

### Agent Files <a href="#agent-files" id="agent-files"></a>

There are two agent files

* Build Scanner - sl-build-scanner.jar
* Test Listener - sl-test-listener.jar

Download them from: <https://agents.sealights.co/sealights-java/sealights-java-latest.zip>

## Configuration file <a href="#configuration-file" id="configuration-file"></a>

### JSON configuration parameters reference <a href="#json-configuration-parameters-reference" id="json-configuration-parameters-reference"></a>

Create a JSON configuration file with the following parameters to provide the necessary configuration fields to the SeaLights Maven plugin:

1. **configuration** section with the following parameters
   1. **token** or **tokenFile** - set with a token or a file containing the token obtained from the SeaLights dashboard
   2. If you create a Build Session ID externally, provide the following fields:
      1. **buildSessionId** or **buildSessionIdFile** - Set with a build session id or a file containing the build session id created by the config step
      2. **createBuildSessionId** - Set to **false**
   3. If you want to create a Build Session ID using the SeaLights Maven plugin, provide the following fields:
      1. **createBuildSessionId** - Set to **true**
      2. **appName** - Name of the application as you want to see it on the SeaLights dashboard
      3. **branchName** - Name of the branch as you want to see it on the SeaLights dashboard
      4. **buildName** - Name of the build as you want to see it on the SeaLights dashboard
      5. **packagesIncluded** - Comma-separated list of packages to include in the scan. Note: This is defining a subset, so it must include the asterisk to include all sub-packages/classes
      6. **packagesExcluded** - (Optional) Comma-separated list of packages to include in the scan.  Note: This is defining a subset, so it must include the asterisk to include all sub-packages/classes
   4. If you want to create a Pull Request Build Session ID using the SeaLights Maven plugin, provide the following fields:
      1. **createPRBuildSessionId** - Set to **true**
      2. **appName** - Name of the application as you want to see it on the SeaLights dashboard
      3. **targetBranch** - The branch to which this PR will be merged (already reported to SeaLights)
      4. **pullRequestNumber** - The number assigned to the Pull Request from the source control
      5. **latestCommit** - The full SHA of the last commit made to the Pull Request
      6. **repositoryUrl** - The pull request URL for the PR to be scanned up until the section before the `pullRequestNumber` value
      7. **packagesIncluded** - Comma-separated list of packages to include in the scan. Note: This is defining a subset, so it must include the asterisk to include all sub-packages/classes
      8. **packagesExcluded** - (Optional) Comma-separated list of packages to include in the scan.  Note: This is defining a subset, so it must include the asterisk to include all sub-packages/classes
   5. **executionType** - Provide which executions need to be handled by the Maven plugin
      1. **full** - Execute both the build scanner and the test listener
      2. **testsonly** - Execute only the test listener
      3. **scanonly** - Execute only the build scanner
   6. **filesincluded** - (Optional) Set to the binary files to scan. Default: `*.class`
   7. **filesexcluded** - (Optional) Set to the binary files to exclude from the scan. Default:`*test-classes*`
   8. **workspacepath** - Set to with the path to the binary files to scan (Different per module). Default: `${project.build.outputDirectory}`\
      Note: there are rare cases that this needs to be changed. Make sure you really need to change it before doing so.
   9. **moduleNameArtifactId** - (Optional) Set to true to automatically set the module name for each sub-project to be based on `${project.artifactId}`. Default: false.
   10. **recursive** - (Optional) Set to true to scan all the subdirectories of the workspace path. Default: `true`
   11. **includeResources** - (Optional) Set to include the token and build session ID files in the built resources
   12. **includeTokenResource** - (Optional) On top of `includeResources` above, set to `false` to exclude the token file from the built resources. By default is `true`.
   13. **testStage** - (Optional) Set the name of the test stage as will be displayed on the SeaLights dashboard
   14. **labId** - (Optional) Unique ID for a set of test labs in case multiple labs are running simultaneously
   15. **filesStorage** - Set to the temp folder for the agent to create temporary files in. For example: `/tmp` or `C:\\Temp`
   16. **logEnabled** - Set to **true** if you want a log to be created
   17. **logLevel** - Set the log level to create. For example `INFO`
   18. **proxy** - (Optional) Address of proxy to run connection through
   19. **sealightsJvmParams** - Entry to provide JVM params to the SeaLights agent. It should be of the format `{"key1":"val1", "key2":"val2"}`
   20. **metadata** section with CI details
       1. **jobName** - Set to the name of the build job. For example: `${JOB_NAME}`
       2. **logsUrl** - Set to the link that the SeaLights dashboard should provide to view the build log. For example: `${BUILD_URL}/console`

{% hint style="warning" %}

* If you override the **surefire** `<argLine>...</argLine>` then you need to add the SeaLights parameters inside the override value. See [Surefire integration](https://sealights.atlassian.net/wiki/spaces/SUP/pages/100499481)
* **Do not** call the JSON file 'sealights.json' as the agent uses this file name for override options
* For troubleshooting purpose,  you can use `"buildName":"SL_Timestamp"` in your JSON file to have the Sealights Maven plugin generating automatically a time stamp (`yyyy.MM.dd-hh.mm` format) as a default build name.
  {% endhint %}

{% hint style="info" %}
See [#installing-test-listener-as-java-agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/java-agent/command-reference#installing-test-listener-as-java-agent "mention") for more parameter values and information.
{% endhint %}

**Sample of 'sealights' profile**

{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
  "executionType": "scanonly",
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${JOB_NAME}",
  "branchName": "${GIT_BRANCH}",
  "buildName": "${BUILD_NUMBER}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "off",
  "logFolder": "/tmp",
  "sealightsJvmParams": {}
}
```

{% endcode %}

### Frequently used parameters <a href="#frequently-used-parameters" id="frequently-used-parameters"></a>

#### Configuring SCM  <a href="#configuring-scm" id="configuring-scm"></a>

SeaLights, by default, provides all links to the SCM for Github.

You can configure SeaLights to prepare the links for Bitbucket and Gitlab as well with the following parameters placed under the `sealightsJvmParams` section:

* **sl.scm.provider** - set to **github, bitbucket** or **gitlab**
* **sl.scm.baseUrl** - When working with an on-premise installation of your SCM and access from the build machine is different than the one accessed by the users, then you can provide the base URL to use
* **sl.scm.version** - set to the version of the on-premise version you use

**Sample of SCM Parameters**

{% code overflow="wrap" lineNumbers="true" %}

```javascript
  "sealightsJvmParams": {
    "sl.scm.provider": "bitbucket",
    "sl.scm.baseUrl": "https://{dns}/projects/{project}/repos/{repo}/browse",
    "sl.scm.version": "4.9.0"
}
```

{% endcode %}

For more details and recommendations on how to set those 3 parameters, please refer to our dedicated page [incorrect-scm-links](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/general/incorrect-scm-links "mention").

#### Tagging <a href="#tagging" id="tagging"></a>

You can add tags to be viewed in the cockpit for the agents started by this maven job by passing them through the `sl.tags` property in the `sealightsJvmParams` field

{% code overflow="wrap" lineNumbers="true" %}

```
"sealightsJvmParams": {
    "sl.tags": "mytag",
}
```

{% endcode %}

#### Pre-downloading the agents <a href="#pre-downloading-the-agents" id="pre-downloading-the-agents"></a>

The Maven plugin downloads the recommended agent at the beginning of the run. If you want to pre-download them and provide them to the plugin, you can do so with the flags scannerJar & listenerJar.

{% code overflow="wrap" lineNumbers="true" %}

```
"scannerJar": "./sl-build-scanner.jar"
"listenerJar": "./sl-test-listener.jar"
```

{% endcode %}

{% hint style="warning" %}
The agents used here should be downloaded either with the latest agent or the recommended one as stated in [downloading-the-java-agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/downloading-the-java-agent "mention").
{% endhint %}

## Integrating into the pom.xml files <a href="#integrating-into-the-pom.xml-files" id="integrating-into-the-pom.xml-files"></a>

Before running your maven build, you run the build scanner with `-pom` flag to integrate the SeaLights Maven Plugin into the pom.xml files.

The parameters it receives are:

* **configfile** - The path to the JSON configuration you created with the parameters to be provided to the SeaLights Maven Plugin
* **pluginversion** - The version of the Maven SeaLights Plugin to insert into the pom.xml
* **workspacepath** - The base path to the location of the pom.xml files to update

**Sample Command**

{% code overflow="wrap" lineNumbers="true" %}

```
java -jar sl-build-scanner.jar -pom -configfile slmaven.json -workspacepath .
```

{% endcode %}

{% hint style="warning" %}
This step will update all the `pom.xml` files and back them up to `pom.xml.slback`\
You will need to restore them at the end of the run if you do not reset your workspace.
{% endhint %}

## Restoring the pom.xml file to its previous state <a href="#restoring-the-pom.xml-file-to-its-previous-state" id="restoring-the-pom.xml-file-to-its-previous-state"></a>

In case the pom file is to be restored to its previous state before the Sealights plugin was applied, use the build scanner with the -restore flag on the workspace where the pom.xml file is located:

{% code overflow="wrap" lineNumbers="true" %}

```
java -jar sl-build-scanner.jar -restorePom -workspacepath .
```

{% endcode %}

## Sample script  <a href="#sample-script" id="sample-script"></a>

{% hint style="info" %}
**Best Practice:** This script is very often added to a dedicated **pre-build step** in the CI job (i.e. Jenkins).
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```sh
echo "Downloading Sealights Agents..."
wget -nv https://agents.sealights.co/sealights-java/sealights-java-latest.zip
unzip -o sealights-java-latest.zip
echo "Sealights agent version used is:" `cat sealights-java-version.txt`

echo  '{ 
    "executionType": "scanonly", 
    "tokenFile": "./sltoken.txt", 
    "createBuildSessionId": true,
    "appName": "${JOB_NAME}",   
    "branchName": "${GIT_BRANCH}", 
    "buildName": "SL_Timestamp",  
    "packagesIncluded": "*com.example.*",   
    "packagesExcluded": "", 
    "filesIncluded": "*.class", 
    "filesExcluded": "*test-classes*", 
    "recursive": true, 
    "includeResources": true, 
    "proxy": null,
    "logEnabled": false, 
    "logDestination": "console", 
    "logLevel": "warn", 
    "logFolder": "/tmp/sl-logs", 
    "sealightsJvmParams": {
      "sl.scm.provider": "github"
    }, 
    "scannerJar": "./sl-build-scanner.jar",
    "listenerJar": "./sl-test-listener.jar",
    "filesStorage": "/tmp"
  }' > sl-mvn-build.json
 
echo "Updating POM with Sealights..."
java -jar sl-build-scanner.jar -pom -configfile sl-mvn-build.json -workspacepath .
```

{% endcode %}

**The next step** is to run your regular maven command, typically like '**mvn clean install**' or '**mvn clean verify**'.