Specific Configurations

Data Providers

Data Providers are utilities that run during an analysis. They usually take an input file to parse or parameters specified by the user to generate output files containing violations or metrics to add to your project. Here is a non-exhaustive list of what some of them do:

  • Use XSLT files to transform XML files.

  • Read information from Microsoft Excel files.

  • Parse HTML test results.

  • Query web services.

  • Launch external processes.

User Interface

The tags element accepts the following additional attributes for Data Providers:

  • baseName (mandatory if you are not using an exec-phase) indicates the base framework. The value of this attribute must match a sub-folder from one of the "<SQUORE_HOME>/addons/<type>" folders of your installation.

  • needSources (optional, default: false) allows specifying whether the Data Provider requires sources or not. When set to true, an error will be displayed if you try to select this Data Provider without adding any Repository Connector location to your project.

  • projectStatusOnFailure (optional, default: WARNING) defines what status the project ends in when this Data Provider produces an error. The following values are allowed:

    • IGNORE

    • WARNING

    • ERROR

  • projectStatusOnWarning (optional, default: WARNING) defines what status the project ends in when the tool produces a warning. The following values are allowed:

    • IGNORE

    • WARNING

    • ERROR

  • provide (optional) allows specifying which rules standards are provided by the Data Provider. Corresponding rulesets will be automatically activated and the others deactivated, if the Data Provider is included in the analysis.

  • deprecated (optional, default: false) to remove a Data Provider from the list of available Data Providers for new projects, while keeping it available for existing projects that already have used it.

The tag element accepts the following additional attributes for Data Providers:

  • provide (optional) allows specifying which rules standards are provided by the Data Provider. Can only be provided if type=booleanChoice, in which case corresponding rulesets will be automatically activated and the others deactivated, if parameter is checked.

The value element accepts the following additional attribute for Data Providers:

  • provide (optional) allows specifying which rules standards are provided by the Data Provider. Corresponding rulesets will be automatically activated and the others deactivated, if the value is selected.

If you are not seeing your Data Provider in Squore’s web interface, make sure you are familiar with the Data Providers chapter.

If you have made the adequate changes and your Data Provider still does not appear in your wizard, consult the Validator to find out if it was disabled because of an error in its configuration.

ALL ValidateDPs
Figure 1. The General section of the Validator shows errors in your Data Providers

Execution Phase

At the end of a Data Provider execution, Squore expects a file named input-data.xml to be written in a specific location. The syntax of the XML file to generate is as follows:

<!-- input-data.xml syntax -->
<bundle version="2">
	<artifact [local-key=""] [local-parent=""|parent=""] >
        <artifact [id="<guid-stable-in-time-also-used-as-a-key>"] name="Component" type="REQ" [location=""] >
			<info name|n="DESCR" value="The description of the object"/>
			<key value="3452-e89b-ff82"/>
			<metric name="TEST_KO" value="2"/>
			<finding name="AR120" loc="xxx" p0="The message" />
			<link name="TEST" local-src=""|src=""|local-dst=""|dst="" />
				<artifact id="" name="SubComponent" type="REQ">
				...
				</artifact>
		</artifact>
	</artifact>

	<artifact id="" local-key="" name="" type="" local-parent=""|parent="" [location=""] />
	...

	<link name="" local-src=""|src="" local-dst=""|dst="" />
	...

	<info local-ref=""|ref="" name="" value=""/>
	...

	<metric local-ref=""|ref="" name="" value=""/>
	...

	<finding local-ref=""|ref="" [location=""] p0="" />
	<finding local-ref=""|ref="" [location=""] p0="">
		<location local-ref=""|ref="" [location=""] />
		...
		<relax status="RELAXED_DEROGATION|RELAXED_LEGACY|RELAXED_FALSE_POSITIVE"><![CDATA[My Comment]]></relax>
	</finding>
	...
</bundle>

You can find the XML schema for input-data.xml in ref_input-data-2.xsd.

A Data Provider can also synchronize Squore rules with the set of rules and/or configuration that was active during the third-party tool execution it is importing the results from.

To do so, a Data Provider must create a ruleset file (ruleset.xml) in a specific location that will contain the list of these active rules. This file will then be reused by Squore to do the synchronization. Here is an example of ruleset.xml file content:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<UpdateRules>
    <UpdateRule measureId="ACTIVE_RULE_ID_1" disabled="false" />
    <UpdateRule measureId="ACTIVE_RULE_ID_2" disabled="false" />
    ...
</UpdateRules>

The exec-phase element accepts the following attributes:

  • id which defines the phase the execution corresponds to. Accepted phase value for Data Providers is:

    • ruleset for the construction of file ruleset.xml.

    • add-data for the construction of file input-data.xml.

On top of common variables and functions, Data Providers allow for the following additional:

  • ${getOutputFile(<relative/path/to/file>,<abortIfMissing>)} returns the absolute path of an input-data.xml file output by an exec-phase.

    • abortIfMissing is an optional boolean which aborts the execution when set to true if the file is missing.

  • ${getTemporaryFile(<relative/path/to/file>)} returns the absolute path of a temporary file created by an exec.

  • ${versionDate} is the current version date if defined, build date otherwise.

  • ${lastBaselineVersionDate} is the last baseline version date if defined, build date otherwise.

Built-in Data Provider Frameworks

In order to help you import data into Squore, the following Data Provider frameworks are provided and can write a valid input-data.xml file for you:

  1. csv_import

    The csv_import framework allows you to write Data Providers that produce CSV files and then pass them on to the framework to be converted to an XML format that Squore understands. This framework allows you to import metrics, findings, textual information and links as well as generate your own artefacts. It is fully linked to the source code parser and therefore allows to locate existing source code artefacts generated by the source code parser. Refer to the full csv_import Reference for more information.

  2. xml

    The xml framework is a sample implementation of a Data Provider that allows you to directly import an XML file or run it through an XSL transformation to that it matches the input format expected by Squore (input-data.xml). This framework therefore allows you to import metrics, findings, textual information and links as well as generate your own artefacts. Refer to the full xml Reference for more information.

If you are looking for the legacy Data Provider frameworks from previous versions of Squore, consult Legacy Frameworks.

The legacy Data Provider frameworks are still supported, however using the new frameworks is recommended for developing new Data Providers, as they are more flexible and provide more functionality to interact with source code artefacts.

Offline XSL Transformations

This section describes how to provide a catalog file to a Data Provider for offline XSL transformation.

When transforming an XML results file with an XSL stylesheet, the XML parser used by Squore will try to validate the XML file against the DTD declared in the XML header. In cases where the XSL transformation is running on a machine with no internet access, this can result in the execution of the Data Provider failing with a No route to host error message.

You can fix this issue by modifying the Data Provider to use a catalog file that will provide an alternate location for the DTD used to validate the XML. This feature can be used by all Data Providers that include an XSL transformation [1] .

The following example adds this functionality to the Cobertura Data Provider:

  1. Add a catalog.xml file in the Data Provider’s configuration folder:

    <configuration>/tools/cobertura/catalog.xml:
<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
	<rewriteSystem systemIdStartString="http://cobertura.sourceforge.net/xml" rewritePrefix="./DTD"/>
</catalog>

  2. Copy the dtd that the XML needs to validate again inside a DTD folder in <configuration>/tools/cobertura/.

The catalog file will be used the next time the Data Provider is executed and the DTD declaration will dynamically be changed from:

<!DOCTYPE coverage SYSTEM "http://cobertura.sourceforge.net/xml/coverage-04.dtd">

to:

<!DOCTYPE coverage SYSTEM "<configuration>/tools/cobertura/DTD/coverage-04.dtd">">

For more information about how to write your catalog file, refer to https://xerces.apache.org/xerces2-j/faq-xcatalogs.html.

Repository Connectors

Repository Connectors are used to specifically retrieve source code and other data from source code management systems.

User Interface

The tags element accepts the following additional attributes for Repository Connectors:

  • deleteTmpSrc (optional, default: false) indicates whether the downloaded source code should be removed from the sources folder at the end of each analysis.

  • useCredentialsForSCA (optional, default: true) allows specifying whether credentials dialog will be prompted in View Source Code or not.

  • projectStatusOnFailure (optional, default: ERROR) defines what status the project ends in when this Repository Connector produces an error. The following values are allowed:

    • IGNORE

    • WARNING

    • ERROR

  • projectStatusOnWarning (optional, default: WARNING) defines what status the project ends in when the tool produces a warning. The following values are allowed:

    • IGNORE

    • WARNING

    • ERROR

If you are not seeing your Data Provider in Squore’s web interface, make sure you are familiar with the Repository Connectors chapter.

If you have made the adequate changes and your Data Provider still does not appear in your wizard, consult the Validator to find out if it was disabled because of an error in its configuration.

ALL ValidateDPs
Figure 2. The General section of the Validator shows errors in your Data Providers

Execution Phase

The exec-phase element accepts the following attributes:

  • id which defines the phase the execution corresponds to. Accepted phases value for Repository Connectors are:

    • import defines how you extract source code and make it available to Squore Analyzer so it can be analysed. This phase is expected to return a path to a folder containing the sources to analyse or a data.properties file listing the path to the folder containing source and various other properties to be used in other executions:

      directory=/path/to/sources-to-analyse
data.<key1>=<value1>
data.<key2>=<value2>

    • repo-add-data is expected to produce an input-data.xml file. This phase is executed once per source code node in the analysis.

    • display is the phase that is called when users request to view the source code for an artefact from the web UI. This phase is expected to return a data.properties file with the following keys:

      filePath=/path/to/source/file
displayPath=<Artefact Display Path (optional)>

      The contents of filePath will be loaded in the source code viewer, while the value of displayPath will be used as the file path displayed in the header of the source code viewer.

Consult SVN’s full form.xml file in <SQUORE_HOME>/configuration/repositoryConnectors/SVN for a working example of a Repository Connector that uses all the phases described above.

The exec element accepts the following attributes:

  • forkProcess (default: true), allows to define whether Groovy scripts are executed in separate processes or not (i.e. outside of Squore Server JVM). Only available for java executables during display phase.

On top of common variables and functions, Repository Connectors allow for the following additional:

  • ${getOutputFile(<relative/path/to/file>,<abortIfMissing>)} returns the absolute path of an input-data.xml file output by an exec-phase.

    • abortIfMissing is an optional boolean which aborts the execution when set to true if the file is missing.

  • ${getTemporaryFile(<relative/path/to/file>)} returns the absolute path of a temporary file created by an exec.

  • ${getImportData(<key1>)} returns any repository data from the import phase during the display phase.

  • ${outputSourceDirectory} is the folder containing the sources to analyse.

  • ${alias} is the alias used for the source code node. Empty if there is only one source code node.

  • ${scaInfo} is text to display in the title bar of the source code viewer in the web interface.

  • ${artefactName} is the name of the file to display.

  • ${artefactPath} is the path (without the alias) of the file to display.

  • ${versionDate} is the current version date if defined, build date otherwise.

  • ${lastBaselineVersionDate} is the last baseline version date if defined, build date otherwise.

Exports

Exports can help you extract data from Squore by allowing you to export it to any desired output format. A set of pre-defined export already exists in Squore, but you can define your own custom exports.

User Interface

Exports are made available in Squore’s web interface by being added into "<SQUORE_HOME>/configuration/models/<your-model>/Exports/Bundle.xml" file.

Here is an example of a bundle file:

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<xi:include href="import.xml" />
	<Package xmlns:xi="http://www.w3.org/2001/XInclude" >
		<ExportDef name="highlights_excel" onArtefactTypes="MODEL;PACKAGES" />
		<ExportDef name="highlights_json" onArtefactTypes="MODEL;PACKAGES" />
		<ExportDef name="highlights_xml" onArtefactTypes="MODEL;PACKAGES" />
		<ExportDef name="highlights_csv" onArtefactTypes="MODEL;PACKAGES" />
	</Package>
</Bundle>

The ExportDef element takes the following attributes:

  • name is the name of the export folder located in "<SQUORE_HOME>/configuration/exports"

  • onArtefactTypes (optional, default: any) is a semicolon-separated list of artefact types that this item applies to.

  • roles (optional, default: any) is a semicolon-separated list of project roles that are allowed to view and use this item.

  • groups (optional, default: any) is a semicolon-separated list of user groups that are allowed to view and use this item.

  • displayOnlyIf (optional) allows specifying a computation to evaluate whether to show the element. If the result of the computation is more than 0, then the element is displayed. Consult Expressions Syntax for more information about the supported computation syntax.

In the form.xml file, the tag element accepts the following additional attributes for Exports:

  • displayType (optional) allows specifying how to display a multipleChoice parameter by using one of:

    • multi-autocomplete

      Instead of multiple value elements, a sub-element values can be added, with a mandatory type attribute which only accepts the value: highlights. This allows to provide all the available Highlights at the current artefact level for selection.

Execution Phase

The exec-phase element accepts the following attributes:

  • id which defines the phase the execution corresponds to. Accepted phases value for Exports are:

    • export is expected to return a data.properties file with the following keys:

      filename=/path/to/export/file

On top of common variables and functions, Exports allow for the following additional:

  • ${idArtefact} is the ID of the currently selected artefact.

  • ${idVersion} is the ID of the version of the project that is currently selected.

  • ${idRefVersion} is the ID of the reference version of the project selected by the user. Returns the previous version ID if nothing has been selected, and null if the project has only one version.

  • ${idBranch} is the ID of the branch of the project that is currently selected.

  • ${idApplication} is the ID of the project that currently selected.

  • ${idModel} is the ID of the analysis model used for the project that is currently selected.

  • ${group} is the path of the current selected group portfolio.

  • ${serverUrl} is the Squore Server URL, as defined in Administration > System.

  • ${userLanguage} is the user interface language configured by the user.

Custom Tabs

Custom Tabs allow to display tailored HTML content generated via a script in additional tabs of the Explorer page.

User Interface

Custom Tabs are made available in Explorer page by being added into "<SQUORE_HOME>/configuration/models/<your-model>/Tabs/Bundle.xml" file.

Here is an example of a bundle file:

<?xml version="1.0" encoding="UTF-8"?>
<Bundle>
	<Tab name="introduction" onArtefactTypes="APPLICATION" borderColor="#f19c60" />
</Bundle>

The Tab element takes the following attributes:

  • name is the name of the custom tab folder located in "<SQUORE_HOME>/configuration/tabs".

  • onArtefactTypes (optional, default: any) is a semicolon-separated list of artefact types that this item applies to.

  • roles (optional, default: any) is a semicolon-separated list of project roles that are allowed to view and use this item.

  • groups (optional, default: any) is a semicolon-separated list of user groups that are allowed to view and use this item.

  • displayOnlyIf (optional) allows specifying a computation to evaluate whether to show the element. If the result of the computation is more than 0, then the element is displayed. Consult Expressions Syntax for more information about the supported computation syntax.

  • autoRun (optional, default: true) allows to specify whether the custom tab is executed automatically or manually via a button in the tab.

  • borderColor (optional, default: none) allows to define a color for the tab header’s left border. Accepted values are hexadecimal color codes.

No tag elements are supported in the form.xml file.

A Custom Tab example can be found in Squore at the APPLICATION level for projects using Software Analytics model. Configuration files for this example can be found in <SQUORE_HOME>/configuration/tabs/introduction folder.

Execution Phase

The exec-phase element accepts the following attributes:

  • id which defines the phase the execution corresponds to. Accepted phases value for Custom Tabs are:

    • tab is expected to return a data.properties file with the following keys:

      filename=name-of-generated-file-in-outputDirectory.html
or
url=http://full.external.url/to/display/in/custom/tab

The exec element accepts the following attributes:

  • forkProcess (default: true), allows to define whether Groovy scripts are executed in separate processes or not (i.e. outside of Squore Server JVM). Only available for java executables during tab phase.

On top of common variables and functions, Custom Tabs allow for the following additional:

  • ${idArtefact} is the ID of the currently selected artefact.

  • ${idVersion} is the ID of the version of the project that is currently selected.

  • ${idRefVersion} is the ID of the reference version of the project selected by the user. Returns the previous version ID if nothing has been selected, and null if the project has only one version.

  • ${idBranch} is the ID of the branch of the project that is currently selected.

  • ${idApplication} is the ID of the project that currently selected.

  • ${idModel} is the ID of the analysis model used for the project that is currently selected.

  • ${group} is the path of the current selected group portfolio.

  • ${serverUrl} is the Squore Server URL, as defined in Administration > System.

  • ${userLanguage} is the user interface language configured by the user.

If no exec-phase is configured in form.xml file, then a static index.html file located in the custom tab folder will try to be loaded for display.

External Tools

Squore uses a menus folder in its configuration, so you can add functionalities that will be available in Squore’s web interface to run as external tools.

These external scripts are launched in Squore Server’s context, and can therefore benefit from Squore’s authentication and permission mechanism. They are launched from the web interface via a Tools menu visible to the users whose global role grants access to the Use External Tools feature.

CFG customMenu
Figure 3. A Tools menu containing an external tool to create a demo environment, and the associated page to configure and launch the script.

User Interface

An external tool is made available in Squore’s web interface by adding a sub-folder in "<SQUORE_HOME>/configuration/menus".

In the form.xml file, the tags element accepts the following additional attributes for External Tools:

  • formatLog (optional, default: true) provides the options to turn off console log colourisation.

  • task (optional, default: false) displays a link to this tool on the Home page in the Tasks section when set to true.

  • multiUsers (optional, default: false) defines whether only one running instance of the tool is allowed per user (true) or whether only one running instance at a time is allowed for the entire Squore Server (false).

  • users (optional, default: empty) is a semicolon-separated list of user logins. If specified, this attribute limits the availability of the menu to the users explicitly listed.

  • groups (optional, default: empty) is a semicolon-separated list of user groups. If specified, this attribute limits the availability of the menu to users belonging to the groups explicitly listed.

The tag element accepts the following additional attributes:

  • acceptedTypes (mandatory) are the accepted file types. Follows the HTML MIME types convention.

Execution Phase

The exec-phase element accepts the following attributes:

  • id which defines the phase the execution corresponds to. Accepted phases value for External Tools are:

    • process for the execution of the script.

On top of common variables and functions, External Tools allow for the following additional:

  • ${homeDirectory} is the path to Squore’s installation folder.

1. The list includes: