Common Configuration

An addon is configured in a file called form.xml. We can distinguish two parts to the configuration of an addon:

The web’s user interface configuration, which will allow the user to define and collect the required user inputs.
The execution phase configuration, which will allow to configure which scripts are to be executed, in which order and with which parameters.

The following sections will help you understand how to configure an addon and provide the list of attributes common to all types of addons.

You can find the XML schema for form.xml in form.xsd.

User Interface

Defining Parameters

The structure of an addon’s form.xml file for parameters is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<tags baseName="Generic" image="CustomDP.png" ...>
	<tag type="multipleChoice" displayType="checkbox" key="tests" optionTitle=" ">
		<value key="firstKey" ... />
		...
	</tag>
	<tag type="booleanChoice" key="ignore_missing_sources" defaultValue="false" />
	<tag type="file" key="input_file" defaultValue="myFile.xml" multi="true"/>
	<tag type="text" key="java_path" defaultValue="/usr/bin/java" hide="true" />
	<tag type="password" required="true" key="password" />
	...
</tags>

The tags element accepts the following attributes:

image (optional, default: none) allows displaying a logo in the web UI.

Each tag element is a tool option and allows the following attributes:

key (mandatory) is the option’s key that will be passed to the script, or can be used to specify the parameter’s value from the command line.

type (mandatory) defines the type of the parameter. The following values are accepted:

text for free text entry.
file for file path with native permission and validity checks.
directory for directory path with native permission and validity checks.
file_or_directory for file or directory path with native permission and validity checks.
password for password fields.
token for token fields.
booleanChoice for a boolean.

multipleChoice for offering a selection of predefined values.

Predefined values are specified with a value element with a mandatory key attribute and an optional option attribute that allows modifying the value of the option from the UI. The input field for each option attribute is only displayed if the parent tag contains an optionTitle attribute.

displayType (optional) allows specifying how to display a multipleChoice parameter by using one of:
- comboBox
- radioButton
- checkbox
- multi-autocomplete
multi (optional, default: false) allows for dynamic addition/removal of multiple files or directories path.
defaultValue (optional, default: empty) is the value used for the parameter when not specified.
hide (optional, default: false) allows hiding a parameter from the web UI, which is useful when combining it with a default value.
changeable (optional, default: true) allows making a parameter configurable only when creating the project but read-only for following analyses when set to true.
style (optional, default: empty) allows setting basic css for the attribute in the web UI.
deprecated (optional, default: false) allows hiding the deprecated attribute from the GUI, while displaying a warning when it is being used from command line (instead of a crashing if simply removed).

required (optional, default: false) allows showing a red asterisk next to the field in the web UI to make it visibly required.

You can use a required tag of type booleanchoice to ensure that users must check a box in the web UI or set its value to true when building from the command line in order to proceed with the analysis.

<tag type="booleanChoice" required="true" key="accept_privacy_policy" />

Figure 1. Clicking the Next button without checking a required checkbox displays an error

The tag element also accepts a child element, displayIf, which can be used to hide elements in the web UI.

The displayIf element accepts logical and conditional conditions:

and (optional, applied by default), all conditions defined in the and container must be true in order to display tagged items.
or (optional), one condition defined in the or container must be true in order to hide tagged items.
equals (optional) this element is associated to a tag element defined in the key and value attributes. The tagged element must contain the value specified in the value attribute in order to be displayed in the web UI.
notEmpty (optional) the tag element defined in the key attribute has to be filed in order to display element in the web UI.

Example of conditional display

	<tag type="text" key="config_file" hide="true"/>
	<tag type="text" key="url" required="true" >
		<displayIf>

			<notEmpty key="max_results" />

		</displayIf>
	</tag>
	<tag type="text" key="api_token" required="true" >
		<displayIf>
			<or> <!-- Conditional containers can be stacked  -->
				<equals key="max_results" value="100"/>
				<notEmpty key="url" />
			</or>
		</displayIf>
	</tag>
	<tag type="text" key="max_results" required="true" defaultValue="50" />

Adding Descriptions

In order to display your addon parameters in different languages in the web UI, your addon’s form.xml does not contain any hard-coded strings.

Instead, Squore uses each parameter’s key attribute to dynamically retrieve a translation from a form_xx.properties file located next to the form.xml file.

When you create an addon, it is mandatory to include at least an English version of the strings in a file called form_en.properties. You are free to add other languages as needed.

To know more about the descriptions syntax, have a look at the Properties files section.

Execution Phase

This section will show you how to use the addons parameters defined in the web UI and pass them to one or more scripts or executables.

This is done by defining an exec-phase element, which syntax is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<tags baseName="Generic" image="CustomDP.png" ...>
	...
	<exec-phase id="add-data">
		<exec name="tcl|perl|java" | executable="/path/to/bin" | executable="executable_name" failOnError="true|false" failOnStdErr="true|false" warn="[WARN]" error="[ERROR|ERR]" fatal="[FATAL]">
			<arg value="${<function>(<args>)}"/>
			<arg value="-freeText" />
			<arg value="${<predefinedVars>}" />
			<arg value="versions" />
			<arg value="-myTag"/>
			<arg tag="myTag"/>
			<env key="MY_VAR" value="SOME_VALUE"/>
		</exec>
		<exec ... />
	</exec-phase>

Executables

The exec-phase element accepts the following attributes:

id which defines the phase the execution corresponds to. Phases are specific to addons type, refer to the adequate section in order to know the accepted values for your addon.

The exec-phase element allows for multiple child element, exec, which accepts the following attributes:

name to define the executables language. Accepted values are:
- tcl
- perl
- java
The scripts are launched using the tcl, perl, or java runtimes defined in your Squore installation.
failOnError (optional, default: true) marks the Data Provider execution as failed if the executable returns an error code.
failOnStdErr (optional, default: true) marks the Data Provider execution as failed if the executable prints something to stdErr during the execution.
warn , error and fatal (optional, default: see code block above) allow you to define patterns to look for in the executable’s standard output to fine-tune the result of the execution.

When using Groovy scripts, the java engine is handling them. The basic syntax of a Groovy exec name is indicated below:

<exec name="java">
            <arg value="${javaClasspath(poi,groovy,jackson)}"/>
            <arg value="groovy.lang.GroovyShell" />
            <arg value="${getConfigFile(to_excel.groovy)}"/>
...

Other executables can be called, as long as they are available on the system’s PATH, or configured in config.xml

Given the following config.xml:

<!-- config.xml (server or cli) -->
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<squore type="server" version="1.3">
	<paths>
		<path name="python" path="C:\Python\python.exe" />
		<path name="git" path="C:\Git\bin\git.exe" />
	</paths>
...
</squore>

Git and python can be called as follows:

<exec-phase id="add-data">
	<exec name="git">
		...
	</exec>
	<exec name="python">
		...
	</exec>
</exec-phase>

Arguments

The exec element accepts arg and env child elements in order to define the arguments and environment variables expected by the executable.

The env element accepts the following attributes:

key to define the environment variable name.
value to define the environment variable value. Same accepted values as value attribute for arg element, see below.

The arg element accepts the following attributes:

tag to pass the value of a web UI parameter for retrieving the input specified by the user. If no input was specified, you can provide a defaultValue.

value to pass any string. Accepted values are:

free text, which can be useful to specify a parameter for your script.

Any of the following predefined functions:

${getAddonsFile(<relative/path/to/file>)} returns the absolute path of a file in the addon’s <SQUORE_HOME>/addons folder.
${getConfigFile(<relative/path/to/file>)} returns the absolute path of a file in the addon’s <SQUORE_HOME>/configuration folder.
${getSharedAddonsFile(<relative/path/to/file>)} returns the absolute path of a file in addon’s addons/shared folder, if not returns the absolute path of a file in addons/shared folder.
${getConfigFiles()} returns the path of a config-files.xml file containing the list of files present in the addon’s <SQUORE_HOME>/configuration folder.
${getOptionsFile(tags,rules,storage)} returns the absolute path of an XML file containing the content related to the comma-separated list of specified options. Accepted options are the following:
- Available for all execution phases:
  - tags, to retrieve the addon’s list of parameters from the current analysis.
  - config-files, to retrieve the addon’s configuration files paths.
- Only available for execution phases, add-data, repo-add-data, import and ruleset:
  - previous-tags, to retrieve the addon’s list of parameters from the previous analysis.
  - repositories, to retrieve the list of repositories folders where sources have been extracted.
  - storage, to retrieve the storage, previous draft and previous baseline folders path.
  - rules, to retrieve the list of rules contained in the model used during the analysis.
  - finding-statuses, to retrieve the list of available findings statuses types.
${getTagValue(<tag-key>)} returns the corresponding tag value.
${path(<executable_name>)} returns the absolute path of an executable configured in config.xml, or just the executable name if the executable is available from the system’s PATH.
```
<exec name="...">
	<arg value="-git_path" />
	<arg value="${path(git)}" />
```

${javaClasspath(poi,groovy,jackson,abc.jar,xyz.jar)} adds the specified list of jars to the classpath for java execution.

Squore will look for the jars first in the configuration/tools/<toolName>/lib folder, then in the addons/lib folder of your configuration and return a classpath parameter for the desired runtime environment (-cp="…" for java).

poi is a shortcut for poi-ooxml-3.17.jar,poi-3.17.jar,poi-ooxml-schemas-3.17.jar,xmlbeans-2.6.0.jar,commons-collections4-4.1.jar and configures the environment necessary to use Apache POI when creating custom Export Definitions, as described in Exports.

groovy is a shortcut for groovy-3.0..jar, groovy-json-3.0..jar and groovy-xml-3.0.*.jar libraries needed to run Groovy scripts.

jackson is a shortcut for jackson-core-2.10.1.jar, jackson-databind-2.10.1.jar and jackson-annotations-2.10.1.jar libraries needed to parse Json file.

squore-api is a shortcut for squore-rest-assured-api.jar, squore-rest-utils.jar and all Jackson libraries to use Squore Rest Api.

*plugins" is a shortcut for all .jar files under the configuration/tools/<toolName>/plugins folder.

Any of the following predefined variables:
- ${tmpDirectory} is an absolute path to a temp folder to create files.
- ${sourcesList} is a list of the aliases and locations containing the data extracted by the repository connectors used in the analysis.
- ${outputDirectory} is the absolute path of folder where the addon needs to write its output files.
- ${login} is the login of the user executing the script.
- ${idUser} is the ID (stored in the DB) of the user executing the script.
- ${localUrl} is the Squore local URL.
- ${token} is the auto-generated token for on the fly authentication to the API REST.

Conditions

You can use condition statements in the exec and exec-tool elements in order to parametrize the execution of your addon phase. The executeIf element is used as follows :

<exec-phase id="add-data">
    <exec name="java">
        <executeIf>
            <equals key="outputFile" value="" />   <!-- Execute this Java process only if the output file is not provided. -->
        </executeIf>
        ...
    </exec>
</exec-phase>

The executeIf element uses the same syntax as the displayIf element:

and (optional, applied by default), all conditions defined in the and container must be true in order to display tagged items.
or (optional), one condition defined in the or container must be true in order to hide tagged items.
equals (optional) this element is associated to a tag element defined in the key and value attributes. The tagged element must contain the value specified in the value attribute in order to be displayed in the web UI.
notEmpty (optional) the tag element defined in the key attribute has to be filed in order to display element in the web UI.

Post-Execution Phase

You can call and pass parameters to other addons after your exec-phase using an exec-tool element.

The exec-tool element uses a mandatory attribute:

name which is the name of the folder containing the other addon to launch in your configuration folder.

One or more param child elements can be appended to exec-tool in order to pass the parameters expected by this other addon. It allows for the following attributes:

key is the name of the parameter expected by the other addon (as defined in its form.xml).
value allows passing free text.
tag allows passing the value of your own addon’s tag value to the other addon and can be combined with a defaultValue attribute in case no value was specified by the user for the tag.

Example of a Data Provider generating a CSV file that is then passed to the pep8 Data Provider

<exec-phase id="add-data">
	<exec name="python">
		<arg value="consolidate-reports-recursive.py" />
		<arg value="-folders" />
		<arg tag="root_folder" />
		<arg value="-outputFile" />
		<arg value="output.csv" />
	</exec>
	<exec-tool name="pep8">
		<param key="csv" value="${getOutputFile(output.csv)}" />
		<param key="separator" tag="separator" defaultValue=";" />
	</exec-tool>
</exec-phase>

If your addon uses a perl script, Squore provides a small library that makes it easy to retrieve script arguments called SQuORE::Args. Using it as part of your script, you can retrieve arguments using the get_tag_value() function, as shown below:

# name: export_ticket.pl
# description: exports issues to a CSV file
use SQuORE::Args;
# ...
# ...
my $url = get_tag_value("url");
my $login = get_tag_value("login");
my $pwd = get_tag_value("pwd");
my $outputFile = get_tag_value("outputFile");
# ...
exit 0;

If you want to find more examples of working addons that use this syntax, check the following Data Providers in Squore’s default configuration folder:

conf-checker calls a jar file to write an XML file in Squore’s exchange format.
import_ticket parses a file to translate it into a format that can then be passed to csv_import to import the tickets into Squore.
jira retrieves data from Jira and passes it to import_ticket.