|
|
Dashboards for artefacts consist of two areas: the scorecard area and the charts area. When clicking the name of an analysis model instead of an artefact, then a special dashboard is used: the Model/Group Dashboard.
The type of the artefact targeted is specified in the definition of the dashboard. The number of columns used in the graphics area and the default width and height of graphics can optionally be set.
<dashboard type="APPLICATION" nbColumns="4" defaultWidthValue="500" defaultHeightValue="500" > <scorecard> ... </scorecard> <charts> ... </charts> </dashboard>
The dashboard
element supports the following sub-elements:
The dashboard
element supports the following attributes:
type
(mandatory)
is the type of artefact that this dashboard definition applies to.
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.
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 the section called “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"
.
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
.
The scorecard shows a picture representing a chart (usually the artefact KPI) and a set of tables with further information. 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>
For more information about how to insert a KPI into the scorecard, refer to Key Performance Indicator.
There may be any number of tables below the KPI chart, and there may be any number of lines in each table.
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:
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 the section called “Descriptions”. 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. [colour syntax]
opened
(optional, default: false) defines
whether a table is opened or 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. For full details, consult the displayType reference for the line element.
displayOnlyIf
(optional) allows specifying a computation to evaluate whether or not to show the chart in the dashboard. If
the result of the computation is more than 0, then the chart is displayed. Consult Chapter 5, Expression Syntax for
more information about the supported computation syntax. Note that computations used in
displayOnlyIf
have a limited scope: they only apply to the current node in its current version.
This means that the functions like PREVIOUS_VALUE(), PREVIOUS_INFO(), DELTA_VALUE(), APP(), ANCESTOR(), PARENT() or
IS_DP_OK() cannot be used with displayOnlyIf
.
The line
element accepts the following attributes:
indicatorId
is the unique identifier of the measure, indicator or textual information to be displayed.
headerDisplayType
(in Model/Group Dashboards)
or
displayType
(in Artefact Dashboards)
(optional, default: MNEMONIC)
defines how the indicator is shown in the interface. The supported values are:
NAME
MNEMONIC
DESCRIPTION
displayOnlyIf
(optional) allows specifying a computation to evaluate whether or not to show the chart in the dashboard. If
the result of the computation is more than 0, then the chart is displayed. Consult Chapter 5, Expression Syntax for
more information about the supported computation syntax. Note that computations used in
displayOnlyIf
have a limited scope: they only apply to the current node in its current version.
This means that the functions like PREVIOUS_VALUE(), PREVIOUS_INFO(), DELTA_VALUE(), APP(), ANCESTOR(), PARENT() or
IS_DP_OK() cannot be used with displayOnlyIf
.
displayedValue
(optional)
allows overriding the indicator to display another measure instead.
The attribute takes a measure Id (displayedValue="SLOC").
displayType
(at model-level) or
displayValueType
(at artefact-level)
(optional, default: VALUE)
defines how the indicator's 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
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, as described in the section called “Common Attributes for info
”
PERCENT to automatically convert a value between 0 and 1 into a percentage (also appending '%' as a suffix)
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 with 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.
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.
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/6/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/6/docs/api/java/math/RoundingMode.html.
The external links in the lines of the score card tables 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 section called “Descriptions”.
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.
type
(mandatory) is the id of the type of
links the table displays.
direction
(optional, default: OUT) defines the direction of
the links to display. Set it to OUT to show outbound links or
IN to display inbound links.
For more information about artefact links, consult the section called “Artefact Links”.
You can use dashboard templates to highlight some of the 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:
<?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.
Charts are displayed on the right hand side of the dashboard. They
are defined via chart
elements 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 Chapter 7, Charts Reference.