Health Dashboard tile management

Introduction

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

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

• 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 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

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

If you are using Google Chrome the following tip can be used to automatically empty the browser cache:

• 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, Trendsand Automated Enhancement Point (app.json only) sections you can see by default:

These are represented in the .json file as follows:

"id": 1,
"title": "Overview",

and:

"id": 3,
"title": "Trends",

and:

"id": 2,
"title": "Automated Enhancement Point",

Tiles

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

            {
                "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 Health Dashboard json configuration options 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):

    "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" }
        ]
    }

QualityIndicatorResults (global)

These global settings impact all tiles configured as QualityIndicatorResult/s , allowing the configuration of grouping, value ranges, grade labels, and color schemes.

"QualityIndicatorResults": {
	"groupBy": "technology",
	"ranges": [2.5, 2.9, 3.2],
	"gradeLabels":{},
	"colors": {
		"useGradient": false,
		"from": "#ff0242",
		"to": "#fbbb6e"
	}
},

Note that changing any of these parameters requires that the dashboard is restarted before the new values will be taken into account.

"ranges":[
	1.6,
	2.4,
	3.0,
	3.4
],

"gradeLabels":{
	"1.6": "Poor",
	"2.4": "Average",
	"3.0": "Good",
	"3.4": "Excellent"
},

Tile parameters

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

Technical Size Measures parameters

Technical Size Measures govern the configurable display of Size indicators (Number of Critical Violations, Number of Code Lines, Number of Files etc.) for the drill down page available at Application level for the Technical Size tile (click to enlarge):

The list of indicators can be configured via the app.json file under the TechnicalSizeMeasures section:

In this example we have added two additional indicators for Technical Debt of Added Violations (68901) and Technical Debt of Removed Violations (68902):

"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"
      },
      {
        "id": 10157,
        "label": "Number of Forms"
      },
      {
        "id": 10158,
        "label": "Number of SQL Artifacts"
      },
      {
        "id": 10163,
        "label": "Number of Tables"
      },
      {
        "id": 10152,
        "label": "Number of Artifacts"
      },
      {
        "id": 10107,
        "label": "Number of Comment Lines"
      },
      {
        "id": 10109,
        "label": "Number of Commented Out Code Lines"
      },
      {
        "id": 67901,
        "label": "Number of Critical Violations Added"
      },
      {
        "id": 67902,
        "label": "Number of Critical Violations Removed"
      },
      {
        "id": 67216,
        "label": "Number of Pending Violations"
      },
      {
        "id": 67217,
        "label": "Number of Solved Violations"
      },
      {
        "id": 67218,
        "label": "Number of Excluded Violations"
      },
      {
        "id": 68001,
        "label": "Technical Debt"
      },
	  {
        "id": 68901,
        "label": "Technical Debt of added Violations"
      },
	  {
        "id": 68902,
        "label": "Technical Debt of removed Violations"
      }
    ]
  },

E.g:

Plugin parameters

A plugin also has various different parameters as follows:

Common plugin parameters

PortfolioListing

Without scope:

{
    "id":20150818,
    "plugin": "PortfolioListing",
    "color": "grey-dark",
    "parameters":{
    	"title":"Number of applications"
    }
},

With scope on Tag and Category:

{				   
	"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:

1. type: Describe the type of notifications.
   1. analysisSince - count the number of applications not analyzed in the selected period of time
   2. addedCount - count the number of applications added in the selected period of time
   3. sizingMeasureEvolution - count the number of applications with an evolution larger than the given threshold
   4. qualityIndicatorEvolution - count the number of applications with an evolution larger than the given threshold
2. threshold used by sizingMeasure/qualityIndicator evolutions to filter application with small evolutions
3. trend used by qualityIndicator evolutions to focus on improvement/degradations or sizingMeasure evolutions to focus on increase/decrease
4. qualityIndicatorEvolution comes with qualityIndicator information:
   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. sizingMeasureEvolution comes with a sizingMeasure information
   1. id is either: TECHNICAL_DEBT,LINES_OF_CODE, NUMBER_OF_ARTIFACTS, NUMBER_OF_COMMENT_LINES, NUMBER_OF_DECISION_POINTS, NUMBER_OF_FILES, AUTOMATED_IFPUG_FUNCTION_POINTS_ESTIMATION,BACKFIRED_IFPUG_FUNCTION_POINTS and CRITICAL_VIOLATIONS
   2. id can also be a numerical ID corresponding to any CAST AIP metric
   3. 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)
   4. description is whatever is required

Example (for cmp.json)

            {
                "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

A tile that enables you to display Background Facts that you have manually configured and uploaded during the snapshot generation. The tile can display information about one metric that you have defined in the uploaded Background Facts file.

• backgroundFact: information about the indicator to display : its id, format and an optional description
  • id refers to the Background Fact numerical ID as displayed in the Assessment Model in the CAST Management Studio (in recent versions, the IDs with a “metric_group” value of 6):

• • 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)
  • description is whatever is required
• url: the url field provides a simple means to link the drill down at detail level to some other web based information. Since the metrics comes from non-CAST sources, the external page containing information on the details of the metric, can be linked to here. If no url is provided, drill down cannot be achieved and a message will be displayed in tooltips on tile or charts whenever applicable:

• 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 grade 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.
• aggregation: (sum or average), tile will aggregate the application background fact values using sum or average - default value is sum. For example: if you have two Applications visible in the Health Dashboard and have configured a Background Fact (a Cost of 400 for example) for only one of the Applications, results will be displayed as follows:
  • AVERAGE: A value of 200 will be displayed in the tile at Multi-application level (400 divided by 2) and in the tiles at Application level.
  • SUM: A value of 400 will be displayed in the tile at Multi-application level and at Application level, 400 will be displayed for the Application for which the Background Fact has been uploaded and 0 for the Application for which no Background Fact has been uploaded.

Example (for cmp.json)

        {
            "id": 66002,
            "plugin": "BackgroundFactsResults",
            "color": "green",
            "parameters": {
                "url":"http://www.castsoftware.com",
                "aggregation":"sum",
                "title": "Cost",
                "backgroundFact": {
                	"id": "66002",
                	"format": "0.0",
                	"description": "Total cost value"
                }
            }
         },

Example (for app.json)

				{
                    "id": 39,
                    "plugin": "BackgroundFactsResult",
                    "color": "black",
                    "parameters": {
                        "title": "Number of incidents",
                        "url":"http://www.castsoftware.com",
                        "aggregation":"sum",
                        "backgroundFact": {
                            "id": "66061",
                			"format": "0,000a",
                            "description":""
                         }
                     }
                }

Example Background Facts configuration

In this example, there are two Applications present in the Health Dashboard. Background Facts have been configured and uploaded (see Background Facts and Business Value Metric upload for more information) for one of the Applications as shown below. The tile has been designed to show information about the Cost (66002) metric (see example plugin for cmp.json).

<?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

A tile that enables you to display the evolution of Background Facts that you have manually configured and uploaded during the snapshot generation. The tile can display information about one metric that you have defined in the uploaded Background Facts file.

1. backgroundFact: see the BackgroundFactsResult/BackgroundFactsResults tile above for more info.
2. aggregation; see the BackgroundFactsResult/BackgroundFactsResults tile above for more info.
3. widget: provides the rendering type (number for number variation, line or spline for trend chart representation: line uses with straight lines whereas spline provides smooth transitions between points)
4. selectedApplicationCount defines the number of applications selected by default in the drill down at detail level page when the tile is defined at multi-application level (cmp.json).

Clicking the tile

When defined at single application level (app.json), clicking a tile will by default display the evolution of TQI. When defined at multi-application level (cmp.json), clicking a tile will display the following Background Fact detail for the Applications in scope:

Example (for cmp.json or app.json):

{
                "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

1. qualityIndicator: information about the indicator to display (as x axis) : its id, format and an eventual description

2. id is either: ARCHITECTURAL_DESIGN, CHANGEABILITY, DOCUMENTATION, PERFORMANCE, PROGRAMMING_PRACTICE, ROBUSTNESS,SEI_MAINTAINABILITY, SECURITY, TQI, TRANSFERABILITY

3. id can also be a numerical ID corresponding to any CAST AIP metric

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. description is whatever is required

6. sizingMeasure: information about the indicator to display (as bubble size): its id, format and an eventual description

   1. id is either: TECHNICAL_DEBT, LINES_OF_CODE, NUMBER_OF_ARTIFACTS, NUMBER_OF_COMMENT_LINES, NUMBER_OF_DECISION_POINTS, NUMBER_OF_FILES, AUTOMATED_IFPUG_FUNCTION_POINTS_ESTIMATION, BACKFIRED_IFPUG_FUNCTION_POINTS and CRITICAL_VIOLATIONS
   2. id can also be a numerical ID corresponding to any CAST AIP metric
   3. 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)
   4. description is whatever is required

7. backgroundFact:  information about the indicator to display (as y axis) : its id, format and an eventual description

8. id is either: BUSINESS_VALUE, COST, DELIVERY_FEATURE_REQUESTS, EFFORT, ENHANCEMENT_FUNCTION_POINTS, PENDING_FEATURE_REQUESTS, and PENDING_FIXES

9. id can also be a numerical ID corresponding to any CAST AIP metric

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

11. description is whatever is required

12. chartSettings: information about the displayed graph. It is described by the highcharts library (cf. http://api.highcharts.com/highcharts for available description)

    1. xAxis and yAxis refers to the chart axis
    2. plotLines: An array of lines streching across the plot area, marking a specific value on one of the axes:
       1. value: the position of the line in axis units.
       2. color: the color of the plot band.
       3. label: text labels for the plot bands
          1. align: horizontal alignment (“left”, “center” or “right”)
          2. text: The string text itself. A subset of HTML is supported.
          3. textAlign: The text alignment for the label determines how the text is aligned against its anchor point. Possible values are “left”, “center” and “right”.
          4. verticalAlign: Vertical alignment of the label relative to the plot band. Can be one of “top”, “middle” or “bottom”. Defaults to top.
    3. plotBands: An array of colored bands stretching across the plot area marking an interval on the axis:
       1. from: the start position of the plot band in axis units.
       2. to: the end position of the plot band in axis units.
       3. color: the color of the plot band.
       4. label: text labels for the plot bands
          1. align: horizontal alignment (“left”, “center” or “right”)
          2. text: The string text itself. A subset of HTML is supported.
          3. textAlign: The text alignment for the label determines how the text is aligned against its anchor point. Possible values are “left”, “center” and “right”.
          4. verticalAlign: Vertical alignment of the label relative to the plot band. Can be one of “top”, “middle” or “bottom”. Defaults to top.

Example:

			{
                "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

This tile shows the top 5 critical rules at Application or multi-Application level, together with:

• Checked column: the number of times the rule has been checked - i.e. the number of objects checked by the Quality Rule
• Failed (%)orFailed (#) column: the percentage or number of checks that have failed - i.e. percentage or number of objects checked by the Quality Rule that violate the Quality Rule

Configuration:

1. type: Describe the type of notifications - set totopRules

2. count: the number of lines displayed. 5 is the optimized size for the height of the tile

3. order: the ordering of the Quality Rules represented in the tile. This can be descending or ascending, and is based on the number of failed checks

4. format: the format of the compliance value: it uses the the format defined in numeral.js  (see http://numeraljs.com/ for available Numbers formats)

5. mode: two options are possible:

   • “ratio”: a Failed (%) column will display a percentage of the checks that have failed - i.e. percentage of objects checked by the Quality Rule that violate the Quality Rule.
   • “number”: a Failed (#) column will display the number of the checks that have failed - i.e. the number of objects checked by the Quality Rule that violate the Quality Rule.

6. loadLimit: Compared to other tiles, this tile tends to involve large amount of data when the application scope increases, hence can quickly prove to be performance inefficient; theloadLimit option defines a limit for the number of applications: when there are less Applications than the loadLimit value, then the contents of the tile will be loaded. When there are more Applications than the loadLimit value, then the contents of the tile will not be loaded and a message will state this.

Example (for cmp.json):

            {
                "id": 14,
                "plugin": "CriticalQualityRulesRatios",
                "size":"large",
                "color": "grey-dark",
                "parameters": {
                    "loadLimit": 60,
                    "title": "Top 5 critical rules",
                    "count": 5,
                    "order": "descending",
                    "format": "0,000",
                    "mode": "ratio"
                }
            }

Example (for app.json):

                {
                    "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:

1. count: the number of lines displayed. 5 is the optimized size for the height of the tile. This parameter is only taken into account for topRiskiest tile types.
2. order: the ordering of the data represented in the tile. This can be descending or ascending, and is based on the sizing measure
3. qualityIndicator: this is identical to the indicator of the singleQualityIndicator tile :

   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)

      Info

From, v. ≥ 2.5.0-funcrel the mode option is available.