Created by James Hurrell, last modified on Jun 27, 2023

Summary: This page provides information about the Action Plan Recommendation feature.

Introduction

The Action Plan Recommendation is a feature designed to help you automatically build an Action Plan to improve the grade/score of a chosen Health Factor (Business Criteria). In short, for a given Health Factor, you can configure one of the "remediation targets" listed below and the Action Plan Recommendation will automatically suggest a list of violations to be added to the Action Plan for future correction. The correction of the suggested violations will match the desired remediation target when a new snapshot is generated and therefore improve the grade of the chosen Health Factor. Available remediation targets:

  • the grade you want to achieve with a minimum of violations to fix, OR
  • the grade you want to achieve with the minimum of effort in man/days required to fix the violations OR
  • the number of violations you want to fix, OR
  • the amount of effort in man/days you would like to "spend" on fixing the violations
  • The feature requires a login with the QUALITY_MANAGER role.
  • This feature supports Health Factors introduced by the following industry standard extensions:
  • The Compliance Score option is supported in AIP versions ≥ 8.3.29
  • This feature does not work for old snapshots (the "APR" and "download data as excel file" icon  are disabled).

How does it work?

The Action Plan Recommendation uses an optimization algorithm to build an Action Plan according to the target you want to achieve. This algorithm functions as follows for each of the available remediation targets:

  • you select a specific grade/score for a given Health Factor and choose the "Minimize violations" option: Action Plan Recommendation will search for an Action Plan (i.e. a list of violations) both to reach this grade and to minimize the number of violations to fix.
  • you select a specific grade/score for a given Health Factor and choose the "Minimize effort" option: the system will search for an Action Plan (i.e. a list of violations) both to reach this grade and to minimize the total effort required to fix the violations.
  • you select a specific number of violations to fix: the system will search for an Action Plan (i.e. a list of violations) that matches (where possible) the selected number of violations and that maximizes the grade/score of the chosen Health Factor.
  • you select a specific effort: the system will search for an Action Plan (i.e. a list of violations) that matches with the selected total effort and that maximizes the grade/score of the chosen Health Factor.

This algorithm attempts to solve a "combinatorial optimization problem". This means that the perfect solution (i.e. Action Plan or list of violations) is unknown, and the algorithm will try to find the very best solution it can by selecting the best result using the three heuristics (grade/score, number of violations and effort). As a result, the algorithm may find a solution (i.e. Action Plan or list of violations) which may differ slightly from your requested remediation target.

Notes:

  • As soon you re-select or deselect a rule in the interface the algorithm will recompute the action plan recommendation. Depending on the rules you have already excluded, some rules may be added/removed by the algorithm compared to a previous recommendation.
  • The effort is calculated for a number of objects and does not depend on the number of objects to fix (especially for cost complexity).
  • An effort "unit" is set by a hard coded rule. The value of the effort unit depends on the parent Technical Criterion of the rule.
  • By default, all rules that belong to the same Technical Criterion are set with the same effort unit.
  • By default, an initial remediation target is set when the interface is first opened - this is to correct one violation - if you already have violations added to Action Plan, this initial remediation target will be set to correct one additional violation.

Calculation of the remediation effort

The remediation effort of a rule is determined as follows:

  • For ISO rules the remediation effort applied is deduced from its ISO characteristic
  • For CISQ rules, the remediation effort applied is deduced from its CISQ characteristic
  • For other rules, the remediation effort applied is deduced from the technical criterion of the rule (see the table below) 

For a rule, the total remediation effort proposed by the Action Plan Remediation feature is: (the remediation effort) x (average number of occurrences of violations) x (number of violations to be corrected).

The total remediation effort

The remediation effort is an estimate to be used to select an action plan. It cannot claim to have a predictive value. In reality, it is necessary to take into account the technology (a C++ remediation effort will be different from a COBOL remediation), the development practices (unit tests, integration tests, etc.), the level of competence of the teams, the functional or technical complexity (backend, frontend).

Default efforts by technical criterion:


Technical Criteria

Evaluation

Impact

Low effort

Documentation - Naming Convention Conformity
Documentation - Style Conformity
Complexity - Empty Code
Documentation - Bad Comments
Documentation - Automated Documentation

12 minutes (0.2 x 60 minutes)

Local impact

Low Effort

Documentation - Volume of Comments
Dead code (static)
Programming Practices - Structuredness'

24 minutes (0.4 x 60 minutes)

Local impact

Intermediate Effort

Complexity - Dynamic Instantiation
Secure Coding - Weak Security Features
Secure Coding - API Abuse,

30 minutes = (0.5 x 60 minutes)

Local Impact & Sensitive changes

Intermediate Effort

Programming Practices - Unexpected Behavior'
Programming Practices - Error and Exception Handling
Volume - Number of LOC
Programming Practices - File Organization Conformity
Programming Practices - OO Inheritance and Polymorphism
Architecture - Multi-Layers and Data Access
Programming Practices - Modularity and OO Encapsulation Conformity
Complexity - Algorithmic and Control Structure Complexity
Complexity - Technical Complexity
Secure Coding - Encapsulation
Secure Coding - Input Validation
Secure Coding - Time and State
Architecture - OS and Platform Independence
Volume - Number of Components
Efficiency - Memory, Network and Disk Space Management

1 hour = (1 x 60 minutes)

Global Impact & Sensitive Change

High Effort

Efficiency - SQL and Data Handling Performance
Complexity - SQL Queries
Efficiency - Expensive Calls in Loops
Complexity - Functional Evolvability

2 hours = (2 x 60 minutes)

Very Sensitive changes

High Effort

Complexity - OO Inheritance and Polymorphism
Volume - Number of Components
Architecture - Object-level Dependencies
Architecture - Reuse
Efficiency - Memory, Network and Disk Space Management

3 hours= (3 x 60 minutes)


The difference with the OMG Technical Debt calculation is as follows:

  • OMG Technical Debt is limited to CISQ, while the Action Plan Remediation feature makes a calculation for all CISQ and non-CISQ rules (except if one explicitly selects the CISQ scope). 
  • OMG Technical Debt is adjusted for each object according to its characteristics (e.g. cyclomatic complexity) - the Action Plan Remediation feature does not make this adjustment due to calculation time.
  • OMG Technical Debt is adjusted as close as possible to the number of occurrences of violations - the Action Plan Remediation feature is based on an average of occurrences of violations for reasons of calculation time.

Accessing the Action Plan Recommendation

The Action Plan Recommendation feature can be accessed from the Action Plan using the icon in the top right corner:

Action Plan Recommendation interface

Click to enlarge

Select Health Measure

This option provides a drop down list of the available Health Factors to target for grade improvement. By default the Total Quality Index Health Factor will be selected. Choose the required Health Factor in the drop down:

  • If you have filterHealthFactor set to false, additional Health Factors will be displayed.
  • This feature supports Health Factors introduced by the following industry standard extensions:
  • In case of Industry Standards, Grade option is hidden.
Mimimize Violations / EffortThis option allows you to choose whether your target remediation will focus on minimizing the number of violations to fix, or minimizing the amount of effort in man/days required to fix the violations. By default, Violations will be selected meaning that the Action Plan Recommendation will attempt to suggest an Action Plan (i.e. list of violations) that meets the target remediation you set whilst minimizing the total number of violations to fix.
Improve Total Quality Index

This option allows you to Improve Total Quality Index  by choosing either Grade or Compliance (in%), from the drop-down.

Grade slider

The grade slider indicates the target grade you would like to achieve for the chosen Health Factor (grades go from 1 (worst) to 4 (best)):

  • When the Action Plan Recommendation is first opened, the slider will indicate a target grade based on the default initial remediation target to correct one violation.
  • You can manually move the slider by clicking the circle and dragging it to a new position - this is a quick method to build an action plan based simply on a target grade.
  • The Action Plan Recommendation will recalculate the suggested Action Plan each time you move the slider.
  • The target grade shown by the slider will match the target grade shown in the Grade manual entry box (see below).
Compliance (in %) slider

The Compliance slider indicates the target Compliance (in %) you would like to achieve for the chosen Health Factor (Compliance percentage go from 0 (worst) to 100 (best)):

When you select Compliance (in %) from the Improve Total Quality Index drop-down, Minimize (Violations and Effort) option gets disabled.

  • You can manually move the slider by clicking the circle and dragging it to a new position - this is a quick method to build an action plan based simply on a target grade.
  • The Action Plan Recommendation will recalculate the suggested Action Plan each time you move the slider.
  • The Compliance (in %) shown in the slider will match the Target Compliance shown in the Compliance manual entry box (see below)
Select a Module

This option provides the drop down list of the available Modules, by default "All Modules" is selected. Users can specify the improvement scope to the application, which is the "All Module" option, or any particular module can be selected from the module dropdown.


Grade manual entry

This option indicates the target grade you would like to achieve for the chosen Health Factor (grades go from 1 (worst) to 4 (best)):


  • When the Action Plan Recommendation is first opened, the box will indicate a target grade based on the default initial remediation target to correct one violation - if you already have violations added to Action Plan, this initial remediation target will be set to correct one additional violation.
  • You can manually change the grade in the box using the up/down buttons or by manually entering the grade - this is a quick method to build an action plan based simply on a target grade:

  • The Action Plan Recommendation will recalculate the suggested Action Plan each time you change the value in the box.
  • The target grade shown in the box will match the target grade shown on the Grade slider (see above).
Compliance manual entry

This option indicates the target Compliance you would like to achieve for the chosen Health Factor (Compliance percentage go from 0 (worst) to 100 (best)):

  • When the Compliance is selected the first time, the box will indicate a target Compliance based on the default initial remediation target to correct one violation - if you already have violations added to Action Plan, this initial remediation target will be set to correct one additional violation.
  • You can manually change the Compliance percentage in the box using the up/down buttons or by manually entering the grade - this is a quick method to build an action plan based simply on a target Compliance: 

  • The Action Plan Recommendation will recalculate the suggested Action Plan each time you change the value in the box.
  • The target Compliance shown in the box will match the target Compliance shown on the Compliance slider (see above).
Violation manual entry

This option indicates the number of violations that you want to fix:

  • When the Action Plan Recommendation is first opened, the box will indicate a default initial remediation target to correct one violation - if you already have violations added to Action Plan, this initial remediation target will be set to correct one additional violation.
  • You can manually change the number of violations in the box using the up/down buttons or by manually entering the number - this is a quick method to build an action plan based simply on the number of violations you want to correct:

  • The Action Plan Recommendation will recalculate the suggested Action Plan each time you change the value in the box.
Effort manual entry

This option indicates the amount of effort in man/days you would like to "spend" on fixing the violations:

  • When the Action Plan Recommendation is first opened, the box will indicate a target effort in man/days based on the default initial remediation target to correct one violation - if you already have violations added to Action Plan, this initial remediation target will be set to correct one additional violation.
  • You can manually change the amount of effort in the box using the up/down buttons or by manually entering the number - this is a quick method to build an action plan based simply on the amount of effort you would like to "spend" on fixing the violations:

  • The Action Plan Recommendation will recalculate the suggested Action Plan each time you change the value in the box.
FINALIZE

The FINALIZE button will add all the violations for selected rules into the Action Plan. In the following example, 7 violations have been added to the Action Plan:

Click to enlarge

Note that the Comment in the Action Plan will be populated automatically and will describe the target remediation, for example:

Recommended action plan for Total Quality Index score improvement from 3.12 to 3.30

Click to enlarge

Exclude previously selected criterias (available in ≥ 2.11.3)

This option (when enabled) will exclude all rules that have ALREADY been added to the Action Plan, i.e. enabling the option will remove all rules from the recommendation list that are already listed in Action Plan. By default the option is not enabled, therefore you may find that rules that you have already added to the Action Plan will be listed in the Recommendation List:

Action Plan Recommendation list

This section lists the rules that the Action Plan Recommendation algorithm thinks are the best match for the target remediation. You can sort each column in ascending or descending order by clicking on the column header.

Check boxes

The check boxes enable you to choose whether you want the violations for a specific rule to be added to the Action Plan or not. By default, all check boxes will be selected - meaning that all violations for all rules will be added to the Action Plan. If you do not want to fix violations for a specific rule, de-select the associated check box.

In the following example, we do not want to fix the violations of the rule Avoid using javascript or expression in the CSS file, therefore we need to deselect the corresponding check box:

Click to enlarge

  • When you deselect a rule, the Action Plan Recommendation will recalculate the suggested Action Plan, therefore you may find that the list changes since you have excluded a certain rule and the algorithm may decide that a different combination of violations will match the chosen remediation target.
  • If violations of a particular rule are already present in the Action Plan, the check box will be unselected and disabled, e.g. the four unselected rules are also disabled in the following image:

CriteriaThe name of the parent Technical Criterion for the violated rule.
RuleThe name of the violated rule.
CriticalIndicates whether the rule is critical or not (a red dot indicates a critical rule).
Effort (min)Indicates the suggested time in minutes required to fix one single violation.
ViolationsNumber of violations of the rule that will be added to the Action Plan.
Occurrences

Number of occurrences during which the violation of a rule takes place. The value of number of occurrences and number of violations of the rule could be same or different. 

TotalTotal effort in man/days required to fix all the violations of the selected rule. This value is calculated by multiplying the value in the Effort(min) column by the value in the Violations column.