Page tree

Versions Compared

Key

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

...

Info
Summary: This page explains how to configure the Health Dashboard tile interface

Introduction

The Health Dashboard has a "tile" or "panel" based interface that provides access to the data:

Image RemovedImage Added

These tiles have default presentation settings, but this can be modified and tailored to your requirements. For example:

...

The default tile presentation is defined in the following files:files listed below. To modify the presentation, edit the .json file with a text editor (Notepad or other similar application). CAST recommends:

  • creating a copy of the default .json files that can be used as a replacement if an error occurs during editing
  • first changing existing parameters such as color and title and also moving Tiles around before you begin making large scale and more complex changes
File nameUsage

WAR 1.x

  • CATALINA_HOME\webapps\CAST-Health\portal\resources\cmp.json

WAR ≥ 2.x

  • CATALINA_HOME\webapps\CAST-Health\WEB-INF\classes\config\hd\cmp.json

ZIP ≥ 2.x

  • <unpacked_zip>\configurations\config\hd\cmp.json
This file governs the display of tiles when your Measurement Service contains multiple Applications - i.e the Multi-application landing page. For more information about the Multi-application and Application landing pages, see Health Dashboard - GUI.

WAR 1.x

  • CATALINA_HOME\webapps\CAST-Health\portal\resources\app.json

WAR ≥ 2.x

  • CATALINA_HOME\webapps\CAST-Health\WEB-INF\classes\config\hd\app.json

ZIP ≥ 2.x

  • <unpacked_zip>\configurations\config\hd\app.json

This file governs the display of tiles for a single Application - i.e the Application landing page. This page is displayed in two situations:

  • When the Measurement Service contains information about only one Application
  • When you have drilled down from the Multi-application landing page into a single Application.

For more information about the Multi-application and Application landing pages, see Health Dashboard - GUI.

To modify the presentation, edit the .json file with a text editor (Notepad or other similar application). CAST recommends:

  • creating a copy of the default .json files that can be used as a replacement if an error occurs during editing
  • first changing existing parameters such as color and title and also moving Tiles around before you begin making large scale and more complex changes


Note that
Info
Info

Starting from ≥ 1.27 and ≥ 2.1, two additional json files have been added that are used to display tiles for the ISO-5055 view that uses data generated by the ISO-5055 Index extension:

WAR 1.x

  • CATALINA_HOME\webapps\CAST-Health\portal\resources\app-ISO.json
  • CATALINA_HOME\webapps\CAST-Health\portal\resources\cmp-ISO.json

WAR ≥ 2.x

  • CATALINA_HOME\webapps\CAST-Health\WEB-INF\classes\config\hd\app-ISO.json
  • CATALINA_HOME\webapps\CAST-Health\WEB-INF\classes\config\hd\cmp-ISO.json

ZIP ≥ 2.x

  • <unpacked_zip>\configurations\config\hd\app-ISO.json
  • <unpacked_zip>\configurations\config\hd\cmp-ISO.json

See Manual configuration of Dashboard tiles using ISO-5055 data for more information.

Image Added

Library files

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 here:

WAR 1.x

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

WAR ≥ 2.x

  • CATALINA_HOME\webapps\CAST-Health\static\portal\resources\cmp_tiles_library.json
  • CATALINA_HOME\webapps\CAST-Health\static\portal\resources\app_tiles_library.json

ZIP ≥ 2.x - The file is located in a compiled JAR file located at the root of the unpacked ZIP. This JAR file will need to be unpacked to find the .json files:

  • <unpacked_jar>\BOOT-INF\classes\static\portal\resources\cmp_tiles_library.json

  • <unpacked_jar>\BOOT-INF\classes\static\portal\resources\cmp_tiles_library.json

Viewing the changes in your browser

...

Info

Note that:

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

...

  1. qualityIndicator: information about the indicator to display : its id, format and an optional description
    • id is
    either
    • one of the following: ARCHITECTURAL_DESIGN, CHANGEABILITY, DOCUMENTATION, PERFORMANCE, PROGRAMMING_PRACTICE, ROBUSTNESS, SEI_MAINTAINABILITY, SECURITY, TQI, TRANSFERABILITY
    id can
    • - can also be a numerical ID
    corresponding to any CAST AIP metric
    • such as 66031 (Programming Practices)
    • 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)
    • technicalId is the ID of the parent Technical Criteria
    you want to display
    • , for example "61003" would display "Programming Practices - OO Inheritance and Polymorphism" in the tile. Functions at Portfolio and Application level.
    • description
    is
    •  free text of whatever is required
  2. details provide parameters dedicated towards drill down page views:
    • ranges: range used to separate indicator groups displayed in detail view. Default is [2,3] to produce : [indicator < 2, 2 <= indicator < 3, 3<= indicator]
    • colorsfrom hex code color to hex code color. from provides the grade 1 white to provide the grade 4 color values. Default values are #CE2029 for grade 1 and #28AC1B for grade 4. The choice of a gradient or plain colors can be made through the useGradient parameter. Default value is false.
  3. widget provides graphical representations of the indicator (e.g. gaugedonut or riskGauge)
    • If widget is set to riskGauge, then the gauge will display color based on the indicator score with regard to riskGauge configuration (thresholds and colors). The tile color theme is restricted to grey-light and grey-dark when using this widget. Default color is grey-dark.
    • riskGauge: can be set globally in the top level QualityIndicatorResults global configuration and can be overridden in the tile parameters. Parameters are used if the widget parameter is set to riskGauge
      • thresholds: define the thresholds used to qualify the score risk; default values are: [2, 3, 3.99] meaning high-risk:1 to 2, risk:2 to 3, low risk:3 to 3.99, and very low risk over
      • colors: define the colors using hexidecimal color numbers according to the number of thresholds (remember that one more color is always required than the number of thresholds defined, for example: defining 3 thresholds will result in 4 areas, hence 4 colors are required)
  4. icon: boolean to display (true) an icon next to the tile title, false by default.
  5. zoom: true or false to enable zooming in detail charts. Default value is true. The zoom feature works best when you have multiple Applications consolidated into your Health Dashboard - in this situation it can be difficult to read the score details of each column (a column represents one Application). You can therefore use the zoom option to select (using the mouse) the Applications you want to zoom into.
Info

Parameters are available panel per panel. Some general parameters can be set on the top most level of the json structure through the "QualityIndicatorResults" field. The parameters set there involve the details fields such as rangescolor or riskGauge.

Example (for cmp.json)

No Formatcode
{
    "id": 211999,
    "plugin": "QualityIndicatorResults",
    "color": "grey-dark",
    "parameters": {
    	"title": "Programming Practices - OO Inheritance and Polymorphism",
    	"widget": "gauge",
    	"qualityIndicator": {
        "id": "ROBUSTNESS",{
        	"technicalIdid": "6100366031",
        	"format": "0.00",
        	"description": ""
    	}
    }
},

Example (for app.json)

No Formatcode
{
    "id": 104999,
    "plugin": "QualityIndicatorResult",
    "color": "yellow",
    "parameters": {
    	"title": "RobustnessProgramming Practices",
    	"widget": "gauge",
    	"qualityIndicator": {
        	"id": "ROBUSTNESS66031",
        	"format": "0.00"
			"description": ""
    	}
    }
},

Example for a riskGauge at

...

the start of the file in app.json or cmp.json

No Formatcode
"QualityIndicatorResults" : {
      
	"ranges": [2.5, 2.9, 3.2],
	"riskGauge": 	{
		"thresholds":[1,2,2.7,3.2],
		"colors":["#02eff4","#ff4b02","#025af4","#7fc4b2","#eff402"]
	}
},

...

  • id: each custom tile must have its own unique ID within cmp.json / app.json
  • plugin: must be IndustryStandards (cmp.json) / IndustryStandard (app.json)
  • color: tile color
  • parameters:
    • type: One of the following depending on the industry standard you are measuring:
      • CISQ
      • MIPS
      • ISO-5055
      • OWASP-2013
      • OWASP-2017
    • title: Title of the tile - free text
    • widget: (only when you require grade format results) - gauge or donut
    • industryStandard:
      • id: the IndustryStandard industryStandard ID defined by the extension (see the extension documentation for more information).
      • indexID: this ID should be the industryStandard parent Business Criterion index. This ensures that drill down from the tile functions correctly. For example, if you have configured the tile to show CISQ-Performance-Efficiency (1062102), you should configure the indexID to 1062100 (the parent Business Criterion index)
      • mode: the mode in which the value needs to be displayed:
        • grade: this will provide a value from 1 - 4
        • violations: this will provide the total number of violations
        • compliance: this will provide the percentage value of compliance to the chosen IndustryStandard
      • format: the format in which the value has to be displayed, this uses the the format defined in numeral.js (see http://numeraljs.com/ for available Numbers formats):
        • 0.00 for grade format
        • 0,000 for violations format
        • 0.0% for compliance format
      • description: an optional free text field to describe what the tile shows (not shown in the dashboard)

...

Code Block
languagexml
{
  "id": 1234,
  "plugin": "IndustryStandards",
  "color": "black",
  "parameters": {
	"type": "CISQ",
    "title": "CISQ-Security Index",
    "widget": "gauge",
    "industryStandard": {
		"id": "10621041062166",
		"indexID": "1062100",
		"mode": "grade",
		"format": "0.00",
		"description": "CISQ-Security in grade format"
    }
  }
}

...

Code Block
languagexml
{
  "id": 1236,
  "plugin": "IndustryStandard",
  "color": "orange",
  "parameters": {
	"type": "OWASP-2013",    
	"title": "OWASP-2013 Index",
    "industryStandard": {
		"id": "1062300",
		"indexID": "1062300",
		"mode": "violations",
		"format": "0,000",
		"description": "OWASP-2013 in violation format" 
    }
  }
}

...

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:

...

Functions

...

 

...

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

...