Highlights

The Highlights tab in Squore’s Explorer is a flat list of artefacts in predefined categories for a model. These categories are defined in your model by including content in the highlights Bundle.xml file for your model. In this chapter, you will learn to understand the default highlights in the default models and will be able to consult the full reference for formatting a highlights bundle.

The default highlights bundle looks similar to this:

<Bundle>
	<TopArtefacts id="TOP_10_MOST_CHANGED_ARTEFACTS" onArtefactTypes="PACKAGES" measureId="SI" order="ASC" resultSize="10">
			<where>
				<measure id="SI" bounds="[0;1[" />
			</where>
			<Column measureId="SI" suffix="%" />
			<Column measureId="LC" />
	</TopArtefacts>
	<TopArtefacts id="TOP_10_WORST_ARTEFACTS" order="DESC" resultSize="10" roles="PROJECT_MANAGER"/>
	<TopDeltaArtefacts id="TOP_10_MOST_DETERIORATED_ARTEFACTS" order="DESC" resultSize="10"/>
	<TopNewArtefacts id="ALL_NEW_ARTEFACTS" order="DESC" resultSize="*"/>
</Bundle>

Highlight definitions from the Bundle display in the Highlights tab of the Explorer in Squore:

CFG highlights
Figure 1. The Highlights tab of the Explorer

Highlight definitions can be created directly in the web interface and can be shared between users and projects. You only need to learn about the syntax of the Highlights bundle if you want to customise the list of default highlights or make new ones available by default in your configuration.

The XML Schema for the highlights bundle is described in highlights.xsd.

Definition types

The Bundle element accepts the following sub-elements:

  • Role (optional, deprecated) allows grouping several highlight definitions for a particular role. This element should be replaced with a roles attribute in each highlight definition instead.

    Role has a mandatory name attribute where you can specify a role ID.

  • Filters (optional, deprecated) allows grouping several highlight definitions for a particular artefact type. This element should be replaced with a onArtefactTypes attribute in each highlight definition instead.

    Filters has a mandatory type attribute where you can specify an artefact type

  • TopArtefacts is a type of highlight definition used to retrieve artefacts with the biggest value for a given measure.

  • TopDeltaArtefacts is a type of highlight definition used to retrieve artefacts with the biggest variation in the value of a given measure since an earlier version.

  • TopNewArtefacts is a type of highlight definition used retrieve artefacts that are new in the current version, sorted according to the value of a given measure.

Common Attributes

The common attributes for all highlight definitions types are as follows:

  • id (mandatory) is the id of the highlight definition.

  • 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.

  • artefactTypes (optional, default: any) defines the types of artefacts to filter on.

  • excludingTypes (optional, default: none) lists the artefact types for which the metric should not be displayed. This allows refining the types provided in the main filter above.

  • linkType allows to filter artefacts linked to the current artefact according to their link type. For more information about links, refer to Artefact Links.

  • linkDirection (optional, default: OUT) is used to specify the link direction to consider. Accepted values are:

    • OUT to consider links from the current artefact towards other artefacts

    • IN to consider links from other artefacts towards the current artefact

  • onlyDirectChildren (optional, default: false) includes artefacts that are direct children of the current artefact when set to true. Or all descendants of the current artefact when set to false. (Only available if linkType is not defined).

  • measureId (optional, default: the measureId associated with the root indicator) is the name of the measure Id to filter on.

  • order (optional, default: ASC) is the sort order for the list according to the reference measure ID. Valid values are ASC and DESC.

  • altMeasureId (optional, default: empty) is the second measure ID to use for sorting.

  • altOrder (required if altMeasureId is set, default: empty) is the sort order for the second measure ID. Valid values are ASC and DESC.

  • resultSize (mandatory) is the number of results to include in the list. Use 10 to display 10 artefacts or * to display all artefacts.

  • hidePath (optional, default: false) Allows the user to hide the artefact path.

  • hideRating (optional, default: false) Allows the user to hide the artefact rating.

Output Customisation

All highlight definitions support the following nested elements, to customise the output:

  • where is used to specify extra filtering conditions for the artefacts to return.

  • Column is used to add a column to the list of artefacts returned by the highlight definition.

  • OrderBy is used to specify sorting directives, in addition to the one already specified in the highlight definition.

where

The where clause allows you to filter out unwanted artefacts by indicator, measure or info.

<Bundle>
	<TopArtefacts id="TOP_10_MOST_CHANGED_ARTEFACTS" onArtefactTypes="PACKAGES" measureId="SI" order="ASC" resultSize="10">
			<where>
				<measure id="SI" bounds="[0;1[" />
			</where>
	</TopArtefacts>
	<TopArtefacts id="OPEN_TICKETS_DEV_RECENT" onArtefactTypes="TICKET_FOLDER" measureId="STATUS" order="ASC" resultSize="*">
			<where>
				<indicator id="STATUS" levels="CLOSED" invert="true" />
				<info id="I_PROJECT" values="Development" />
				<measure id="AGE" bounds="[0;7]" />
			</where>
	</TopArtefacts>
</Bundle>

The where element accepts the following sub-elements:

  • measure to filter based on a measure. Following attributes are supported:

    • id (mandatory) is the entity identifier in the analysis model

    • values|bounds (mandatory) is respectively, a semicolon-separated list of values or an interval, to test for the specified metric

    • invert (optional, default: false) allows checking for the invert of a condition when set to true

  • indicator to filter based on an indicator. Following attributes are supported:

    • id (mandatory) is the entity identifier in the analysis model

    • levels (mandatory) is a semicolon-separated list of scale levels to test for the specified metric

    • invert (optional, default: false) allows checking for the invert of a condition when set to true

  • info to filter based on an information. Following attributes are supported:

    • id (mandatory) is the entity identifier in the analysis model

    • values|patterns (mandatory) is a semicolon-separated list of respectively, values or wildcard patterns, to test for the specified metric

    • invert (optional, default: false) allows checking for the invert of a condition when set to true

Column

The Column allows the following attributes:

  • measureId, indicatorId or infoId (mandatory) is the ID of the measure, indicator or textual information to display.

  • artefactTypes (optional, default: the parent value of artefactTypes) lists the artefact types for which the metric should be displayed. This allows refining the types provided in the main filter above.

  • excludingTypes (optional, default: the parent value of excludingTypes) lists the artefact types for which the metric should not be displayed. This allows refining the types provided in the main filter above.

  • labelType (optional, default: NAME) defines how the metric is shown in the interface. Supported values are:

    • NAME

    • MNEMONIC

    • DESCRIPTION

    • CUSTOM which accepts the following additional attribute when defined:

      • label to define the string that must be displayed.

  • displayType (optional, default: VALUE) sets the value display type. The supported values are:

    • VALUE for the metric numeric value

    • RANK for the indicator rank

    • ICON for the indicator rank icon

    • NAME for the indicator level name

    • MNEMONIC for the indicator level mnemonic

    • DATE for the metric value, displayed as a UTC date

    • DATETIME for the metric value, displayed as a UTC date and time

    • TIME for the metric value, displayed as a UTC time

    For DATE, DATETIME and TIME, you can specify the required format using the dateStyle, timeStyle and datePattern attributes described below.

  • decimals (optional, default: 2) sets the number of decimals, used when the displayType is VALUE.

  • dateStyle (optional, default: DEFAULT) : the date formatting style, used when the displayType is one of DATE or DATETIME.

    • SHORT is completely numeric, such as 12.13.52 or 3:30pm.

    • MEDIUM is longer, such as Jan 12, 1952.

    • DEFAULT is MEDIUM.

    • LONG is longer, such as January 12, 1952 or 3:30:32pm.

    • FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.

  • timeStyle (optional, default: DEFAULT): the time formatting style, used when the displayType is one of DATETIME or TIME. See above for available styles.

  • datePattern (formerly dateFormat) (optional, default: empty) : the date pattern, used when the displayType is one of DATE, DATETIME or TIME.

    • "yyyy.MM.dd G 'at' HH:mm:ss z" is "2001.07.04 AD at 12:08:56 PDT".

    • "EEE, d MMM yyyy HH:mm:ss Z" is "Wed, 4 Jul 2001 12:08:56 -0700".

      If this attribute is set, both dateStyle and timeStyle attributes are ignored. The date is formatted using the supplied pattern. Any format compatible with the Java Simple Date Format can be used. Refer to http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html for more information.

  • suffix (optional, default: empty) is the label displayed after the value of the metric in the UI

  • useBackgroundColor(optional, default: false) allows you to use the indicator level as the background colour of the cell. This is only valid when using a column with indicatorId. You can also control the transparency of the background colour with the attribute alpha (optional, default: 100) which accepts a value between 0 (transparent) and 255 (opaque).

  • showTrend(optional, default: false) allows you to view the trend values and icons for each cell of a highlighted artefact.

Either measureId, infoId or indicatorId is required. Note that all display related tags, except labelType and displayType are ignored when infoId is used.

OrderBy

OrderBy allows the following attributes:

  • measureId (mandatory) is the ID of the measure

  • order (mandatory) is the sort order for measure. Supported values are:

    • ASC for ascending

    • DESC for descending