Configuration Guide

This document was released by Squoring Technologies.

It is part of the user documentation of the Squore software product edited and distributed by Squoring Technologies.

The Squore Configuration Guide provides a complete reference for the configuration and administration of Squore 18.0.18, with step-by-step instructions to customise the different models that define Squore behaviour.

This manual is intended for Squore administrators. It allows to fine-tune the Squore configuration to fit specific needs or contexts. Note however, that the default parameters work in most cases for most users, and that only experienced and technical-savvy users should try to modify those settings.

If you are already familiar with Squore, you can navigate this manual by looking for what has changed since the previous version. New functionality is tagged with (new in 18.0) throughout this manual. A summary of the new features described in this manual is available in the entry *** What's New in Squore 18.0? of this manual's Index.

For information on how to use and configure Squore, the full suite of manuals includes:

If the information provided in this manual is erroneous or inaccurate, or if you encounter problems during your installation, contact Squoring Technologies Product Support: https://support.squoring.com/

You will need a valid Squore customer account to submit a support request. You can create an account on the support website if you do not have one already.

For any communication:

Approval of this version of the document and any further updates are the responsibility of Squoring Technologies.

The version of this manual included in your Squore installation may have been updated. If you would like to check for updated user guides, consult the Squoring Technologies documentation site to consult or download the latest Squore manuals at https://support.squoring.com/documentation/18.0.18. Manuals are constantly updated and published as soon as they are available.

Squore process overview

The picture above shows the different components involved in the Squore process.

The main building blocks of the Squore configuration are:

Models define how Squore computes metrics (analysis model), how action items are created (decision model), and how data is displayed (dashboards and reports).

All models are located in the <SQUORE_HOME>/configuration/models directory.

Each folder in <SQUORE_HOME>/configuration/models is a separate model. Each model has a wizard, i.e. a series of screens where users configure the options available for the model before launching an analysis, as described in Chapter 8, Understanding Project Wizards.

The Shared folder is different, since it is not a self-contained model, but rather a collection of components that are meant to be imported by other models in the configuration. This avoids creating redundancy, and redefining the same metrics or indicators every time.

The Shared Model is located in the same directory as other models: <SQUORE_HOME>/configuration/models. Its structure is similar to other models, but it does not appear in the user interface. To understand some of the common measures and rules used across Squore you can take a look at the common definitions available in <SQUORE_HOME>/configuration/models/Shared/Analysis/product_quality/code, especially:

Squore is fully customisable and allows you to override the default models and add your own ones. Your modifications to the default configuration should never be made directly in <SQUORE_HOME>/configuration, but in your own configuration folder which you will make Squore aware of by editing <SQUORE_HOME>/config.xml. This allows you to create only the files that are needed for your modifications and minimise the amout of files to add to version control.

In order to add a configuration folder for your modifications:

Squore now knows that it needs to load the models that exist in your custom configuration as well as the ones in the default configuration folder. If you want to override a file in the default configuration folder, recreate the folder structure in your custom configuration folder, copy the file from the default configuration folder and make the necessary modifications. Because the custom configuration folder is listed first in <SQUORE_HOME>/config.xml, the file in the custom configuration folder will be used instead of the file in the default configuration folder.

Creating a new model is as simple as creating a folder in your custom configuration folder and creating the various definition files needed for the Analysis Model, the Decision Model, the dashboard and reports you want to enable:

The following section of this manual will cover how to use existing packages from the Shared folder and how to display text in the web infterface.

All 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:

Repository Connectors are based on the same model and are used to specifically retrieve source code and other data from source code management systems.

Read on to learn about how to configure your Data Provider and make it available in the web interface, and then understand how to implement the scripted part of a Data Provider that is executed during an analysis.

The last part fo this section also introduces two frameworks that you can base your Data Providers on depending on whether you prefer to produce CSV or XML files for Squore.

Data Provider Parameters

A Data Provider's parameters are defined in a file called form.xml. The following is an example of form.xml for a Data Provider extending the GenericPerl framework:

CustomDP parameters

<?xml version="1.0" encoding="UTF-8"?>
<tags baseName="GenericPerl" needSources="true" image="CustomDP.png" projectStatusOnFailure="ERROR">
	<tag type="multipleChoice" displayType="checkbox" optionTitle=" " key="tests">
		<value key="ux" option="usability" />
		<value key="it" option="integration" />
		<value key="ut" option="unit" />
	</tag>
	<tag type="booleanChoice" key="ignore_missing_sources" defaultValue="false" />
	<tag type="text" key="input_file" defaultValue="myFile.xml" changeable="false" />
	<tag type="multipleChoice" key="old_results" style="margin-left:10px" displayType="radioButton" defaultValue="Exclude">
		<value key="Exclude" />
		<value key="Include" />
	</tag>
	<tag type="text" key="java_path" defaultValue="/usr/bin/java" hide="true" />
	<tag type="password" required="true" key="password" />
</tags>

Tip

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

The tags element accepts the following attributes:

• baseName (mandatory if you are not using an exec-phase ) indicates on which framework you are basing this Data Provider. The value of this attribute must match a folder from the addons folder 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.

• image (optional, default: none) allows displaying a logo in the web UI for the Data Provider

• projectStatusOnFailure (optional, default: ERROR) 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 this Data Provider produces a warning. The following values are allowed:

  • IGNORE

  • WARNING

  • ERROR

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

• key (mandatory) is the option's key that will be passed to the perl 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

  • password for password fields

  • booleanChoice for a boolean

  • multipleChoice for offering a selection of predefined values

    Note

    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

• 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

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

  Tip

  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 (new in 18.0).

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

  

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

Localising your Data Provider

In order to display your Data Provider parameters in different languages in the web UI, yout Data Provider'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 form.xml.

When you create a Data Provider, 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. Here is a sample .properties for for the CustomDP you created in the previous section:

FORM.GENERAL.NAME  = CustomDP
FORM.DASHBOARD.NAME  = Test Status
FORM.GENERAL.DESCR = CustomDP imports test results for my project
FORM.GENERAL.URL   = http://example.com/CustomDP

TAG.tests.NAME  = Test Types
TAG.tests.DESCR = Check the boxes next to the types of test results contained in the results

TAG.ignore_missing_sources.NAME = Ignore Missing Sources

TAG.input_file.NAME = Test Results
TAG.input_file.DESCR = Specify the absolute path to the file containing the test results

TAG.old_results.NAME = Old Test Results
TAG.old_results.DESCR = If the previous analysis contained results that are not in this results file, what do you want to do with the old results?
OPT.Exclude.NAME = discard
OPT.Include.NAME = keep

TAG.password.NAME = File Password
TAG.password.DESCR = Specify the password to decrypt the test results file

The syntax for the .properties file is as follows:

• FORM.GENERAL.NAME is the display name of the Data Provider in the project wizard

• FORM.DASHBOARD.NAME is the display name of the Data Provider in the Explorer

• FORM.GENERAL.DESCR is the description displayed in the Data Provider's tooltip in the web UI

• FORM.GENERAL.URL is a reference URL for the Data Provider. Note that it is not displayed in ther web UI yet.

• TAG.tag_name.NAME allows setting the display name of a parameter

• TAG.tag_name.DESCR is a help text displayed in a tooltip next to the Data Provider option in the web UI

• OPT.option_name.NAME allows setting the display name of an option

Using the form_en.properties above for CustomDP results in the following being displayed in the web UI when launching an analysis:

CustomDP pulling translations from a .properties file

Tip

Not all wizards display all Data Providers by default. If your Data Provider does not appear after refreshing your configuration, make sure that your wizard bundle allows displaying all Data Providers by reviewing the tools element of Bundle.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Bundle>
	<Wizard ... >
		...
		<tools all="true">
			...
		</tools>
		...
	</Wizard>
</Bundle>

For more information about the wizard bundle, consult the the chapter called "Project Wizards" in the Configuration Guide.

If you have made this change 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.

The General section of the Validator shows errors in your Data Providers

<!-- input-data.xml syntax -->
<bundle version="2.0">
	<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>

<exec-phase id="add-data">
	<exec name="tcl|perl|java|javascript or nashorn" | 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-tool name="another_data_provider">
		<param key="<tagName>" value="<value>" />
		<param key="<tagName>" tag="<tag>" />
		<param ... />
	</exec-tool>
	<exec-tool ... >
		...
	</exec-tool>
</exec-phase>

<!-- 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>

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

<exec-phase id="add-data">
	<exec executable="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>

<exec-phase id="add-data">
	<exec name="perl"> 
		<arg value="${getToolConfigDir(export_ticket.pl)}" />
		<arg value="-url" />
		<arg tag="url" />
		<arg value="-login" />
		<arg tag="login" />
		<arg value="-pwd" />
		<arg tag="pwd" />
		<arg value="-outputFile" />
		<arg value="${getOutputFile(exportdata.csv,false)}" />
	</exec>
	<exec-tool name="import_ticket">
		<param key="input_file" value="${getOutputFile(exportdata.csv)}" />
		<param key="csv_separator" value=";" />
	</exec-tool>
</exec-phase>

# 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;

 <!-- form.xml -->
<exec-phase id="repo-add-data">
	<exec name="tcl">
		<arg value="${getToolAddonsDir(repo-add-data.tcl)}" />
		<arg value="${tclToolkitFile}" />
		<arg value="${squanOutputDirectory}" />
		<arg value="${outputDirectory}" />
		<arg tag="xxx" />
	</exec>
</exec-phase>

#repo-add-data.tcl:
set toolkitFile [lindex $argv 0]
set sqOutputDir [lindex $argv 1]
set outputDir [lindex $argv 2]
set xxx [lindex $argv 3]

# Initialise the toolkit
puts "Initializing toolkit"
source $toolkitFile
toolkit::initialize $sqOutputDir $outputDir
        
# Execute your code
puts "Main execution"
# yout code here
# ...

# Generate xml files (artefacts)
puts "Generating xml files"
toolkit::generate $outputDir {artefacts}

Analysis Models define how metrics data is computed and aggregated. You can browse and analyse models through the Models > Viewer menu in the Squore web interface.

Analysis Models define building blocks organised in a hierarchical structure. The following blocks can be used:

Blocks can refer to each others, for example computations use measures and rules. The syntax used for computations is documented in Chapter 5, Expression Syntax.

In order to rate your project, you can define artefact types and aliases in Squore. The artefact types used in the default configuration for source code are all defined in <SQUORE_HOME>/configuration/models/Shared/data_provider/squan_sources/artefact_types.xml so you can include them easily in your model. Here is a selection of the most common ones:

<ArtefactType id="CODE" heirs="PACKAGES;FILES;CLASSES;MODULES;CODE_SPECIFICATIONS" />
<ArtefactType id="PACKAGES" heirs="APPLICATION;SUB_APPLICATION;SOURCE_CODE;FOLDER" />
<ArtefactType id="FILES" heirs="FILE;HEADER" />
<ArtefactType id="SUB_FILES" heirs="CLASSES;MODULES;CODE_SPECIFICATIONS" />
<ArtefactType id="CLASSES" heirs="CLASS;FORTRAN_MODULE;SQL_CLASS" />
<ArtefactType id="MODULES" heirs="FUNCTION" />
<ArtefactType id="CODE_SPECIFICATIONS" heirs="JAVA_INTERFACE;ADA_SPACK;ADA_STASK;ADA_SPROTOBJ;ADA_PROTOBJ;ABAP_CLASSDEF;VBNET_INTERFACE" />

You can define any artefact type in your model by declaring them in the artefactTypes attribute of your analysis model's RootIndicator , as shown below. The following definition of the ROOT main indicator declares the types APPLICATION, FILE, CLASS, FUNCTION, REQUIREMENT, TEST_PLAN, TEST_SUITE and TEST:

<RootIndicator artefactTypes="APPLICATION;FILE;CLASS;FUNCTION;REQUIREMENT;TEST_PLAN;TEST_SUITE;TEST" indicatorId="ROOT" />

In addition, you can define aliases to group types of artefacts together to use later when defining metrics in your analysis model. The ArtefactType definition below groups the artefacts defined above into CODE and DOCUMENT aliases:

<ArtefactType id="CODE" heirs="APPLICATION;FILE;CLASS;FUNCTION" />
<ArtefactType id="DOCUMENT" heirs="REQUIREMENT;TEST_PLAN;TEST_SUITE;TEST" />

This means that the long artefact declaration above can be rewritten as follows:

<RootIndicator artefactTypes="CODE;DOCUMENT" indicatorId="ROOT" />

You can also use the ArtefactType element with a manual attribute to declare that some artefacts can be added manually by the user, as shown below:

<ArtefactType id="TEST_SUITE" parents="APPLICATION;TEST_SUITE;TEST_PLAN" manual="true" />
<ArtefactType id="TEST" parents="TEST_SUITE" manual="true" />
<ArtefactType id="TEST_PLAN" parents="APPLICATION" manual="true" />
<ArtefactType id="REQUIREMENT" parents="APPLICATION" manual="true" />

Manual artefacts can be added by users with the required permissions via a context menu in the Artefact Tree

The Measure element defines the semantics of a single measure. From a technical standpoint, a measure is merely a mapping between the information provided by the Data Provider and known Squore elements.

Base Measures only define the measure name and identifier, whereas Derived Measures define how they are computed from other measures. A Measure without computation is a base measure. The following two examples show how the SLOC (Source Lines Of Code) base measure and the COMR (Comment Rate) derived measure are defined:

<Measure measureId="SLOC" targetArtefactTypes="APPLICATION;FILE" defaultValue="1" />
<Measure measureId="COMR" defaultValue="0">
	<Computation stored="true" targetArtefactTypes="APPLICATION;FOLDER;FILE;FUNCTION;CLASS;PROGRAM" result="(CLOC+MLOC)*100/(SLOC+CLOC)" />
</Measure>

The attributes allowed for the Measure element are as follows:

The attributes allowed for the Computation element are as follows:

The measure defined is then used with its identifier, prefixed with B. for base measures, or prefixed with D. for derived measures. The following example shows the use of a derived measure for a computation:

<Computation targetArtefactTypes="APPLICATION;FOLDER;FILE;CLASS;FUNCTION" result="(D.MET_OKR+D.RULE_OKR)/2" />

Rules are a specific type of measure. They do not return a numeric value like other measures, but the location within the source code where the rule was broken. Squore does not define any rule by itself, but requires a mapping between the rules defined in the external tools^[2] that provide the compliance measure and internal concepts (and properties files).

An example of rule definition is provided below:

<Measure measureId="R_NOGOTO" type="RULE" categories="SCALE_SEVERITY.REQUIRED;SCALE_PRIORITY.HIGH" families="REQUIRED;ANALYSABILITY;MISRA;CF;STRP" targetArtefactTypes="FUNCTION" defaultValue="0" />

The attributes allowed for the Measure element of type rule are as follows:

A simple way to override a rule that is defined somewhere in your model is to use an UpdateRules section in your Analysis bundle:

<UpdateRules>
	<UpdateRule measureId="R_NOGOTO" disabled="true" categories="SCALE_SEVERITY.CRITICAL"/>
</UpdateRules>

This syntax allows you to import a ruleset from the Shared folder and modify some of the rules if they do not fit your target model.

The UpdateRules element takes one or more UpdateRule elements where you need to define:

Scales define grades and boundaries for measures, in order to translate them into more understandable information. The ScaleLevel sub-element defines the ranges in the scale.

<Scale scaleId="SCALE_EC">
	<ScaleLevel levelId="UNKNOWN" bounds="];0["  rank="-1" />
	<ScaleLevel levelId="LEVELA" bounds="[0;0]"  rank="0" />
	<ScaleLevel levelId="LEVELB" bounds="]0;1]" rank="1" />
	<ScaleLevel levelId="LEVELC" bounds="]1;2]" rank="2" />
	<ScaleLevel levelId="LEVELD" bounds="]2;3]" rank="3" />
	<ScaleLevel levelId="LEVELE" bounds="]3;4]" rank="4" />
	<ScaleLevel levelId="LEVELF" bounds="]4;5]" rank="5" />
	<ScaleLevel levelId="LEVELG" bounds="]5;]"  rank="6" />
</Scale>

In this example, the scale SCALE_EC associates different levels to a measured value:

<Scale scaleId="SCALE_EC2">
	<ScaleLevel levelId="LEVEL_IN" bounds=" ]0;10[|]10;100[" rank="0"/>
	<ScaleLevel levelId="LEVEL_OUT" bounds="[10;10]" rank="1"/>
</Scale>

<Scale scaleId="SCALE_EC2">
	<ScaleLevel levelId="LEVEL_IN_LOW" bounds=" ]0;10[" rank="0"/>
	<ScaleLevel levelId="LEVEL_OUT" bounds="[10;10]" rank="1"/>
	<ScaleLevel levelId="LEVEL_IN_HIGH" bounds=" ]10;100[" rank="0"/>
</Scale>

Scales can be overridden for a specific artefact type, as shown below:

<Indicator indicatorId="VG" measureId="VG" scaleId="VG" targetArtefactTypes="CODE" />
<Scale scaleId="VG">
	<ScaleLevel levelId="UNKNOWN"	bounds="];0[" rank="-1" />
	<ScaleLevel levelId="GREEN"	bounds="[0;6]" rank="0" />
	<ScaleLevel levelId="YELLOW"	bounds="]6;10]" rank="1" />
	<ScaleLevel levelId="RED" bounds="]10;[" rank="2" />
</Scale>

<Scale scaleId="VG" targetArtefactTypes="COBOL_PROGRAM">
	<ScaleLevel levelId="UNKNOWN"	bounds="];0[" rank="-1" />
	<ScaleLevel levelId="GREEN"	bounds="[0;10]" rank="0" />
	<ScaleLevel levelId="YELLOW"	bounds="]10;20]" rank="1" />
	<ScaleLevel levelId="RED" bounds="]20;[" rank="2" />
</Scale>

The scale VG applies to all artefacts of type CODE, however, for artefacts of type COBOL_PROGRAM, the scale levels have different bounds than for other types (as specified via the targetArtefactTypes attribute).

You can use scale macros in order to avoid duplicating a scale and use parameters ({0}, {1}...) to define the scale level thresholds:

<ScaleMacro id="RGB">
	<ScaleLevel levelId="UNKNOWN"	bounds="];0[" rank="-1" />
	<ScaleLevel levelId="GREEN"	bounds="[0;{0}]" rank="0" />
	<ScaleLevel levelId="YELLOW"	bounds="]{0};{1}]" rank="1" />
	<ScaleLevel levelId="RED" bounds="]{1};[" rank="2" />
</ScaleMacro>

Scales defined by a macro and its parameters are then specified as shown below:

<Scale scaleId="VG" macro="RGB" vars="6;10" />
<Scale scaleId="VG_REVERSED" macro="RGB" vars="10;6" />

The Scale element accepts the following attributes:

Scale levels are defined using one or more ScaleLevel sub-elements, with the following attributes:

The levelIds are then mapped to their language-specific attributes in a properties file. For the previous example, the file PerformanceLevels_en.properties gives the following mapping:

LOP.LEVELA.MNEMO=A
LOP.LEVELA.NAME=Level A
LOP.LEVELA.COLOR=0,81,0
LOP.LEVELA.IMAGE=../Shared/Images/images/perfA.png
LOP.LEVELA.ICON=../Shared/Images/icons/perfA.png

The trend icons (new, improved, deteriorated and stable) that appear in the artefact tree and the dashboard tables can also be customised in a properties file as shown below:

EVO.TREE_NEW.ICON=Description/new.png
EVO.TREE_DOWN.ICON=Description/down.png
EVO.TREE_UP.ICON=Description/up.png
EVO.TREE_EQUAL.ICON=Description/equal.png

EVO.TABLE_NEW.ICON=Description/new.png
EVO.TABLE_DOWN.ICON=Description/down2.png
EVO.TABLE_UP.ICON=Description/up2.png
EVO.TABLE_EQUAL.ICON=Description/equal.png

Indicators associate a measure with a scale.

<Indicator indicatorId="ROKR_REQ" measureId="ROKR_REQ" scaleId="SCALE_DECILE" families="TAB" displayTypes="VALUE;LEVEL" />

The attributes allowed in the Indicator tag are the following:

<Indicator indicatorId="TEST_COVERAGE" />

Advanced Examples

An indicator must be specified as the root indicator for a each artefact type. The root indicator is the top-level mark displayed next to an artefact in the artefact tree.

<RootIndicator indicatorId="MAINTAINABILITY" artefactTypes="APPLICATION;FILE;FUNCTION" />

<Measure id="ROOT" targetArtefactTypes="TYPE" defaultValue="0" />

<Measure id="ROOT" targetArtefactTypes="TYPE" defaultValue="0">
	<Computation targetArtefactTypes="SOME_OTHER_TYPE" result="B.ROOT" />
</Measure>

In order to allow users to relax or exclude artefacts from the projects from the Artefact Tree, you need to reserve one measure that uses a special attribute used for relaxation and specify to which artefact types it applies.

The following is a basic example of how to allow users to relax folders and files in your model:

<!-- myModel/Analysis/Bundle.xml -->
<ArtefactType id="RELAXABLE" heirs="FOLDER;FILES" />
<Measure measureId="RELAX" targetArtefactTypes="RELAXABLE" defaultValue="0" usedForRelaxation="true" />

By adding these two lines in your model, you allow users whose role grant the View Drafts of Projects and Modify Artefacts privileges to use the relaxation mechanism. For more information about using artefact relaxation from the web UI, consult the Getting Started Guide or the online help.

Impact on computations

When an artefact is relaxed, its metrics are ignored when computing metrics for other artefacts. This makes sense for example when relaxing a folder full of third-party code, because you may not want the total number of software lines of code to include third-party code.

In other situations, it does not make sense to exclude all metrics from relaxed artefacts: If you are analysing components of a system and aggregate memory usage information up to the application level for example, third-party components for which you relax source code issues should still be part of the total memory usage for the system. In the latter case, you can use the continueOnRelaxed attribute to indicate that some or all measures should be included in computations even if the artefact has been relaxed. This is explained in the two examples below.

In the following code continueOnRelaxed is set to true for the metric used to mark artefacts as relaxed (usedForRelaxation ). As a result, all measures of the relaxed artefact are included in computations for other artefacts:

<ArtefactType id="RELAXABLE" heirs="FOLDER;FILES" />
<Measure measureId="RELAX" targetArtefactTypes="RELAXABLE" usedForRelaxation="true" continueOnRelaxed="true" defaultValue="0" />

In the following code, continueOnRelaxed is set to true at computation-level. As a result, the measure MEMORY is included in computations even when the artefact is relaxed. No other measures are included in computations for relaxed artefacts, since continueOnRelaxed is omitted from the definition of RELAX:

<ArtefactType id="RELAXABLE" heirs="FOLDER;FILES" />
<Measure measureId="RELAX" targetArtefactTypes="RELAXABLE" usedForRelaxation="true" defaultValue="0" />
<Measure measureId="MEMORY" defaultValue="0">  
	<Computation targetArtefactTypes="APPLICATION;FODLER" result="SUM FILE.MEMORY FROM DESCENDANTS" continueOnRelaxed="true"/>
</Measure>

Only artefacts of type FOLDER and FILES should be relaxable. If you need to find out if an artefact is relaxed in your model, you can use the IS_RELAXED_ARTEFACT() function described in the section called “Conditional and Level-Related Functions”.

Squore allows you to define links between artefacts. The links are generally created by Data Providers in your model (see the section called “Creating your own Data Providers and Repository Connectors”), and are displayed automatically in tables on the dashboard, as shown below:

Links to related requirements and tests in the scorecard of a requirement

Links in the scorecard can be clicked to navigate to the target artefact directly.

Basic links are declared in the analysis model using a Links element, which accepts the following attributes:

The links shown in the picture above can be defined as follows:

<Link id="TEST" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="TEST_CASE" />
<Link id="RELATED_REQ" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="REQUIREMENT" />

You can also create advanced links in your analysis model by declaring computed links,. Computed links allow you to add conditions to the source and destination artefacts and create links that follow artefacts recursively, which are a great way to implement traceability between artefacts. Here are a few examples of computed links:

A ComputedLink always has a starting point defined with a StartPath element and one or more optional NextPath elements designed to keep following links as needed.

The full syntax for ComputedLink is as follows:

The full syntax for StartPath and NextPath is as follows:

Constants are used to resolve a symbol to a number. They are defined with the Constant XML tag.

<Constant id="HIS_MET" value="12" />

Two attributes are required to define a constant:

A constant can then be used in a computation by prefixing it with C., e.g.:

<Computation targetArtefactTypes="APPLICATION;FOLDER;FILE;CLASS;FUNCTION" result="100*(1-(MET_KO/C.HIS_MET))" />

A constant can also be used in a scale level. Note that in this kind of usage, the constant ID does note require a prefix, as shown below:

<ScaleLevel levelId="LEVELG" bounds="]5;]" rank="HIS_MET" />

Dynamic scales are scales whose levels use measures instead of absolute bounds. They are useful when one metric has a different meaning according to the context in which it is read. In software development for example, you may accept a certain amount of specification changes at one stage of the process, but completely want to prohibit it at another stage. This section takes you through an example that can be implemented easily in your model with the use of dynamic scales.

What we want to guarantee with our dynamic scale, is that during three different phases of development, our requirements stability indicator is evaluated differently, as represented below:

Requirement Stability by Development Phase.

The following is an example of a dynamic scale definition for a KPI that evaluates the stability of requirements as excellent, fine, worrying, critical or unknown:

<Scale scaleId="DYN_SCALE_REQ_STABILITY" isDynamic="true">
	<ScaleLevel levelId="DYN_EXCELLENT" bounds="[APP(EXCELLENT_THRESHOLD);["  rank="0" />
	<ScaleLevel levelId="DYN_FINE" bounds="[APP(FINE_THRESHOLD);APP(EXCELLENT_THRESHOLD)[" rank="1" />
	<ScaleLevel levelId="DYN_WORRYING" bounds="[APP(WORRYING_THRESHOLD);APP(FINE_THRESHOLD)[" rank="2" />
	<ScaleLevel levelId="DYN_CRITICAL" bounds="[APP(CRITICAL_THRESHOLD);APP(WORRYING_THRESHOLD)[" rank="3" />
	<ScaleLevel levelId="DYN_UNKNOWN" bounds="];APP(CRITICAL_THRESHOLD)[" rank="4" />
</Scale>

Compared with the examples of scales shown in the section called “Scales”, note the use of the isDynamic attribute and how the bounds are expressed with measures instead of actual values.

The threshold measures can vary for each analysis and/or for each artefact type, and the scale may therefore be different as time goes by. There are two ways they could be set:

Here is an example setting the thresholds according to a PHASE attribute set by the user before running an analysis (more information about attributes is available in the section called “Attributes”:

<!-- Attribute Definition in Wizard -->
<tag type="multipleChoice" name="Development Phase: " measureId="PHASE" defaultValue="SPECIFICATION" displayType="radioButton" targetArtefactTypes="APPLICATION">
	<value key="SPECIFICATION" value="1" />
	<value key="PROTOTYPING" value="2" />
	<value key="IMPLEMENTATION" value="3" />
</tag>

<!-- Metrics Definition in Analysis Model -->
<Measure measureId="PHASE" targetArtefactTypes="APPLICATION" defaultValue="0" />
<Constant id="PHASE_SPECIFICATION" value="1" />
<Constant id="PHASE_PROTOTYPING" value="2" />
<Constant id="PHASE_IMPLEMENTATION" value="3" />

<!-- Thresholds Computation in Analysis Model -->
<Measure measureId="EXCELLENT_THRESHOLD">
	<Computation targetArtefactTypes="APPLICATION" 
		result="CASE(PHASE,
		C.PHASE_SPECIFICATION:60,
		C.PHASE_PROTOTYPING:95,
		C.PHASE_IMPLEMENTATION:100,
		DEFAULT:-1)"/>
</Measure>
<Measure measureId="FINE_THRESHOLD">
	<Computation targetArtefactTypes="APPLICATION" 
		result="CASE(PHASE,
		C.PHASE_SPECIFICATION:30,
		C.PHASE_PROTOTYPING:80,
		C.PHASE_IMPLEMENTATION:99,
		DEFAULT:-1)"/>
</Measure>
<Measure measureId="WORRYING_THRESHOLD">
	<Computation targetArtefactTypes="APPLICATION" 
		result="CASE(PHASE,
		C.PHASE_SPECIFICATION:10,
		C.PHASE_PROTOTYPING:40,
		C.PHASE_IMPLEMENTATION:95,
		DEFAULT:-1)"/>
</Measure>
<Measure measureId="CRITICAL_THRESHOLD">
	<Computation targetArtefactTypes="APPLICATION"
		result="CASE(PHASE,
		C.PHASE_SPECIFICATION:0,
		C.PHASE_PROTOTYPING:20,
		C.PHASE_IMPLEMENTATION:90,
		DEFAULT:-1)"/>
</Measure>

The final REQUIREMENTS_STABILITY indicator is associated with a static scale that uses the same ranks as the dynamic one, and its value is assigned by retrieving the desired rank from the dynamic scale using the FIND_RANK() function:

<!-- Static scale to base the KPI on -->
<Scale scaleId="SCALE_REQ_STABILITY">
	<ScaleLevel levelId="EXCELLENT" bounds="[0;0]"  rank="0" />
	<ScaleLevel levelId="FINE" bounds="[1;1]" rank="1" />
	<ScaleLevel levelId="WORRYING" bounds="[2;2]" rank="2" />
	<ScaleLevel levelId="CRITICAL" bounds="[3;3]" rank="3" />
	<ScaleLevel levelId="UNKNOWN" bounds="[4;4]" rank="4" />
</Scale>

<!-- Indicator definition -->
<Indicator indicatorId="REQUIREMENTS_STABILITY" measureId="REQ_STABILITY_RANK" targetArtefactTypes="APPLICATION;FOLDER;FILE" scaleId="SCALE_REQ_STABILITY" />

<!-- The base measure that holds the actual raw value of Requirement Stability -->
<Measure measureId="REQUIREMENTS_STABILITY_METRIC" targetArtefactTypes="APPLICATION;FOLDER;FILE" defaultValue="0" />

<!-- A temporary measure to compute the rank of the metric on the dynamic scale -->
<Measure measureId="REQ_STABILITY_RANK">
	<Computation stored="false" targetArtefactTypes="APPLICATION;FOLDER;FILE" result="FIND_RANK(DYN_SCALE_REQ_STABILITY, REQUIREMENTS_STABILITY_METRIC)" />
</Measure>

For more information about the FIND_RANK() function, refer to the section called “Functions”.

A Decision Model defines how to build an Action Plan in Squore. The list of action items triggered during an analysis defines the to-do list that can be followed to improve the quality of a project.

There are two types of decision models available in Squore:

The easiest way to instruct Squore to build a dynamic action plan for your model based on the findings generated during an analysis is to ensure that your model folder contains no Decision/Bundle.xml file. A list of the Top 40 valuable actions will be created for the project. This list is shown to all users in the Action Items tab of the Explorer.

Part of the Top 40 valuable actions dynamically generated for a source code project

By default, action items are created based on findings in the project using these criteria:

This can be specified in your Bundle.xml as follows:

$SQUORE_HOME/configuration/MyModelFolder/Decision/Bundle.xml:
<Bundle>
	<FindingsActionPlan limit="40">
		<CategoryCriterion type="COST" scaleId="SCALE_REMEDIATION" preferenceLevel="MEDIUM" excludeLevels="UNKNOWN;NONE" />
		<CategoryCriterion type="BENEFIT" scaleId="SCALE_SEVERITY" preferenceLevel="MEDIUM" excludeLevels="UNKNOWN;INFORMATION" />
		<OccurrencesCriterion type="COST" preferenceLevel="MEDIUM" />
	</FindingsActionPlan>
</Bundle>

Dynamic Action Plan Syntax

The FindingsActionPlan element accepts the following attributes:

There are three types of criteria that you can use to prioritise findings:

Each type of criterion accepts the following attributes:

Here is an example that expands on the default shown earlier to take into account the test coverage of artefacts and make sure that action items are generated mostly for artefacts with a high test coverage ratio. The scale used as well only contains five levels from P1 to P5 and will single out very high and very log priority items (the relevancy of an action item is a number between 0 and 100 that is measured against this scale to define the priority):

$SQUORE_HOME/configuration/MyModelFolder/Decision/Bundle.xml:
<Bundle>
	<FindingsActionPlan limit="40" priorityScaleId="SCALE_LEVEL_FIVE">
		<CategoryCriterion type="COST" scaleId="SCALE_REMEDIATION" preferenceLevel="MEDIUM" excludeLevels="UNKNOWN;NONE" />
		<CategoryCriterion type="BENEFIT" scaleId="SCALE_SEVERITY" preferenceLevel="MEDIUM" excludeLevels="UNKNOWN;INFORMATION" />
		<OccurrencesCriterion type="COST" preferenceLevel="MEDIUM" />
		<VariableCriterion type="BENEFIT" preferenceLevel="VERY_HIGH" indicatorId="TEST_COVERAGE" />
  </FindingsActionPlan>
<Bundle>

Where SCALE_LEVEL_FIVE is:
<Scale scaleId="SCALE_LEVEL_FIVE">
	<ScaleLevel levelId="P0" bounds="[0;5]" rank="0" />
	<ScaleLevel levelId="P1" bounds="]5;15]" rank="1" />
	<ScaleLevel levelId="P2" bounds="]15;65]" rank="2" />
	<ScaleLevel levelId="P3" bounds="]65;85]" rank="3" />
	<ScaleLevel levelId="P4" bounds="]85;95]" rank="4" />
	<ScaleLevel levelId="P5" bounds="]95;100]" rank="5" />
</Scale>

If you want to use a combination of metrics to trigger action plans instead of relying on prioritising findings, Squore allows building your own specification of triggers for action items. The following is an example of a Decision Bundle where an action item is based on specific triggers:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Bundle>
	<DecisionCriteria>
		<DecisionCriterion dcId="DR_FU_UNTESTABLE" categories="SCALE_PRIORITY.MEDIUM" roles="DEVELOPER;PROJECT_MANAGER" targetArtefactTypes="FUNCTION">
			<Triggers>
				<Trigger>
					<Test expr="IS_CRITICAL_COMPONENT" />
					<Test expr="VG" bounds="[20;[" descrId="UNTESTABLE_VG" p0="#{MEASURE.VG}" />
					<Test expr="NEST" bounds="[4;[" descrId="UNTESTABLE_NEST" p0="#{MEASURE.NEST}" />
					<Test expr="NPAT" bounds="[800;[" descrId="UNTESTABLE_NPAT" p0="#{MEASURE.NPAT}" />
				</Trigger>
				<Trigger>
					<Test expr="VG" bounds="[50;[" descrId="UNTESTABLE_VG" p0="#{MEASURE.VG}" />
				</Trigger>
			</Triggers>
		</DecisionCriterion>
	</DecisionCriteria>
</Bundle>

A DecisionCriterion is an action item definition. At least one Trigger must be true to trigger the automatic generation of an action item on an artefact whose type is defined in the targetArtefactTypes attribute of a DecisionCriterion . A trigger is true when all its tests evaluate to true.

Writing a Test

Writing a test, requires using the mandatory expr attribute, which is the expression being tested for, in the form of a computation. See Chapter 5, Expression Syntax for more details about the syntax to use.

The following optional attributes may also be used:

Queries allow performing calculations on a set of values, optionally applying some conditions.

You can think of a query as an structured statement similar to:

[COMPUTE_VALUE] FROM [SCOPE] WHERE [CONDITION]

where [SCOPE] is one of:

and [CONDITION] can use the following operators (with some exceptions where specified):

In this section, you will learn how to compute values, define a scope and write conditions for your queries following the syntax supported in Squore to:

COUNT PROGRAM FROM DESCENDANTS WHERE LEVEL=LEVELG

COUNT FILE FROM DESCENDANTS WHERE LEVEL!=LEVELC OR LEVEL!=UNKNOWN AND B.LC>10

COUNT FILE FROM DESCENDANTS WHERE LC
=> is shorthand for
COUNT FILE FROM DESCENDANTS WHERE LC >=1

COUNT ISSUE FROM TREE WHERE EQUALS(INFO('STATUS'), 'FIXED') AND DATE_SUBMITTED >= TODAY() - DAYS(60)

SUM|MAX|MIN|MUL|AVR <ArtefactType|ALL>.<MeasureId>