User Interface Options

Some configuration options are also available to tweak the Squore user interface. These options need to be specified in a file called properties.xml located at the root of your Configuration folder, or in various other Bundle.xml files. This chapter describes these options and their effect on the user interface.

You can find the XML schema for properties.xml in properties-1.2.xsd.

Hiding Explorer tabs

By default, the Explorer shows the following tabs for all users:

CFG explorerTabs
Figure 1. The default set of tabs in the Explorer. The tab displayed by default is the Dashboard tab.

Users can change the displayed tabs by clicking the Tab Manager icon right of the last tab. You can also define the available tabs and their default state (shown, hidden, default) by editing properties.xml as shown below:

<!-- Active tabs -->
<explorerTabs>
	<tab name="dashboard" default="true"/>
	<tab name="action-items" mandatory="true"/>
	<tab name="highlights"/>
	<tab name="findings"/>
	<tab name="documents" rendered="false"/>
	<tab name="attributes"/>
	<tab name="indicators" rendered="false"/>
	<tab name="measures" rendered="false"/>
	<tab name="annotations"/>
</explorerTabs>

Each tab element accepts the following parameters:

  • name (mandatory) identifies the tab of the Explorer by name. The supported values are:

    • dashboard

    • action-items

    • highlights

    • findings

    • documents

    • attributes

    • indicators

    • measures

    • annotations

  • mandatory (optional, default: false) removes the option to hide the tab from the web UI for all users.

  • default (optional, default: false) makes the tab the default tab in Squore. Every link to a project or artefact that does not specifically request a target tab will open the Explorer with this tab active by default. Note that when set to true, the tab is automatically mandatory as well.

  • rendered (optional, default: true) specifies whether the tab is shown (true) or hidden (false) by default. Hidden tabs can be shown by checking a box in the Tab Manager. Note that the value of this attribute is ignored if either default or mandatory is set to true.

The tabs definitions order (top to bottom) will define the display order in Explorer page (left to right).

Customising the Help menu

You can use the help option to add links that will appear in the Help menu in Squore (? in the main toolbar), as shown below.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Bundle>
	<!-- Customise the help links that appear in the right menu -->
	<help label="OWASP 25" url="http://cwe.mitre.org/top25/" />
	<help label="JBoss Wiki" url="http://www.jboss.org/jbosswiki" roles="ADMINISTRATOR;" />
</Bundle>

The help element accepts the following attributes:

  • label (mandatory) is the label for the link in the help menu.

  • url (mandatory) is the URL to link to.

  • roles (optional) is a list of global roles that are allowed to see the link. If not specified, then the link is displayed for all logged-in users.

CFG customHelp
Figure 2. A customised Help menu for a user with the global role ADMINISTRATOR

Hiding specific models

If you wish to hide some of the available models in Squore, you can use the hideModel option to prevent some folders under the models folder in the configuration from being read by Squore, as shown below.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Bundle>
	<!-- Hidden models -->
	<hideModel name="ISO9126_Maintainability_Xaml" />
</Bundle>

The hideModel element accepts only one attribute:

  • name (mandatory) is the name of the folder to exclude from the configuration.

Hiding specific measures

If it does not make sense to display a specific measure in the Indicator Tree or the Model Viewer, you can hide it by editing the Properties bundle of a model. This is useful to remove confusion about how a measure is computed.

In order to hide a measure:

  1. Edit the model’s Properties/Bundle.xml.

  2. Add a <hideMeasure targetArtefactTypes="" path="" > element.

  3. Fill in the artefact types for which this measure is hidden (this is optional).

  4. Specify the complete path of the measure to be hidden.

Below is an example of two hidden paths. The first one is only hidden at application level. The second one is always hidden.

configuration/models/[ModelFolder]/Properties/Bundle.xml
<bundle>
	<!-- Hidden measures -->
	<hideMeasure targetArtefactTypes="APPLICATION" path="I.MAINTAINABILITY/I.ANALYSABILITY/I.FUANA_IDX" />
	<hideMeasure path="I.MAINTAINABILITY/I.CHANGEABILITY/I.ROKR_CHAN/D.RKO_CHAN" />
</bundle>

Note that you should always use the precise notation path elements, with the I., B. or D. to avoid ambiguities.

Tweaking the Ruleset Editor screen

Using the Properties bundle, you can define the list of categories available for edition in the Ruleset Editor. By default, all categories can be edited, but the rulesEdition element allows you to explicitly limit the list to specific categories.

configuration/models/[ModelFolder]/Properties/Bundle.xml
<bundle>
	<rulesEdition scales="CUSTOMER_SEVERITY;CUSTOMER_REMEDIATION;SCALE_SCHEDULE" />
</bundle>

The rulesEdition element takes a scale attribute that accepts a semicolon-separated list of scales to display for each rule in the Ruleset Editor for this model.

Configuring Action Items and Findings tabs

Configuring sorting order

You can define for each model the order that is used to sort items in the Action Items and Findings pages. This is done by defining one or more scales and adding them to the Properties/Bundle.xml file using the findingsTab and actionItemsTab options, as shown below:

configuration/models/[ModelFolder]/Properties/Bundle.xml
<bundle>
	<!-- sort order for columns -->
	<findingsTab orderBy="SCALE_PRIORITY;SCALE_SEVERITY" />
	<actionItemsTab orderBy="SCALE_REMEDIATION;SCALE_SEVERITY" />
</bundle>

Hiding columns

You can define for each model the columns that should be hidden in the Action Items and Findings pages. This is done by defining one or more scales and adding them to the Properties/Bundle.xml file using the findingsTab and actionItemsTab options, as shown below:

configuration/models/[ModelFolder]/Properties/Bundle.xml
<bundle>
	<!-- sort order for columns -->
	<findingsTab hideColumns="SCALE_PRIORITY;SCALE_SEVERITY" />
	<actionItemsTab hideColumns="SCALE_REMEDIATION;SCALE_SEVERITY" />
</bundle>

On the Findings tab, you can also hide the Characteristics column with the hideCharacteristicsFilter attribute:

configuration/models/[ModelFolder]/Properties/Bundle.xml
<bundle>
	<!-- hide characteristics column (list of families) -->
	<findingsTab hideCharacteristicsFilter="true" />
</bundle>

In models that integrate requirements, test cases or change requests as artefacts, it may be necessary to provide a link to view an artefact in the context of the application where it was created. This can be done in Squore by configuring the View Source link in the Dashboard to open links in an external applications. This section shows how you can configure external links using Jira as the target application.

Our model collects Jira issues and shows a minimal dashboard or the issue’s status, assignee, priority, summary and description, as shown below:

CFG external links
Figure 3. Dashboard containing Jira issues

The Jira issue shown above is an artefact of type NEW_FEATURE. In order to make the View Source link open the Jira issue in a browser, you simply need to create a properties file in the sources folder of your configuration, whose name is the artefact type in lower case.

<my_configuration_folder>/sources/new_feature.properties:
type=url
pattern=https://github.com/squoregit/earthRepo/issues/{0}
pattern.findings=https://github.com/squoregit/earthRepo/issues/browse/{0}/activity?from={1}
p0=INFO(ISSUE_ID)
p1=INFO(ASSIGNEE)

The syntax of this properties file is as follows:

  • type is the type of link to create. Only url is currently supported.

  • pattern is the URL pattern used to generate a link for the View Source link in the Dashboard. You are free to insert parameters in the URL as needed, as long as you declare them in the properties file.

  • pattern.findings is the URL pattern used to generate a link for artefacts on the Findings tab. This pattern also supports parameters.

  • p0, p1…​ pn are parameters that accept a computation that will return a string for the artefact. In the example above, ISSUE_ID and ASSIGNEE are two text metrics that exist for the NEW_FEATURE artefact type.

    You can use the following computations:

    • INFO(measureId) to retrieve textual information from the current artefact.

    • ARTEFACT_LOCATION() to retrieve the location of an artefact within a file. For example, it will return 5 for a function artefact that starts at line 5 of its parent file artefact.

    • FINDING_LOCATION() to retrieve the precise location of the finding within the artefact. For example, it will return 2 if the finding is located on the second line of a function artefact (no matter where in the file the function artefact is located).

Enabling model/group rating in Project Portfolios

It is possible to display the models and groups of project rating in the Project Portfolios:

CFG model rating
Figure 4. Models and groups rating in Project Portfolios

To do so, just add the following line in the "Properties/Bundle.xml" file of your model:

<bundle xmlns:xi="http://www.w3.org/2001/XInclude" >
    <scoreGroups indicatorId="LEVEL" aggregationType="AVG" />
</bundle>

The scoreGroups element accepts the following attributes :

  • indicatorId (optional, default: LEVEL) is the indicator to use to rate the project group.

  • aggregationType (optional, default: AVG) is the aggregation method used to compute the indicator level. The supported values allowed are:

    • MIN: minimal value

    • MAX: maximal value

    • OCC: number of data points

    • AVG: average value

    • DEV: standard deviation

    • SUM: sum of values

    • MED: median value

    • MOD: modal value

When rating models/groups is disabled, you can use a group icon instead by defining it in the properties.