Artefact Dashboards

Dashboards for artefacts consist of three areas:

The scorecard area (green)
The tables area (blue)
The charts area (orange).

Figure 1. The Squore Artefact Dashboard Areas

When clicking on a group/model node in the Project Portfolios, a special dashboard is used: Model/Group Dashboard.

The targeted artefacts types are specified in the dashboard definition. The number of columns used in the charts area and the default width and height of charts as well. Here is a dashboard definition example:

<dashboard type="APPLICATION" nbColumns="4" defaultWidthValue="500" defaultHeightValue="500" >
	<scorecard> ... </scorecard>
	<tables> ... </tables>
	<charts> ... </charts>
</dashboard>

The dashboardelement supports the following sub-elements:

scorecard specifies the scorecard part to be displayed to the left part of the dashboard (green).
tables specifies the tables to be displayed at the top of the dashboard (blue).
charts specifies the charts to be displayed on the (bottom) right of the dashboard (orange).

The dashboard element supports the following attributes:

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.
nbColumns (optional, default: 3) sets the number of columns used to display the charts on the dashboard.
defaultWidthValue (optional, default: 400) sets the default width of a maximised chart if not specified within the chart itself.
defaultHeightValue (optional, default: 400) sets the default height of a maximised chart if not specified within the chart itself.
topTablesMaxLines (optional, default: 8) defines the maximum number of lines in the tables displayed in the top row above the charts.
rowMaxHeight (optional, default: 250) define the maximum height in pixels of a row of charts on the dashboard.
template (optional, default: 1x1 for all charts) allows changing the aspect ratio of charts in the dashboard, using the syntax "position:width x height;". Note that the use of this attribute requires defining a value for the nbColumns attribute. For more details about dashboard templates, refer to Dashboard templates.
minSizeForLegend (optional, default: no legends on thumbnails) allows displaying chart legends on the thumbnails for charts whose ratio is above the specified minimum. By default, no chart legends are displayed on thumbnails. If you want to force the legend to be displayed on thumbnails, specify for what chart ratio the thumbnail will be generated. Charts have a ratio of 1x1 by default, so specify minSizeForLegend="1x1" to force legends for all charts. If you want to display legends for all charts that have a width that is twice their height, specify minSizeForLegend="2x1".
name (deprecated) is unused.

If a chart has an attribute legend="false", then its legend will not be included on the thumbnail even if its ratio matches the one specified in minSizeForLegend.

Scorecard area

The scorecard area allows displaying a unique chart, usually the artefact KPI, and a set of tables.

Each table has its own set of lines with various information. The structure used to define the scorecard is shown below:

<scorecard>
	<chart ... />
	<tables>
		<table id="DECISION_MAKING" opened="true">
			<line indicatorId="BUSINESS_VALUE" displayType="NAME" decimals="0" suffix="FP" />
			...
		</table>
		...
	</tables>
</scorecard>

Key Performance Indicator (KPI)

Figure 2. Key Performance Indicator

For more information about how to insert a KPI into the scorecard, refer to Key Performance Indicator.

Scorecard tables

There may be any number of tables below the KPI chart, and there may be any number of lines in each table.

Figure 3. A scorecard information table using 3 tables with respectively 10, 7, and 4 lines

A scorecard table is defined using the following syntax:

<tables displayContext="false" hideLinks="ALL">
	<table name="My Table Name" id="TABLE_ID" opened="true">
		<line indicatorId="BUSINESS_VALUE" displayType="NAME" decimals="0" suffix="FP" emptyValue="-" exclude="TESTER" />
		<line indicatorId="QUALITY" displayType="NAME" decimals="1" suffix="%" />
		<line indicatorId="SI" displayType="NAME" decimals="1" suffix="%" />
	</table>
	<table id="TABLE_ID">
		...
	</table>
	...
</tables>

The tables element accepts the following attributes:

displayContext (optional, default: false) allows to automatically insert an Artefact context table containing the current artefact’s project, version and name, as shown below:

Figure 4. The artefact context table

The table name is not configurable.
hideLinks allows managing the display of the links tables in the scorecard. All links tables are shown by default. You can hide a table by setting the value of the attribute to <LinkType>#<direction>, where LinkType is the type of link between artefacts, and direction is a choice of OUT or IN, for example:
```
hideLinks="TEST_SPEC#OUT;TASK#IN"
```
If you want to hide all links tables in the scorecard, use hideLinks="ALL".

The name of the table can be configured using properties files, as explained in Properties files. If you need more control over where links tables are displayed in the scorecard, you can manually insert a links table using the linksTable element, described later in this section.

The table element accepts the following attributes:

id (mandatory) is used to find the localised version of the table name in a .properties file.
name (optional, default: empty) allows bypassing the search for a localised string
backgroundColor (optional, default: WHITE for charts, GREY for tables) allows specifying a background colour for a chart or a table. Working With Colours
backgroundColorFromIndicator (optional) allows making the background colour for a chart or a table dependent on an indicator level. The attribute takes an indicator Id (backgroundColorFromIndicator="ROOT"). The color will be the one defined in the indicator’s associated scale.
opened (optional, default: false) to specify whether the table is collapsed or un-collapsed by default.
displayType (optional, default: no default) defines the displayType to be used by all lines in this table. It can be overridden for each line if necessary.
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.

The line element accepts the following attributes:

measureId, indicatorId or infoId (mandatory) is the ID of the measure, indicator or textual information to display.
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.
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.
displayedValue (optional) allows overriding the indicator to display another measure instead. The attribute takes a measure ID (displayedValue="SLOC").
displayValueType (optional, default: VALUE) defines how the metric value is shown in the interface. It may be one of:
- NAME the level’s name
- MNEMONIC the level’s mnemonic
- RANK the level’s rank
- VALUE the measure’s value
- PERCENT to automatically convert a value between 0 and 1 into a percentage (also appending '%' as a suffix)
- ICON the level’s icon
- DATE the measure value converted to date format
- DATETIME the measure value converted to datetime format
- TIME the measure value converted to time format
- TEXT when the metric you are trying to display is textual information
  
  For DATE,DATETIME and TIME, you can specify the required format using the dateStyle, timeStyle and datePattern attributes described below.
unknownValue (optional, default: "?") defines what text to display if the level of the indicator is UNKNOWN or outside the specified dataBounds. Set this to OFF to use the old behaviour (which display the rank -1).
emptyValue (optional, default: "-") defines what text to display if there is no value in the database for the specified metric, or if a date is not specified. This is usually useful if a date has not been set yet manually in a form (and is therefore equal to 0), or if you have just added a new metric to your model you want to display specific text for the versions of your project where this metric did not exist yet.
dataBounds (optional, default:[;[) allows overriding the normal range of values that would trigger the display of the unknownValue text. This allows you to display the unknown value if the metric associated to the indicator is not within the defined bounds.
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
decimals (optional, default: 0) is the number of decimals places to be used for displaying values.
roundingMode (optional, default: HALF_EVEN) defines the behaviour used for rounding the numerical values displayed. The supported values are:
- CEILING to round towards positive infinity.
- DOWN to round towards zero.
- FLOOR to round towards negative infinity.
- HALF_DOWN to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round down.
- HALF_EVEN to round towards the "nearest neighbour" unless both neighbours are equidistant, in which case, round towards the even neighbour.
- HALF_UP to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round up.
- UP to round away from zero.
For more examples of rounding mode, consult http://docs.oracle.com/javase/8/docs/api/java/math/RoundingMode.html

External links in the lines of a table are generated automatically according to the metric that the line displays. They will generally link to the list of findings that are used to compute the metric. You can however override the URL and set your own external URL. In order to do this, ensure that the metric MY_METRIC displayed in a table line has a MY_METRIC.URL property defined in a properties file in your model. For more information about properties files, consult the Properties files section.

The linksTable element is used instead of table to insert a links table, and accepts the following attributes:

id (mandatory) is used to find the localised version of the table name in a .properties file.
types (mandatory) is the list of links type ids the table displays.
operation (optional, default: UNION) allows to define basic operation on result set (mathematical). Accepted values are:
- UNION
- INTERSECTION
- SYMMETRIC_DIFFERENCE
direction (optional, default: OUT) defines the direction of the links to display. Accepted values are:
- OUT to show outbound links
- IN to display inbound links

For more information about artefact links, consult Artefact Links.

Tables area

Tables are displayed at the top of the dashboard. They are defined via table sub-elements contained in a tables element, as follows:

<tables>
	<table id="TABLE_ID">
		<line measureId="MEASURE_ID_1" />
		<line measureId="MEASURE_ID_2" />
		<line measureId="MEASURE_ID_3" />
	</table>
	<table id="TABLE_ID_2">
		...
	</table>
</tables>

The table element accepts the following attributes:

id (mandatory) is used to find the localised version of the table name in a .properties file.
name (optional, default: empty) allows bypassing the search for a localised string
backgroundColor (optional, default: WHITE for charts, GREY for tables) allows specifying a background colour for a chart or a table. Working With Colours
backgroundColorFromIndicator (optional) allows making the background colour for a chart or a table dependent on an indicator level. The attribute takes an indicator Id (backgroundColorFromIndicator="ROOT"). The color will be the one defined in the indicator’s associated scale.
opened (optional, default: false) to specify whether the table is collapsed or un-collapsed by default.
displayType (optional, default: no default) defines the displayType to be used by all lines in this table. It can be overridden for each line if necessary.
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.

The line element accepts the following attributes:

measureId, indicatorId or infoId (mandatory) is the ID of the measure, indicator or textual information to display.
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.
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.
displayedValue (optional) allows overriding the indicator to display another measure instead. The attribute takes a measure ID (displayedValue="SLOC").
displayValueType (optional, default: VALUE) defines how the metric value is shown in the interface. It may be one of:
- NAME the level’s name
- MNEMONIC the level’s mnemonic
- RANK the level’s rank
- VALUE the measure’s value
- PERCENT to automatically convert a value between 0 and 1 into a percentage (also appending '%' as a suffix)
- ICON the level’s icon
- DATE the measure value converted to date format
- DATETIME the measure value converted to datetime format
- TIME the measure value converted to time format
- TEXT when the metric you are trying to display is textual information
  
  For DATE,DATETIME and TIME, you can specify the required format using the dateStyle, timeStyle and datePattern attributes described below.
unknownValue (optional, default: "?") defines what text to display if the level of the indicator is UNKNOWN or outside the specified dataBounds. Set this to OFF to use the old behaviour (which display the rank -1).
emptyValue (optional, default: "-") defines what text to display if there is no value in the database for the specified metric, or if a date is not specified. This is usually useful if a date has not been set yet manually in a form (and is therefore equal to 0), or if you have just added a new metric to your model you want to display specific text for the versions of your project where this metric did not exist yet.
dataBounds (optional, default:[;[) allows overriding the normal range of values that would trigger the display of the unknownValue text. This allows you to display the unknown value if the metric associated to the indicator is not within the defined bounds.
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
decimals (optional, default: 0) is the number of decimals places to be used for displaying values.
roundingMode (optional, default: HALF_EVEN) defines the behaviour used for rounding the numerical values displayed. The supported values are:
- CEILING to round towards positive infinity.
- DOWN to round towards zero.
- FLOOR to round towards negative infinity.
- HALF_DOWN to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round down.
- HALF_EVEN to round towards the "nearest neighbour" unless both neighbours are equidistant, in which case, round towards the even neighbour.
- HALF_UP to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round up.
- UP to round away from zero.
For more examples of rounding mode, consult http://docs.oracle.com/javase/8/docs/api/java/math/RoundingMode.html

The linksTable element is used instead of table to insert a links table, and accepts the following attributes:

id (mandatory) is used to find the localised version of the table name in a .properties file.
types (mandatory) is the list of links type ids the table displays.
operation (optional, default: UNION) allows to define basic operation on result set (mathematical). Accepted values are:
- UNION
- INTERSECTION
- SYMMETRIC_DIFFERENCE
direction (optional, default: OUT) defines the direction of the links to display. Accepted values are:
- OUT to show outbound links
- IN to display inbound links

For more information about artefact links, consult Artefact Links.

Charts area

Charts are displayed on the (bottom) right of the dashboard. They are defined via chart sub-elements contained in a charts element, as follows:

<charts>
	<chart id="CHART_ID" type="CHART_TYPE">
		<indicator>INDICATOR_1</indicator>
		<indicator>INDICATOR_2</indicator>
		<indicator>INDICATOR_3</indicator>
	</chart>
	<chart id="CHART_ID">
	...
	</chart>
	  ...
</charts>

You can read more about the available charts in Charts.

Dashboard templates

You can use dashboard templates to highlight specific charts on your dashboard by changing their size in terms of grid slots they occupy. The following is an example template that uses 4 columns of charts with custom aspect ratios applied to the first three charts:

Figure 5. A Custom Dashboard Template

<?xml version="1.0" encoding="UTF-8"?>
<roles xmlns:xi="http://www.w3.org/2001/XInclude">
	<role name="DEFAULT">
		<dashboard nbColumns="4" type="APPLICATION" template="1:4x2;2:2x2;3:2x2">
		(...)
			<charts>
				<xi:include href="chart1.xml" />
				<xi:include href="chart2.xml" />
				<xi:include href="chart3.xml" />
				<xi:include href="chart4.xml" />
				<xi:include href="chart5.xml" />
				<xi:include href="chart6.xml" />
				<xi:include href="chart7.xml" />
			</charts>
		</dashboard>
	</role>
</roles>

Note that you only need to specify custom dimensions for non-standard charts sizes using the syntax "position:width x height;", other charts will use a 1x1 grid slot by default.