OMG-CTDM - 2.0

Extension ID

com.castsoftware.omg-atdm

What's new?

See OMG-CTDM - 2.0 - Release Notes.

Description

Release ≥ 2.x of this extension uses CTDM (Contextual Technical Debt Measure) to calculate Technical Debt values. CTDM is a recognized nomenclature for a customized ATDM (Automated Technical Debt Measure) as described in chapter 6.3 of the OMG ATDM specification 1.0, see: https://www.omg.org/spec/ATDM/1.0/PDF. For this extension, CTDM uses a combination of remediation effort produced by the ISO-5055 measure and remediation effort produced by CAST Imaging Core. This means that the number of rules taken in to account by this release of the extension is higher than in release 1.x of the extension (ATDM), which only considered "CISQ" Business Criteria. As a direct result, Technical Debt values will be higher for release ≥ 2.x of the extension and are therefore not comparable with release 1.x. You can see a list of Technical Criteria used by the extension below.

The technical debt values are computed for all violations which have an entry with a remediation effort at Business Criteria or Rule level. Effort is taken in to account in the following order:

• Rule 
• CISQ index (if the com.castsoftware.cisq-index extension is installed) 
• ISO-5055 index
• CAST Imaging Core (TQI)

Therefore:

• If an effort exists at rule level, then this effort is applied for the rule 
• If an effort exists at CISQ level then this effort is applied 
• if an effort exists for the rule at ISO-5055 level then this effort is applied
• otherwise effort from CAST Imaging Core is applied.

Technical Debt is calculated as follows: at the object/rule level and then aggregated at Rule, Technical Criterion, Business Criterion, Module and Application level. The details at rule level are computed on demand by default, this means the results are not stored at the object and rule level - this is to reduce the volume of generated data and to improve performance.

Compatibility and requirements

Product	Release	Required	Notes
CAST Imaging Core	≥ 8.3.34		For 8.3.34 - 8.3.36, ISO remediation efforts are not available, however, default ISO remediation efforts (as provided in 8.3.37) will be used instead.
Dashboard/RestAPI	≥ 2.3.1		-
com.castsoftware.omg-ascqm-index	Any	Recommended	If the ISO-5055 extension is not installed, only the Technical Criteria from CAST Imaging Core will be used to generate the Technical Debt values.
com.castsoftware.cisq-index	Any	Optional	Only required if you want to ALSO view ATDM values (which are based on CISQ Index) as in version 1.x.

OMG-ATDM version

Version	Supported
2.0 (October 2021)

Download and installation instructions

The extension will not be automatically downloaded and installed in CAST Imaging Console. If you need to use it, should manually install the extension.

Assessment Model

The extension calculates the following metrics as Sizing Measures:

How are results calculated?

Predefined Un-Adjusted Remediation Effort

Configuration data is loaded to have the remediation effort for each pattern ( CISQ, ISO-5055, CAST TQI ). This is called Un-Adjusted Remediation Effort. The unit of effort is minute. The effort taken in to account by CTDM for each pattern is EFFORT_DEFAULT. E.g.:

Un-Adjusted Remediation Effort
STANDARD : CISQ
PATTERN : ASCPEM-PRF-15
EFFORT_DEFAULT: 90
EFFORT_MIN: 30
EFFORT_MAX: 210
EFFORT_UNIT: MIN 

Un-Adjusted Remediation Effort
STANDARD : ISO-5055
PATTERN : CWE-125
EFFORT : 30

Scope

• For each of the violations, the number of occurrences and related objects are collected, with related technologies.
• For a violation of type Bookmark, the number of occurrences corresponds to the number of bookmarks and the related object is the main object of the violation.
• For a violation of type Path, the number of occurrences corresponds to the number of paths, and the related objects are the main object of the violation, plus all related objects in the path(s)

The table below lists the Technical Criteria used by this extension:

Qualification information

Complexity

The Complexity - or Effort Complexity - of the code elements implementing an Occurrence is qualification information that is measured according to the Effort Complexity definition from Automated Enhancement Points:

EC/LowEffortComplexity

EC is computed by the following metrics:

• 10351: EC ADDED
• 10353: EC UPDATED
• 10354: EC UNCHANGED

LowEffortComplexity

The technology related Low Complexity column for ADDED artifacts ( from COST_CONFIG ). When the violation has related objects, then the average EC of all objects is taken in to account. The complexity is computed for the main object violating a rule:

Complexity = AVG ( Effort Complexity all objects of the violation )/ Low Complexity for the related technology

Concentration

Concentration is qualification information that measures the number of Occurrences within any Code Element in the software:

1/nb of time the object violates any rule

Exposure

The Exposure of an Occurrence is qualification information that measures the level of contentedness of the Occurrence with the rest of the software, both directly and indirectly through call paths:

1+log(nb paths)

Technical diversity

The Technological Diversity of an Occurrence measures the number of distinct technologies in which the code elements included in a single occurrence of a source code pattern are written. This is set to 1. 

Gap size

In the context of patterns which rely on roles that model values and threshold values that are not to be exceeded, the gap between these values must be closed to re-mediate this weakness. This is set to 1. 

Adjustment Factor

The adjustment factor is computed based on qualification information, as follows:

AVG(Complexity) X AVG(Exposure) X Count(Technological diversity) X AVG(Concentration) X Sum(Gap size)

Technical debt

Finally the technical debt is computed by:

Nb Of Occurrences X Adjustment Factor X Un-adjusted Remediation Effort

Result storage

Default result storage method - high level data only

By default only data aggregated at the following level is available and is stored in the Dashboard schema table DSS_METRIC_RESULTS:

• Application
• Module
• Technical Criteria
• Business Criteria

Detailed information at Object and Rule level can be generated and made available to the dashboard on demand by executing the following query against the Dashboard schema:

select OMG_ATDM_COMPUTE_DETAILS (SNAPSHOT_ID, OBJECT_ID, RULE_ID) 

Where:

When the next snapshot is generated, detailed object/rule level information will be saved in the table OMGTD_RESULTS.

Alternative result storage method - all data

It is possible to change the behaviour and choose to always save all results (including Object and Rule level information) for every snapshot that is generated. To do so, execute the following query against the Dashboard schema:

select OMG_ATDM_DETAILSALL();

This option will be taken in account when a new snapshot is generated and as a result all information is saved as follows:

• Application, Module, Technical Criteria, Business Criteria - aggregated in the table DSS_METRIC_RESULTS
• Details for Object and Rule levels stored in the table OMGTD_RESULTS 

To disable the storage of all details, execute the following query against the Dashboard schema:

select OMG_ATDM_DETAILSONDEMAND();

What results can you expect?

Health Dashboard

When the ISO-5055 view is selected, two tiles are available out of the box in the Overview and Trends sections respectively, at Multi-Application level (the tiles will display no value if the OMG Technical Debt extension is not installed and no snapshot has been generated):

At single Application level, one tile is available out of the box in the Overview section when the ISO-5055 view is selected:

Switch between the AIP and ISO-5055 views using the drop down in the home page:

Clicking the tiles will provide more detailed information:

Multi Application level

Single Application level

In addition, at single Application level drill down, for each of the Source Code Pattern Names, it is possible to navigate to the details of the violations in the Engineering Dashboard (where this has been setup):

SizingMeasureResult (app-ISO.json) / SizingMeasureResults (cmp-ISO.json):

        {
          "id": 208,
          "plugin": "SizingMeasureResult",
          "color": "yellow",
          "parameters": {
            "title": "Technical Debt (OMG) by ISO-5055",
            "sizingMeasure": {"id": "OMG_TECHNICAL_DEBT_ISO", "format": "0,0", "description": "Days"}
          }
        },
        {
          "id": 998,
          "plugin": "SizingMeasureResult",
          "color": "yellow",
          "parameters": {
            "title": "Technical Debt (OMG) by CISQ",
            "sizingMeasure": {"id": "OMG_TECHNICAL_DEBT_CISQ", "format": "0,0", "description": "Days"}
          }
        },
        {
          "id": 999,
          "plugin": "SizingMeasureResult",
          "color": "yellow",
          "parameters": {
            "title": "Technical Debt (OMG) by TQI",
            "sizingMeasure": {"id": "OMG_TECHNICAL_DEBT", "format": "0,0", "description": "Days"}
          }
        },  

SizingMeasureEvolution (app-ISO.json and cmp-ISO.json):

        {
          "id": 2103,
          "plugin": "SizingMeasureEvolution",
          "color": "yellow",
          "parameters": {
            "widget":"line",
            "title": "Technical Debt (OMG) by ISO-5055",
            "sizingMeasure": {"id": "OMG_TECHNICAL_DEBT_ISO", "format": "0,0"}
          }
        },
        {
          "id": 9998,
          "plugin": "SizingMeasureEvolution",
          "color": "yellow",
          "parameters": {
            "widget":"line",
            "title": "Technical Debt (OMG) by CISQ",
            "sizingMeasure": {"id": "OMG_TECHNICAL_DEBT_CISQ", "format": "0,0"}
          }
        },
        {
          "id": 9999,
          "plugin": "SizingMeasureEvolution",
          "color": "yellow",
          "parameters": {
            "widget":"line",
            "title": "Technical Debt (OMG) by TQI",
            "sizingMeasure": {"id": "OMG_TECHNICAL_DEBT", "format": "0,0"}
          }
        },

Engineering Dashboard

A tile is available out of the box displaying the Total Technical Debt (OMG) in days for the current Application, as well as Added and Removed OMG Technical Debt in days for the current snapshot:

You can change the specific Technical Criteria used to display the values in the tile, using the drop down option:

By default, this tile is configured to display ISO-5055 index data (using the 1061000 metric ID). If you want to display either TQI (CAST Imaging Core) or CISQ Index values (if the extension is installed), you will need to manually edit the configuration in the ed.json file and change the ID used - see Engineering Dashboard tile management for more information:

• 1061000 - based on ISO-5055 index data, installed by default in CAST Imaging Console
• 1062100 - based on CISQ Index data, requires that the com.castsoftware.cisq-index is installed
• 60017 (based on TQI from CAST Imaging Core)

Clicking this tile will drill down to the Risk investigation view with Technical Debt (OMG) with the ISO-5055 Assessment Model selected. If the tile has been manually edited and re-configured to show either TQI (CAST Imaging Core) or CISQ Index data, the drill down will also change as shown below:

You can also switch to showing Violations instead of Technical Debt (OMG) values from the drop-down list:

In the rule details section, there is a dedicated section called "Technical Debt (OMG)", which will show the details (Total, Added, Removed, and No. of occurrences):

In the source code view, a Technical Debt (OMG) section is displayed, showing object level details on the Adjustment Factor, Unadjusted Effort (in mins) and Adjusted Efforts (in mins):

Using the RestAPI to obtain results

Total Technical Debt by Application, Module

Results can be obtained using a RestAPI query. For example, to obtain technical debt as a remediation effort use the metric #1062020 (you can replace this ID with other supported Sizing Measure IDs):

AAD/results?metrics=1062020&modules=$all&technologies=$all

Example showing the technical debt for all applications, with a breakdown by technology and by module for an example Application called "shopizer8321":

C:>curl -H "Accept: text/csv" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/AAD/results?metrics=1062020&modules=$all&technologies=$all"

Results:

Application Name;Module Name;Technology;Metric Name;Metric Id;Metric Type;Critical;Snapshot Date #1;Result #1
shopizer8321;null;null;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;387350.0
shopizer8321;null;HTML5;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;770.0
shopizer8321;null;JEE;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;386580.0
shopizer8321;shopizer8321 full content;null;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;387350.0
shopizer8321;shopizer8321 full content;HTML5;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;770.0
shopizer8321;shopizer8321 full content;JEE;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;386580.0

In other words, the "shopizer8321" application has a technical debt of 387350 minutes, which is equivalent to 387350 ÷ 60 ÷ 8 = 806 workload days. The remediation effort is dispatched between HTML5 code and Java Code as follows:

Total Technical Debt by Business Criterion, Technical Criterion, Rule

With a CISQ Business Criterion ID, you can obtain the technical debt for this Quality Indicator and all related indicators (ie CISQ Measure Elements):

Example:

C:>curl -H "Accept: text/csv" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/SHOPIZER/applications/3/results?metrics=c:1062100&select=omgTechnicalDebt"

Application Name;Technical Criterion;Metric Id;Metric Type;Critical;Snapshot Date #1;Result #1;OMG Technical Debt (Result #1);OMG Occurrences (Result #1);OMG Added Technical Debt (Result #1);OMG Removed Technical Debt (Result #1)
shopizer8321;ASCMM-MNT-1 - Control Flow Transfer Control Element outside Switch Block;1062110;technical-criteria;false;2020-05-15;4.0;0;2;0;0
shopizer8321;ASCMM-MNT-11 - Callable and Method Control Element Excessive Cyclomatic Complexity Value;1062112;technical-criteria;false;2020-05-15;3.58017346587814;null;null;null;null
shopizer8321;ASCMM-MNT-12 - Named Callable and Method Control Element with Layer-skipping Call;1062113;technical-criteria;false;2020-05-15;4.0;null;null;null;null
shopizer8321;ASCMM-MNT-13 - Callable and Method Control Element Excessive Number of Parameters;1062114;technical-criteria;false;2020-05-15;4.0;null;null;null;null
shopizer8321;ASCMM-MNT-15 - Public Member Element;1062116;technical-criteria;false;2020-05-15;4.0;40;1;0;0
...

You can get also the technical debt for a single rule, as long as this rule is identified as a CISQ rule by the CISQ Index:

C:>curl -H "Accept: application/json" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/SHOPIZER/applications/3/results?metrics=8216&select=omgTechnicalDebt,violationRatio"


...
				"result": {
					"grade": 4,
					"omgTechnicalDebt": {
						"total": 11040,
						"numberOccurrences": 176,
						"added": 0,
						"removed": 0
					},
					"violationRatio": {
						"totalChecks": 7411,
						"failedChecks": 33,
						"successfulChecks": 7378,
						"ratio": 0.9955471596275807
					}
				},

Detailed Technical Debt for a violation

As we refer to findings from a snapshot ID, and object ID and a rule ID with URI such as:

TINY/components/568/snapshots/8/findings/8216

We can refer technical debt details in a similar Web Service:

TINY/components/568/snapshots/8/omg-technical-debt/8216

E.g.:

C:>curl -H "Accept: application/json" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/TINY/components/568/snapshots/8/omg-technical-debt/8216"
{
	"total": 180,
	"numberOccurrences": 3,
	"complexity": 1,
	"exposure": 1,
	"concentration": 0,
	"technologicalDiversity": 1,
	"gapSize": 1,
	"unadjustedEffort": 60,
	"added": 0,
	"removed": 0,
	"adjustmentFactor": 3
}

Querying the Dashboard schema for results

The Dashboard schema contains views and tables that provide information about the results generated by this extension:

Obtaining results at Application level for a snapshot

SET search_path=xxx_central;
SELECT * 
FROM   omg_atdm_results_obj_app 
WHERE  snapshot_id = <snapshot_id>

Obtaining results per CAST Rule / CISQ Pattern at the application level for a snapshot

Possible STANDARD values are 'CISQ' , 'ISO-5055', 'AIP'. CISQ Total:

SET search_path=xxx_central;
SELECT TD.SNAPSHOT_ID,  TD.OBJECT_NAME as APPLICATION_NAME,
sum(case when TD.METRIC_ID = 1062020 then TD.METRIC_NUM_VALUE else 0 end) tech_debt,
sum(case when TD.METRIC_ID = 1062030 then TD.METRIC_NUM_VALUE else 0 end) tech_debt_added,
sum(case when TD.METRIC_ID = 1062032 then TD.METRIC_NUM_VALUE else 0 end) tech_debt_removed
FROM OMG_ATDM_RESULTS_OBJ_RULE_APP TD
join DSS_SNAPSHOTS S on S.SNAPSHOT_ID = TD.SNAPSHOT_ID and TD.OBJECT_ID = S.APPLICATION_ID
Where TD.METRIC_VALUE_INDEX in ( select METRIC_ID from OMG_METRIC_VIEW where STANDARD = 'CISQ')
And TD.SNAPSHOT_ID = <SNAPSHOT_ID>
And TD.METRIC_ID in ( 1062020,1062030, 1062032 ) -- Remediation Effort Total, added, deleted
Group by TD.SNAPSHOT_ID, TD.OBJECT_NAME

CISQ Technical Criteria:

SET search_path=xxx_central;
SELECT TD.SNAPSHOT_ID, TD.METRIC_VALUE_INDEX , TD.AGGREGATELEVEL , TD.OBJECT_NAME as APPLICATION_NAME, 
      sum(case when TD.METRIC_ID = 1062020 then TD.METRIC_NUM_VALUE else 0 end) tech_debt,
      sum(case when TD.METRIC_ID = 1062030 then TD.METRIC_NUM_VALUE else 0 end) tech_debt_added,
      sum(case when TD.METRIC_ID = 1062032 then TD.METRIC_NUM_VALUE else 0 end) tech_debt_removed 
FROM  OMG_ATDM_RESULTS_OBJ_RULE_APP TD
join DSS_SNAPSHOTS S on S.SNAPSHOT_ID = TD.SNAPSHOT_ID and TD.OBJECT_ID = S.APPLICATION_ID
Where TD.METRIC_VALUE_INDEX in ( select METRIC_ID from CTDM_REMEDIATION_EFFORTS where STANDARD = 'CISQ')
And TD.SNAPSHOT_ID = <SNAPSHOT_ID>
And TD.METRIC_ID in ( 1062020,1062030, 1062032 ) -- Remediation Effort Total, added, deleted
Group by  TD.SNAPSHOT_ID, TD.METRIC_VALUE_INDEX , TD.AGGREGATELEVEL , TD.OBJECT_NAME
Order by TD.METRIC_VALUE_INDEX 

CISQ Business Criterion:

SELECT TD.SNAPSHOT_ID, TD.METRIC_VALUE_INDEX , TD.AGGREGATELEVEL , TD.OBJECT_NAME as APPLICATION_NAME,
      sum(case when TD.METRIC_ID = 1062020 then TD.METRIC_NUM_VALUE else 0 end) tech_debt,
      sum(case when TD.METRIC_ID = 1062030 then TD.METRIC_NUM_VALUE else 0 end) tech_debt_added,
      sum(case when TD.METRIC_ID = 1062032 then TD.METRIC_NUM_VALUE else 0 end) tech_debt_removed
FROM  OMG_ATDM_RESULTS_OBJ_RULE_APP TD
join DSS_SNAPSHOTS S on S.SNAPSHOT_ID = TD.SNAPSHOT_ID and TD.OBJECT_ID = S.APPLICATION_ID
Where TD.METRIC_VALUE_INDEX in ( select BC_METRIC_ID from OMG_BC_METRIC_VIEW BC join  CTDM_REMEDIATION_EFFORTS TC on TC.STANDARD = 'CISQ' and TC.METRIC_ID =BC.PATTERN_METRIC_ID )
And TD.SNAPSHOT_ID = <SNAPSHOT_ID>
And TD.METRIC_ID in ( 1062020,1062030, 1062032 ) -- Remediation Effort Total, added, deleted
Group by  TD.SNAPSHOT_ID, TD.METRIC_VALUE_INDEX , TD.AGGREGATELEVEL , TD.OBJECT_NAME
Order by TD.METRIC_VALUE_INDEX

For example to get the results for all metrics of pattern 'ASCPEM-PRF-8':

SELECT * 
FROM   omg_atdm_results_obj_rule_app 
WHERE  snapshot_id = 4 
       AND ( metric_value_index IN (SELECT T.metric_id + 1 
                                    FROM   aed_metric_quality_tags T 
                                    WHERE  T.tag = 'ASCPEM-PRF-8') 
              OR aggregatelevel = 'ASCPEM-PRF-8' ) 

Note that to obtain the CISQ Pattern of a given CAST rule, you can adapt the following query. For example, to find the CISQ Pattern for the rule ID = 7201, the following query will return ASCPEM-PRF-8:

SELECT C.tag 
FROM   aed_quality_tags_doc C 
       join aed_metric_quality_tags T 
         ON T.tag = C.tag 
WHERE  C.standard = 'CISQ' 
       AND T.metric_id + 1 = 7201