tool-configuration.md.vm

# Tool Configuration

${docNameCap} can be used as plugin for different build systems. 
Currently, the configuration is almost the same for all three types (maven, gradle, cli).
It is based on the structure of a Maven pom configuration.
In what follows, the configuration is described and some hints are given if special means have to be taken into account for certain build systems.

Below you can find an example for a possible configuration. If you are using the [Maven Plugin](${docName}-maven-plugin/index.html), this is part of your pom and you have to provide the maven coordinates of the plugin inside the `<plugin>...</plugin>` tags.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<plugin>

    <configuration>
        <!-- MANDATORY properties -->

        <!-- properties for Attribution Document -->
        <productName>Modeler</productName>
        <productFullname>Visual Rules - Modeler</productFullname>
        <version>6.3.0</version>

        <!-- OPTIONAL properties -->

        <!-- path to your workflow definition file (only optional if the workflow steps are configured directly in this file) -->
        <workflowDefinitionFile>${basedir}/workflow.xml</workflowDefinitionFile>

        <!-- properties for attaching Artifacts-->
        <attachAll>true</attachAll>
        <filesToAttach>
            <param>sources-zip,zip,OSS-sources</param>
        </filesToAttach>
        <isMavenInstalled>false</isMavenInstalled>
        <sourcesRepositoryUrl>...</sourcesRepositoryUrl>

        <!-- path(s) to your config.xml(s)-->
        <configFiles>
            <param> ${basedir}/config.xml </param>
            <param> ${basedir}/config2.xml </param>
        </configFiles>

        <!-- properties for proxy configuration-->
        <proxyHost>${proxyHost}</proxyHost>
        <proxyPort>${proxyPort}</proxyPort>

    </configuration>
</plugin>
```

#[[###]]# Explanation of parameters

All parameters are required unless specified as optional.


* `productName`: *(deprecated)* Name of the product (e.g. Modeler).
* `productFullname`: Full name of the product (e.g. Visual Rules - Modeler)
* `version`: Version of the product
* `workflowDefinitionFile`: *optional, if embedded inside tool configuration* The path to your workflow definition file, which defines the steps
 contained in your ${docNameCap} workflow.
* `configFiles`: *(optional)* Path to your configuration file(s).
* `configFileUris`: *(optional)* URIs to your config file.
* `licenseValidation`: *(optional)* In this section a license can be defined as
forbidden and parameter for the license Validation can be set.
* `copyrightHoldersName`: *(optional)* The name of the copyright holder
* `copyrightNotice`: *(optional)* Annotation to the copyright
* `proxyHost`: *(optional)* Parameter to provide a proxy configuration
* `proxyPort`: *(optional)* Port to the provided proxy server
* `isMavenInstalled`: *(optional - default: false)* If set to true, tells ${docNameCap} that Maven is installed on this machine.
This allows certain workflow-steps to run or retrieve more information.
For Gradle and CLI in addition the `M2_HOME` variable needs to be set to the Maven executable.
Defaults is false for Gradle and CLI.
For Maven it the variable is ignored.
* `${docName}TargetDirectory`: *(optional)* The folder where the documents created by ${docNameCap} are stored.
Defaults to a folder called ${docNameCap} inside the build folder of the project.
* `sourcesRepositoryUrl`: *(deprecated)* This option once allowed to set another remote repository address
However, in the current version it does not do anything and will be removed soon.

**Parameters related to attaching artifacts**

* `attachAll`: *(optional)* Attaches all files created by the plugin to
the current build. Defaults to `false`. The default properties are:

| File                | Identifier       | Type | Classifier           |
|---------------------|------------------|------|----------------------|
|sources.zip          |sources-zip       |zip   |${docName}-sources-zip      |
|${docNameCap}_3rdPartyAnalysisReport.txt    |${docName}-report |txt   |${docName}-processing-report|
|attribution document  |attribution-doc    |pdf   |${docName}-attribution-doc   |
|${docNameCap}_artifactsInformation.csv|artifact-information|csv |${docName}-artifact-info    |
|ClmReportData.json   |clm-report        |json  |${docName}-clm-report       |
|clm-report.pdf       |clm-report-pdf    |pdf   |clm-report-pdf        |

* `filesToAttach`: *(optional)* If you want to attach single files or
to overwrite default values, use this parameter (identifier from table):

```xml
<filesToAttach>
 <!--<param>identifier,type,classifier</param-->
     <param>sources-zip,zip,OSS-sources</param>
</filesToAttach>
```

#[[###]]# Definition of the Workflow inside the tool configuration

Inside the plugin definition, you can also add a fully fledged workflow definition.
As an example consider the following plugin definition for ${docNameCap}:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
    <configuration>
        <productName>${docNameCap} EP</productName>

        <productFullname>${docNameCap} Example Project</productFullname>

        <version>${version_to_scan}</version>

        <configFiles>
            <param>${project.basedir}/src/${docName}conf.xml</param>
        </configFiles>
        <workflowDefinitionFile>${project.basedir}/src/workflow.xml</workflowDefinitionFile>
        <workflow>
            <processors>
                <step>
                    <name>Source Validator</name>
                    <classHint>org.eclipse.sw360.antenna.validators.workflow.processors.SourceValidator</classHint>
                    <configuration>
                        <entry>
                            <entryKey>missingSourcesSeverity</entryKey>
                            <entryValue>FAIL</entryValue>
                        </entry>
                        <entry>
                            <entryKey>incompleteSourcesSeverity</entryKey>
                            <entryValue>WARN</entryValue>
                        </entry>
                    </configuration>
                    <deactivated>true</deactivated>
                </step>
            </processors>
            <generators>
                <step>
                    <name>CSV Report Writer</name>
                    <classHint>org.eclipse.sw360.antenna.workflow.generators.CSVGenerator</classHint>
                </step>
            </generators>
        </workflow>

        <copyrightHoldersName>${docNameCap} Company</copyrightHoldersName>
        <copyrightNotice>All rights reserved</copyrightNotice>

        <skip>false</skip>
    </configuration>
</plugin>
```

You can define the workflow as described in the [Workflow configuration](./workflow-configuration.html) and you can even
augment your workflow definition file by adding some steps in the maven `pom.xml`.
The only difference is that in the `pom.xml` you cannot use the notation `<entry key="somekey" value="somevalue">`, you have to use the long form.

If a workflow is present in the pom, it will get merged with any `workflow.xml` provided by you or by the assembly.

* Properties of existing steps will be changed.
* New steps are added at the end of the list of steps in the same segment (analyzers, processors, generators and output handlers).

#[[###]]# Workflow properties in the `pom.xml`

Defining the workflow in the `pom.xml` allows defining and using properties in the workflow.

* Properties which do not contain dots are rendered into the workflow for all frontends.
  Properties containing a dot such as `user.password` are in general not rendered correctly so cannot be used.
* For Maven, all properties known to maven are fully resolved in the `pom.xml` and can therefore be used in the step configuration.
* For Gradle and CLI, only some `project` properties are resolved. The list is equivalent to the list in the [Workflow configuration](./workflow-configuration.html)


#[[###]]# Additional configuration for Java 9 or newer
Since some Java EE dependencies like JAXB have been removed from the standard installation 
one has to manually add these dependencies when configuring the plugin.

```xml
<plugin>
    <groupId>${antennaMavenGroupId}</groupId>
    <artifactId>${antennaMavenPluginName}</artifactId>
    <version>x.y.z</version>
    <configuration>
        <!-- ... -->
    </configuration>
    <dependencies>
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jaxb</groupId>
            <artifactId>jaxb-runtime</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>javax.activation</groupId>
            <artifactId>activation</artifactId>
            <version>1.1.1</version>
        </dependency>
    </dependencies>
</plugin>
```