Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • Tile colours can be changed
  • Tile positions can be changed
  • Tile contents can be changed
  • Tile size can be changed
  • New tiles can be added

Editing your tiles presentation

The default tile presentation is defined in the following files:

...

Info

Note that CAST provides "library" files containing examples of all the tiles that can be created and used in the Health Dashboard. You can use these files as well as the examples in this documentation page to build your own tiles. These library tiles can be found along side the live cmp.json and app.json files:

  • %CATALINA_HOME%\webapps\CAST-AAD\portal\resources\cmp_tiles_library.json
  • %CATALINA_HOME%\webapps\CAST-AAD\portal\resources\app_tiles_library.json

Viewing the changes in your browser

There is no need to restart the application server or application itself if you edit and save the cmp.json or app.json files: changes are immediate on saving the file. However, you may find that the changes are not immediately visible in the Health Dashboard. This is because the .json files are loaded into the browser's cache, therefore CAST recommends that you empty your browser cache to force the changes to become visible.

...

  • Tap F12 to open the Developer Tools window at the bottom of the page.
  • Click the Settings icon (a cog) to the right of the Developer Tools window
  • Tick the Disable cache (while DevTools is open) option and close the Settings window.
  • In this state, when you then tap F12 followed by F5 to refresh the page, the browser cache will be automatically emptied.

Changing the positions of tiles

Tiles are displayed in the Health Dashboard in a left to right and top to bottom format within each "Area" (see below). In the .json file, Tiles are listed one after the other, therefore to move a Tile, you need to change its position in the .json file using copy/paste: the higher up the list within the "Area" you place the tile code, the higher up it will be displayed in the dashboard itself.

Structure of the .json

The .json file is divided into various different sections, each corresponding to an item, area or tile in the Health Dashboard:

Areas

There are three areas, each corresponding to the Overview, Evolution and Software Enhancement Function Points (since Previous Version) (app.json only) sections you can see by default:

...

No Format
"id": 2,
"title": "Software Enhancement Function Points (since Previous Version)",

Tiles

Within each Area, various Tiles (or Panels) are defined, for example:

No Format
            {
                "id": 5,
                "plugin": "QualityIndicatorResults",
                "color": "yellow",
                "parameters": {
                    "title": "Robustness",
                    "qualityIndicator": {"id": "ROBUSTNESS", "format": "0.00"},
                    "details":{
                        "ranges":[1.6,2.8,3.0,3.4]
                    },
                    "widget": "gauge"
                }
            },

Available parameters in .json

Global parameters

Please see HD - Dashboard wide configuration options in json for more information about the following parameters that can be defined in the cmp.json (and in the app.json) to provide dashboard wide parameterization (i.e, they are valid regardless of whether your dashboard contains one or multiple Applications):

No Format
    "title": "Health Dashboard",
    "language": "dev",
    "horizontalScroll": false,
    "confirmLogout": true,
	"persistNavigationFilters":true,
	"filtering":{
      "filterTags":false
    },
    "period": {
        "shift": true,
        "periods": [
            { "diff": 30, "units": "days" },
            { "diff": 3, "units": "months" },
            { "diff": 6, "units": "months" },
            { "diff": 12, "units": "months", "selected": true },
            { "diff": 2, "units": "years" },
            { "diff": 0, "units": "alltime" }
        ]
    }

Tile parameters

A tile or panel represents the equivalent of a "plugin". Each tile is composed of the following properties:

Parameter
Description
idRepresents the tile's unique id. This is a technical id used to identify the panels and MUST be unique throughout the .json file.
pluginRepresents the type of indicators to be displayed in the tile. The plugins that are available are listed below under Plugin parameters.
colorOptional parameter that describes the tile color theme to be used. A light grey color is used if none is defined. Colors are currently limited to:
  • blue
  • black
  • dark grey
  • orange
  • green
  • purple
  • light grey
  • yellow
size

Optional parameter provides the ability to expand tiles in size (large and small):


autoFit

Optional parameter that (when set to true - the default position) will truncate a plugin's title text if it is longer than the size of the tile (whether a large or small tile). Using this parameter may lead to visually less consistent dashboards.

The default value is true, where the font size used for a plugin's title text will be reduced so that the title text fits the tile size. To deactivate the autoFit option, you need to specifically add the parameter to your plugin and set it to false.

parameters This section contains plugin specific parameters. Please refer to each of the following plugin definitions under Plugin parameters for more information about this.

Anchor
TechnicalSizeMeasures
TechnicalSizeMeasures
Technical Size Measures parameters

Info
Only available in app.json.

...

No Format
"TechnicalSizeMeasures": {
    "values": [
      {
        "id": 67011,
        "label": "Number of Critical Violations"
      },
      {
        "id": 10151,
        "label": "Number of Lines of Code"
      },
      {
        "id": 10154,
        "label": "Number of Files"
      },
      {
        "id": 10155,
        "label": "Number of Classes"
      },
      {
        "id": 10156,
        "label": "Number of Programs"
      },
.....

Plugin parameters

A plugin also has various different parameters as follows:

Info

Note that:

  • some plugins are named specifically for use in a specific .json file. In otherwords, a plugin will have two unique names, one for the cmp.json and one for the app.json. Plugins that function like this are documented as such below.
  • plugins that function in the cmp.json file may not necessarily function in the app.json file (and vice-versa)

Anchor
common
common
Common plugin parameters

ParameterDescription
titleA title used to identify the tile.
mode

Determines how much detail will be presented in a tile. Not all tiles support the attribute.

  • terse
  • verbose
qualityIndicator or sizingMeasureRepresent the measurement data properties (typically the indicator identifier, some high level description and the value formatting).
  • quality indicator ids include i.e. ARCHITECTURAL_DESIGN, CHANGEABILITY, DOCUMENTATION, LINES_OF_CODE, PERFORMANCE, PROGRAMMING_PRACTICE, ROBUSTNESS, SEI_MAINTAINABILITY, SECURITY, TQI, TRANSFERABILITY
  • it is possible to use the ID of any CAST AIP metric in place of the worded indicator IDs listed above. For example the LINES_OF_CODE indicator can be replaced with 10151 (the equivalent ID).
  • the format in which the value has to be displayed, it uses the the format defined in numeral.js (see http://numeraljs.com/ for available Numbers formats.

scope

Enables a specific filter to be added to a tile (and related detail) to focus on Applications assigned to a defined tag and related category. Both sub-parameters are mandatory:

  • category the category name

  • tag the tag name in the category

The parameter is global to tile configuration but only applies to the following plugins:

  • PortolioListing

  • QualityIndicatorResults and QualityIndicatorEvolution

  • SizingMeasureResults

  • SizingMeasureEvolution

  • BackgroundFactsResults

  • BackgroundFactsEvolution

  • CustomExpressions

  • CustomExpressionsEvolution

See Note about tags and categories as tile scopes in Health Dashboard.

PortfolioListing

Info

This tile is only available for use in the cmp.json file - in other words at multi-app/portfolio level.

...

No Format
{				   
	"id":20160405,
	"plugin": "PortfolioListing",
	"color": "grey-dark",
	"parameters":{
		"title":"Number of applications",
		"scope":{
			"category":"Vendors",
			"tag":"Vendor 1"
		}
	}
},

Notification

An array whose first five items are shown in the area. Each item describes a notification:

...

No Format
            {
                "id": 1000,
                "plugin": "Notification",
                "color": "orange",
                "size":"large",
                "parameters": {
                    "title": "Applications Fast Facts",
                    "notifications":[
                        {"type":"analysisSince"},
                        {"type":"addedCount"},
                        {"type":"sizingMeasureEvolution", "threshold":0.01, "trend":"increase", "sizingMeasure":{"id": "CRITICAL_VIOLATIONS", "format": "0", "description":"critical violations"}},
                        {"type":"sizingMeasureEvolution", "threshold":0.05, "trend":"increase", "sizingMeasure":{"id": "LINES_OF_CODE", "format": "0", "description":"lines of code"}},
                        {"type":"qualityIndicatorEvolution", "threshold":0.02, "trend":"degradation", "qualityIndicator":{"id": "PERFORMANCE", "format": "0", "description":"performance"}}
                    ]
                }
            }

BackgroundFactsResults / BackgroundFactsResult

Info

Note that:

  • when using this tile in the cmp.json file, please use BackgroundFactsResults
  • when using this tile in the app.json file, please use BackgroundFactsResult

...

No Format
<?xml version="1.0" encoding="iso-8859-1" ?>
<DATA model="Central Model" version="1.0.0.17" scope="Productivity">

<!-- Module Definition -->
<DSS_IN_OBJECTS>
      <OBJECT_NAME>SEVRES full content</OBJECT_NAME>
      <OBJECT_TYPE_ID>20000</OBJECT_TYPE_ID>
      <OBJECT_ID>10</OBJECT_ID>
</DSS_IN_OBJECTS>

<!-- RESULTS : 66061 : Business Value for Module -->
<DSS_IN_METRIC_RESULTS>
    <METRIC_ID>66061</METRIC_ID>
    <METRIC_NUM_VALUE>4</METRIC_NUM_VALUE>
    <OBJECT_ID>10</OBJECT_ID>
</DSS_IN_METRIC_RESULTS>

<!-- RESULTS : 66001 : Effort for Module -->
<DSS_IN_METRIC_RESULTS>
    <METRIC_ID>66001</METRIC_ID>
    <METRIC_NUM_VALUE>10.5</METRIC_NUM_VALUE>
    <OBJECT_ID>10</OBJECT_ID>
</DSS_IN_METRIC_RESULTS>

<!-- RESULTS : 66002 : Cost for Module -->
<DSS_IN_METRIC_RESULTS>
    <METRIC_ID>66002</METRIC_ID>
    <METRIC_NUM_VALUE>400</METRIC_NUM_VALUE>
    <OBJECT_ID>10</OBJECT_ID>
</DSS_IN_METRIC_RESULTS>

</DATA>

BackgroundFactsEvolution

Info
Note that this tile can be used at multi (cmp.json) and single (app.json) Application level.

...

 

No Format
{
                "id": 660011,
                "plugin": "BackgroundFactsEvolution",
                "color": "purple",
                "parameters": {
                    "widget":"number",
                    "aggregation":"average",
                    "title": "Effort",
                    "backgroundFact": {"id": "EFFORT","format": "0,000"}
                }
            },
            {
                "id": 660012,
                "plugin": "BackgroundFactsEvolution",
                "color": "purple",
                "parameters": {
                    "widget":"spline",
                    "aggregation":"sum",
                    "title": "Effort",
                    "backgroundFact": {"id": 66001,"format": "0,000"}
                }
            }

BackgroundFactAndQualityIndicatoryBySizingMeasureResults

Info
Please note that by default this plugin (tile) does not appear in any default .json files. If you need to use it, it will only function at Multi-application level (cmp.json). An example of the tile is given below.

...

No Format
			{
                "id": 10203,
                "plugin": "BackgroundFactAndQualityIndicatoryBySizingMeasureResults",
                "color": "purple",
                "parameters": {
                    "title": "Lines of Code - Effort",
                    "order": "descending",
                    "qualityIndicator": {"id": "TQI", "format": "0.00", "description": "TQI"},
                    "sizingMeasure": {"id": "LINES_OF_CODE", "format": "0,000a", "description": "Lines of Code"},
                    "backgroundFact": {"id": "EFFORT", "format": "0.00", "description": "Effort"},
                    "chartSettings": {
                        "xAxis": {
                            "plotLines": [
                                { "value": 3, "label":{"text":"TQI=3"} }
                            ]
                        },
                        "yAxis": {
                            "plotLines": [
                                { "value": 3.0, "label":{"text":"Risk=3"} }
                            ]
                        }
                    }
                }
            }

CriticalQualityRulesRatios / CriticalQualityRuleRatio

Info

Note that:

  • when using this tile in the cmp.json file, please use CriticalQualityRulesRatios
  • when using this tile in the app.json file, please use CriticalQualityRuleRatio

...

No Format
                {
                    "id": 107,
                    "plugin": "CriticalQualityRuleRatio",
                    "color": "grey-dark",
                    "size":"large",
                    "parameters": {
                        "type":"topRules",
                        "title": "Top Critical Rules",
                        "count": 5,
                        "format":"0,000",
                        "order": "descending",
                        "mode": "ratio"
                    }
                }

CriticalViolationsPerHealthFactor


The critical violations per health factor module provides a critical violations count for a given business criterion:

...

No Format
                {
                    "id": 106,
                    "plugin": "CriticalViolationsPerHealthFactor",
                    "color": "green",
                    "size":"large",
                    "parameters": {
                        "type":"topRiskiest",
                        "title": "Top riskiest modules",
                        "count": 5,
                        "order": "descending",
                        "qualityIndicator": {"id": "PERFORMANCE", "format": "0.00", "description": "Performance"}
                    }
                }

FunctionalWeightMeasureResult / FunctionalWeightMeasureResults

Info

Note that:

  • when using this tile in the cmp.json file, please use FunctionalWeightMeasureResults
  • when using this tile in the app.json file, please use FunctionalWeightMeasureResult

...

Note that when drilling down, a table lists all those Applications that are not included in the AFP measure (essentially all those Applications not using a CAST EFP license:

QualityIndicatorBySizingMeasureResult / QualityIndicatorBySizingMeasureResults

Info

Note that:

  • when using this tile in the cmp.json file, please use QualityIndicatorBySizingMeasureResults
  • when using this tile in the app.json file, please use QualityIndicatorBySizingMeasureResult

...

No Format
                {
                    "id": 101,
                    "plugin": "QualityIndicatorBySizingMeasureResult",
                    "size":"large",
                    "color": "purple",
                    "parameters": {
                        "type":"treemap",
                        "title": "Security Mapping",
                        "order": "descending",
                        "qualityIndicator": {"id": "SECURITY", "format": "0.00", "tooltipFormat":"0.00", "description": "Security"},
                        "sizingMeasure": {"id": "LINES_OF_CODE", "format": "0,000.0a", "tooltipFormat":"'0,000", "description": "Lines of Code"},
                        "treemapColors": {
                            "ranges":[1,2,3,4],
                            "colors":["#ff0242","#FF5B2B","#fbbb6e","#3dc680"]
                        }
                    }
                },

QualityIndicatorResult / QualityIndicatorResults

Info

Note that:

  • when using this tile in the cmp.json file, please use QualityIndicatorResults
  • when using this tile in the app.json file, please use QualityIndicatorResult

...

No Format
{
    "id": 104,
    "plugin": "QualityIndicatorResult",
    "color": "yellow",
    "parameters": {
    "title": "Robustness",
    "widget": "gauge",
    "qualityIndicator": {
        "id": "ROBUSTNESS",
        "format": "0.00"
    }
    }
},

Example for a riskGuage at top level in app.json or cmp.json

No Format
"QualityIndicatorResults" :
{
"ranges":[1.6,2.8,3.0,3.4],
"riskGauge":
	{
	"colors":["#02eff4", "#ff4b02", "#02eff4", "#7fc4b2"]
	}
},

QualityIndicatorEvolution

  1. qualityIndicator: information about the indicator to display: its id, format and an optional description
    1. id is either: ARCHITECTURAL_DESIGN, CHANGEABILITY, DOCUMENTATION, PERFORMANCE, PROGRAMMING_PRACTICE, ROBUSTNESS, SEI_MAINTAINABILITY, SECURITY, TQI, TRANSFERABILITY
    2. id can also be a numerical ID corresponding to any CAST AIP metric
    3. description is whatever is required
    4. format is the format in which the value has to be displayed, it uses the the format defined in numeral.js (see http://numeraljs.com/ for available Numbers formats)
    5. widget provides the rendering type (number for number variation, line or spline for trend chart representation - line uses straight lines whereas spline provides smooth transitions between points)

...

No Format
                {
                    "id": 201,
                    "plugin": "QualityIndicatorEvolution",
                    "color": "blue",
                    "parameters": {
                        "widget":"number",
                        "title": "TQI",
                        "qualityIndicator": {
							"id": "TQI",
							"format": "0.00"
						}
                    }
                },

Anchor
SizingMeasureEvolution
SizingMeasureEvolution
SizingMeasureEvolution

  1. sizingMeasure: information about the indicator to display : its id, format and an optional description
    1. id is either: TECHNICAL_DEBT, LINES_OF_CODE, NUMBER_OF_ARTIFACTS, NUMBER_OF_COMMENT_LINES, NUMBER_OF_DECISION_POINTS, NUMBER_OF_FILES, NUMBER_OF_FUNCTION_POINTS, NUMBER_OF_BACKFIRED_FUNCTION_POINTS and CRITICAL_VIOLATIONS
    2. id can also be a numerical ID corresponding to any CAST AIP metric
    3. description is whatever is required
    4. format is the format in which the value has to be displayed, it uses the the format defined in numeral.js (see http://numeraljs.com/ for available Numbers formats)
    5. widget provides the rendering type (number for number variation, line or spline for trend chart representation - line uses straight lines whereas spline provides smooth transitions between points)

...

No Format
                {
                    "id": 202,
                    "plugin": "SizingMeasureEvolution",
                    "color": "orange",
                    "parameters": {
                        "widget":"number",
                        "title": "Technical Debt",
                        "sizingMeasure": {"id": "TECHNICAL_DEBT", "format": "$0,000.0a"}
                    }
                },

Anchor
SizingMeasureResult
SizingMeasureResult
SizingMeasureResult / SizingMeasureResults

Info

Note that:

  • when using this tile in the cmp.json file, please use SizingMeasureResults
  • when using this tile in the app.json file, please use SizingMeasureResult

...

No Format
                {
                    "id": 102,
                    "plugin": "SizingMeasureResult",
                    "color": "green",
                    "parameters": {
                        "title": "Size",
                        "sizingMeasure": {
                            "id": "LINES_OF_CODE",
                            "format": "0,000",
                            "description": "Lines of Code"
                        }
                    }
                },

This tile (not available by default) provides the ability to define external URLs (e.g. to other data dashboards) in a tile:

...

No Format
{
    "id": 100,
    "plugin": "ExternalLink",
    "color": "red",
    "parameters": {
        "title": "Tackle your Technical Debt",
        "url":"http://www.castsoftware.com"
    }
},

Anchor
custom
custom
Custom expression tiles

At portfolio (cmp.json) and application level (app.json), it is possible to define tiles with custom expressions. A custom expression is defined through a mathematical subset representation involving operations on criteria values (e.g. the ratio of number of lines of codes per critical violations or the count of applications with more than n files).

The tile can represent averaged values (excluding the application not having one of the values such as a background fact or some sizing measure, or those whose function calculation result is infinite) or a total value. For comparison, business criteria scores are average while sizing is usually a total on the portfolio. 

Custom expression tiles can be defined for the current snapshot state (most recent snapshot for all applications at portfolio level or selected snapshots at application level), or via evolutions. 

The mathematical formula available involve the following expression patterns:

Operators

Operator
Name
Syntax
Associativity
Example
Result
()
Parentheses
(x)
None
2 * (3 + 4)
14
,
Parameter separator
x, y
Left to right
max(2, 1, 5)
5
+
Add
x + y
Left to right
4 + 5
9
-
Subtract
x - y
Left to right
7 - 3
4
*
Multiply
x * y
Left to right
2 * 3
6
/
Divide
x / y
Left to right
6 / 2
3
%mod
Modulus
x % y
Left to right
8 % 3
2
^
Power
x ^ y
Right to left
2 ^ 3
8
!
Factorial
y!
Left to right
5!
120
? :
Conditional expression
x ? y : z
Right to left
15 > 100 ? 1 : -1
-1

Functions

Function
Name
Syntax
Associativity
Example
Result
abs
Absolute
abs(x)
None
abs(-2)
2
round
Round
round(x,n)
None
round(3.142265,3)
3.142
sqrt
Square root
sqrt(x)
None
sqrt(4)
2
log
Logarithmic
log(x,base)
None
log(1024,2)
log(1024)
10
3.01
 
Info
Other classic patterns are available but may not be supported by the Health Dashboard in terms of rendering (i.e. those returning non numerical values such as booleans).

CustomExpressionsEvolution

The custom expression tile enables operations on various multiple indicators in a single tile through snapshots. Lots of different operations can be performed on the tile, from scaling to combinations using mathematical formula (as listed above). As it could involve multiple results and extra operations to get the results, the CustomExpressionsEvolution tiles could hinder the performances of the dashboard at some point (depending on number of tiles, number of variables, number of snapshots).

Standard parameters

  • title please note that exceptionally, the title is used to identify different types of custom expression tiles, from result to evolution, portfolio to application level. if you want to avoid duplicates at application level detail, please make sure tiles with the same formula have the same title field.
  • description
  • format

Tile specific parameters

  1. documentation a documentation information to explain about the custom indicator. The field value is a string (that can include html tags) that will be displayed on page details at portfolio level.
  2. aggregator the aggregation type: "average" or "sum", default to average.
  3. expression the mathematical operation to perform for each application (some examples: "sqrt((tqi-1)/3)", "tqi/loc", "log(x)*y^2", etc.)
  4. variables each variable defined in the mathematical operation has to be defined for results to be caclulated. The variable name is defined through its key and have a type and an id. (some examples: "variables":{"tqi":{"type":"qualityIndicator", "id":"TQI"},"loc":{"type":"sizingMeasure", "id":"LINES_OF_CODE"},"effort":{"type":"backgroundFact", "id":"EFFORT"}}

CustomExpression/CustomExpressions

The custom expression tile enables operations on various multiple indicators in a single tile. Lots of different operations can be performed on the tile, from scaling to combinations using mathematical formula (as listed above).

Standard parameters

  1. title please note that exceptionally, the title is used to identify different types of custom expression tiles, from result to evolution, portfolio to application level. if you want to avoid duplicates at application level detail, please make sure tiles with the same formula have the same title field.
  2. description
  3. format

Tile specific parameters

  1. documentation a documentation information to explain about the custom indicator. The field value is a string (that can include html tags) that will be displayed on page details at portfolio level.
  2. aggregator the aggregation type: "average" (default), "sum", or "AvgSum" (see below)
  3. expression the mathematical operation to perform for each application (some examples: "sqrt((tqi-1)/3)", "tqi/loc", "log(x)*y^2", etc.)
  4. variables each variable defined in the mathematical operation has to be defined for results to be caclulated. The variable name is defined through its key and have a type and an id. (some examples: "variables":{"tqi":{"type":"qualityIndicator", "id":"TQI"},"loc":{"type":"sizingMeasure", "id":"LINES_OF_CODE"},"effort":{"type":"backgroundFact", "id":"EFFORT"}}

Info

Notes about the aggregator type "AvgSum"

When using this aggregator type, a new property "aggregator" can also be provided for each key under "variables" to specify the aggregation type as "sum" or "average" for each variable respectively. The default is set to "sum" when "AvgSum" is defined under "aggregator". For example the following lines under "variables" would take both factors produce a sum and then divide them. As such it is now possible to specify the addition of all the violations first, then add up all the function points, THEN do the division (the SUM(Violations) / SUM(Function points) ):

No Format
{
    "id":987654321529,
    "plugin": "CustomExpressions",
    "color": "green",
    "parameters": {
    "title": "TQI - Critical violations ratio",
    "aggregator": "AvgSum",
    "description":"",
    "format":"0.00",
    "expression":"crit / tqi",
    "variables":{
        "tqi": {"type":"qualityIndicator", "id":"TQI", "aggregator": "sum"},
        "crit":{"type":"sizingMeasure", "id":"CRITICAL_VIOLATIONS", "aggregator": "sum"}
    }
    }
},

Example (for cmp.json) - CustomExpressions

No Format
{
    "id": 987654321529,
    "plugin": "CustomExpressions",
    "color": "blue",
    "parameters": {
    "title": "TQI - Critical violations ratio",
    "description":"",
    "format":"0.00",
    "expression":"crit / tqi",
    "variables":{
        "tqi": {"type":"qualityIndicator", "id":"TQI"},
        "crit":{"type":"sizingMeasure", "id":"CRITICAL_VIOLATIONS"}
    }
    }
},

Example (for app.json) - CustomExpression

No Format
{
    "id": 987654321529,
    "plugin": "CustomExpression",
    "color": "blue",
    "parameters": {
    "title": "TQI - Critical violations ratio",
    "description":"",
    "format":"0.00",
    "expression":"crit / tqi",
    "variables":{
        "tqi": {"type":"qualityIndicator", "id":"TQI"},
        "crit":{"type":"sizingMeasure", "id":"CRITICAL_VIOLATIONS"}
    }
    }
},