Motivation

Product 360 provides a framework for the calculation of key performance indicators (KPIs). Therefore an extension point is provided which can be used to contribute custom implementations of KPI value calculators.

Extension point definition

The extension point com.heiler.ppm.kpi.server.kpi provides a contribution element: kpi. This element is used to define a KPI implementation with the following attributes:

Key	value
`type`	Unique identifier for KPI type. Indicates what kind of objects are being described by this KPI.
`name`	The human readable name of the KPI.
`description`	The description of the KPI.
`daysToBeBacktracked`	Days to be backtracked from now, which is used to determine the start day to calculate the KPI Values. It must be an integer. Default value is 1. Example: - when `daysToBeBacktracked = 1` and KPI values calcuation is started at 2017-06-02 11:00:00 AM - then KPI values for the following days will be calculated: - 2017-06-01 (0:00:00 AM - 23:59:59 PM) - 2017-06-02 (0:00:00 AM - 11:00:00 AM)
`calculator`	The implementation class which calculates the actual KPI values.

The calculator class must implement the interface com.heiler.ppm.kpi.server.KPIValuesCalculator, which contains the following method:

com.heiler.ppm.kpi.server.KPIValuesCalculator

public interface KPIValuesCalculator
{
  /**
   * The calculation function which calculates KPI Values of certain objects. Created {@link CalculationResult}s must be
   * valid.
   * This means in concrete:
   * <ul>
   * <li>The first group value is set with a not-blank value</li>
   * <li>All group values below a group value have to be filled with not-blank values. For example if the third group
   * value is filled then also the second and the first one have to be filled with not-blank values.</li>
   * </ul>
   * @param calculationContext The calculation context.
   * @param progressMonitor The progressmonitor. Must not be <code>null</code>.
   * @param problemLog the problemLog. Must not be <code>null</code>.
   * @return A list of {@link CalculationResult}s.
   */
  List< CalculationResult > calculateKPIValues( CalculationContext calculationContext, IProgressMonitor progressMonitor,
                                                ProblemLog problemLog )
                  throws InterruptedException, CoreException;
 
}

A KPI element can have up to five sub elements groupLabel. These can be used to define groups, in which the calculated KPI values can then be categorized. E.g. a KPI implementation describes workflows which can have a group label called "workflows" as it groups KPI values of different workflows.

The following table indicates the attributes of the sub element groupLabel.

key	value
`group`	The group itself which groups KPI data. Its value has to be selected from a predefined list.
`label`	The label of the current group.

You can define up to five different group labels for one KPI which are build as a hierarchical structure. This means that each filled group label needs to have a valid group label above it. For example if you fill your second group label, the first group label also has to be filled. If you fill your third group label, the first and the second group label have to be filled.

Custom implementations

Contributing a KPI

To add a custom implementation of kpi just contribute to the extension point com.heiler.ppm.kpi.server.kpi and create a class implementing the interface KPIValuesCalculator.

KPI Contribution sample

<extension
  point="com.heiler.ppm.kpi.server.kpi">
    <kpi
      calculator="com.heiler.ppm.kpi.sample.calculator.SampleKPICalculator"
      description="%sampleKPI.description"
      daysToBeBacktracked="1"
      name="%sampleKPI.name"
      type="sampleKPI">
        <groupLabel
          group="GROUP_LABEL_1"
          label="groupLabel_1">
        </groupLabel>
        <groupLabel
          group="GROUP_LABEL_2"
          label="groupLabel_2">
        </groupLabel>
  </kpi>
</extension>

Additional KPI setting

The administrator is able to add a corresponding preference in plugin_customization.ini to replace the defined daysToBeBacktracked for a single contributed KPI after the server is restarted.

The preference should use the following format, where <numberOfDays> must be a not negative integer value.

kpi.<kpiIdentifier>.daysToBeBacktracted = <numberOfDays>

For example:

com.heiler.ppm.kpi.server/kpi.mySampleKPIIdentifier.daysToBeBacktracted = 7

During server start all contributed KPI implementations are validated and registered in Product 360.

Scheduling KPI implementation

A server job is running periodically to execute all contributed KPI value calculators. The job instances can be seen in the Desktop Client's Process overview in the category "Calculate KPI values" or be requested via Rest API.

images/download/attachments/114695758/KPI_Jobs.png

In the server's plugin_customization.ini you can define at which time and how often the calculation should be executed. Default is every day at 0:00:00.

# Specifies the cron expression for the KPI Values calculation server job.
# Default is every day at 0:00:00
calculateKPIValuesJob.pattern = 0 0 0 ? * *

Validating the calculation results

After calculation the corresponding results will be validated for the following criteria:

all calculation results are unique, regarding the group values 1 - 5 and the dataSetLabel
the group values are filled from bottom (1) to top (5)
only group values that are defined for the given KPI are filled
the dataSetLabel is not null
the value is not null
the objectcount is not negative

Calculation results of one day are only stored in the database if all of them are valid. Validation errors are stored in the server job's problem log.