In this section:

Introduction

The Key Performance Indicator (KPI) slice calculates a score based on weights assigned to code analysis rules in your development project. The weights are defined in a profile that can be customized to meet your development goals. When the slice is invoked, it counts the number of rule violations for each file in the project. For each rule, the slice multiplies the violation count by the specified rule weight in the profile. If a rule does not have a defined weight in the profile, the count for that rule is not gathered. The sum of the weighted counts is divided by the logical lines of code (METRIC.NOLLOCIF) to yield a KPI score. This artifact ships with the Security Compliance Pack, which includes configurations for calculating KPIs associated with security compliance standards.

KPI Slice Workflow

  1. Install the Security Compliance Pack, which installs the KPI slice and weighted profiles.
  2. Deploy the KPI slice to your DTP environment.
  3. Run your code analysis tool using one of the Security Compliance Pack test configurations (see Security Compliance Pack for additional information).
  4. Run your code analysis tool using the Metrics test configuration. The Number of Logical Lines in Files metric (METRIC.NOLLOCIF) must be enabled.
  5. Call the KPI slices' REST endpoint to invoke the calculation. You must include the filter ID, build ID, and KPI profile containing the weights. The calculation is a long-running process and typically best to execute as part of your automated nightly code analysis. 
  6. Add a Metrics widget configured to show data according to the KPI profile.

Requirements

Installation

The KPI slice is installed with the Security Compliance Pack. After installing the Security Compliance Pack, you will need to deploy the slice using Extension Designer.

Upgrading from an Older Version

If you are upgrading from the standalone instance of the KPI slice, uninstall the previous version of the artifact, including models and profiles, prior to installing the latest version. If you altered the default profile shipped with the previous version or created custom profiles, export the profile(s) and add the following attributes (also see Exporting and Importing Profiles):

If you change the default values, we recommend setting the metric ID prefix to METRIC.KPI.<profile name without spaces>. Use a concise name for the metric (maximum 30 characters).

Deploying the Slice

  1. Open Extension Designer and click the Services tab.
  2. Expand a service category and either click on an existing service or create new service for the KPI slice. 
  3. If you are deploying the slice to an existing service, click the + button to add a new tab. Otherwise, go to the next step. 
  4. Choose Import from the ellipses menu and choose Library> Workflows> Security> Key Performance Indicator.
  5. Click Import and click anywhere in the open area to drop the artifact into the service. 
  6. Click Deploy and return to your DTP dashboard.
  7. Refresh your browser.

Configuration

Several KPI profiles are added when the Security Compliance Pack is installed. Each profile contains weights for the Parasoft rules that check a set of security compliance guidelines. You can use the default weights or review each rule and apply your own weights.

To change the weight:

  1. Click on a profile and click Edit.
  2. Click on a rule and change the value in the Weight field.
  3. Click Save.

You can also add rules that are not in the profile to include in the calculation. Refer to Working with Model Profiles for additional information.

Invoking the Calculation

The KPI slice is a long running slice. It should only be computed when invoked by a third-party, ideally as part of a nightly job.

  1. Click on the service category on the Services tab and drill down to the endpoint. You can use the API or direct endpoint path (see Service Category Page for additional information).



  2. Copy the endpoint and send a REST request to it with the required parameters. Use the API endpoint path if available (see Working with Flows for additional information). The following table describes the required parameters:

filterIdThe filter id for the project that the calculations will be performed on.
profileProfile name with the rules and weights to use for the calculations.
buildIdThe build id for which the calculations will be performed on. If no build id is provided, this parameter defaults to the latest build.

Example Invocation

You could run the following command to invoke the slice and run the calculation:

curl "http://localhost:8314/api/v1/services/5dcc38b803c7380f707268b9/slices/bd858e5f.965978?filterId=2&buildId=docs-2019-11-13&profile=CWE%20Security%20Impact%20-%20Java"

If successful, you will receive a response such as the following:

{
	"success": {
		"message": "Calculation has started for filter 'jtest' using profile 'CWE Security Impact - Java'. Check debug output for any errors during calculation.",
		"title": "KPI"
	}
}


Viewing the Data in DTP

After computation has completed and the KPI metric has been reported back to DTP, you can add a Metrics widget to your DTP dashboard and choose a metric associated with your security compliance guidelines from the Metric drop-down menu. The value in the drop-down menu comes from the Metric Name field in the profile (see Configuration). Refer to Adding Widgets for additional information about adding widgets to DTP dashboards.

The widget will display the metric according to your specifications.

Click on the widget to open the Single Metric Overview Report.

Click on a link in the report to view the data in the Metrics Explorer.