| > Show on single page > Show on multiple pages |
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:
If the measured value is less than 0, the levelId is UNKNOWN with ranking -1.
If the measured value is exactly 0, the levelId is A with ranking 0.
If the measured value is between 0 (excluded) and 1 (included), the levelId is B with ranking 1.
If the measured value is between 1 (excluded) and 2 (included), the levelId is C with ranking 2.
If the measured value is between 2 (excluded) and 3 (included), the levelId is D with ranking 3.
If the measured value is between 3 (excluded) and 4 (included), the levelId is E with ranking 4.
If the measured value is between 4 (excluded) and 5 (included), the levelId is F with ranking 5.
If the measured value is more than 5 (excluded), the levelId is G with ranking 6.
The use of unions in scale bounds has been deprecated since Squore 16.0. You now need to use two distinct scale levels, as shown in the following example:
Old syntax:
<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>
Current syntax:
<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 UNKNOWN level receives special treatment when it comes to showing a trend:
When the rank goes from the UNKNOWN level to any other level, the trend is shown as:
When the rank goes from any level to UNKNOWN, the trend is shown as:
The Scale
element accepts the following attributes:
targetArtefactTypes
(optional) the specific artefacts that this scale applies to. If this attribute
is omitted, then the value of targetArtefactTypes
specified for the indicator using this scale is used.
macro
(optional) specifies the id of the ScaleMacro used to define this scale
vars
(optional) is a semicolon-separated list of parameters to pass to the ScaleMacro to define this scale
isDynamic
(optional, default: false) whether the scale levels are dynamic or not. Read more about the concept of dynamic scales in the section called “Dynamic Scales”.
Scale levels are defined using one or more ScaleLevel
sub-elements,
with the following attributes:
levelId
(mandatory) the unique identifier of the scale level.
bounds
(mandatory) the value limits for this scale level.
Infinite bounds can be specified by omitting the number, e.g.: [0;[ or [0;] for any null or positive number.
rank
(mandatory) the weight of the scale which is used when aggregating values.
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