The Rest KPI API provides some management aspect features, e.g. to schedule jobs to calculate and persist key performance indicator values or delete certain persisted KPI results.

Schedule calculation of key performance indicator (KPI) values

Schedules a KPI calculation job that calculates and persists KPI values for a list of specified KPIs and a time interval.

Returns the scheduled job as EntityItemReference.

The user executing this request must have the permission 'Manage KPI values'. Otherwise, no calculation job will be scheduled and a response with HTTP status forbidden (403) will be returned.

URL Pattern	`/manage/kpi/calculationJob`
Method	POST
Content types	`application/json, application/xml`
Media types	`application/json, application/xml`
Result	The job object of the scheduled KPI calculation job

Content

The content has to be a KPICalculationRequestParameter JSON object which is described in the following table.

Properties of the POST request
Field	Required	Default	Datatype	Parameter description
kpisToCalculate	no	-	String Array	Specifies a list of KPIs for which the calculation of values should be done. If a KPI with a specific identifier is not registered, then there will be no calculation for it (will be logged as warning), but the remaining KPIs in the list are still considered. In case this parameter is not given, then all KPIs will be used that are contributed as KPI extension point.
referenceTime	no	Defaults to the current date when the job is scheduled.	DATETIME	Reference time that specifies the end time of all day intervals that will be considered.
daysToBeBacktracked	no	Defaults individually for each KPI to the daysToBeBacktracked from the server preferences. If then is no value provided for a specific KPI, defaults individually for each KPI to the `daysToBeBacktracked` from the KPI extension point.	Integer	Specifies a global value for the days to be backtracked ending at the date from the `referenceTime` parameter. The global value is used for all KPIs in the `kpisToCalculate` list. Must be convertible to an integer that is >= 0.

Result

An object reference to the KPI calculation job.

Properties of the returned object in the POST response
Field	Data type	Description
`id`	Integer	The job ID
`label`	String	The label of the job

Examples

In the examples it is assumed that there are KPI extension points contributed that have "AverageTimeSpentInWorkflow" and "ProcessTimes" as KPI identifier.

Schedule KPI values calculation job for KPIs "AverageTimeSpentInWorkfow" and "ProcessTimes", a reference time of "2013-04-11T11:00:00" and 2 days to be backtracked

With a referenceTime set to "2013-04-11T11:00:00" and "daysToBeBacktracked" set to "2" the following day intervals will be passed to the calculators of each KPI:

[2013-04-09T00:00:00 - 2013-04-10T00:00:00), [2013-04-10T00:00:00 - 2013-04-11T00:00:00), [2013-04-11T00:00:00 - 2013-04-11T11:00:00)

Java Rest Client

Rest Client Java Code

KPICalculationRequestParameter requestParameter = new KPICalculationRequestParameter();
requestParameter.setKpisToCalculate( Arrays.asList( "AverageTimeSpentInWorkflow", "ProcessTimes" ) );
requestParameter.setReferenceTime( "2013-04-11T11:00:00" );
requestParameter.setDaysToBeBacktracked( "2" );
 
KPICalculationRequest calculationRequest = getRestClient().createKPICalculationRequest();
 
calculationRequest.scheduleCalculateKPIValuesJob( requestParameter );

JSON

//POST to http://localhost:1501/rest/V1.0/manage/kpi/calculationJob as body
{
	"kpisToCalculate": ["AverageTimeSpentInWorkflow", "ProcessTimes"],
	"referenceTime": "2013-04-11T11:00:00",
	"daysToBeBacktracked": "2" 
}

The response contains a reference to the scheduled calculation job.

Returned response for scheduling a KPI values calculation

//Returned response contains job reference 
{
	"id": "291",
    "label": "CalculateKPIValues_SingleJob_291"
}

Remove persisted results of key performance indicator (KPI) calculations

Removes all persisted values and execution data for certain KPIs and time interval. Thus, by doing this, it is possible to force a recalculation of KPI of the desired time interval which are also persisted again.

Reasons to use this call may be that

the calculation logic of the contributed KPI calculator was wrong, so the persisted KPI values are wrong as well.
certain data for a specific time period was not available at the time the calculation execution was done. By removing the execution results it is then possible to have the additional data added as well.

Returns Deletion Result objects containing a Webservice Protocol. This contains log informations (information, warning, error entries) that have been written to the (transient) problem log during the deletion operation.

The user executing this request must have the permission 'Manage KPI values'. Otherwise, no calculation job will be scheduled and a response with HTTP status forbidden (403) will be returned.

URL Pattern	`/manage/kpi/removeCalculationResults`
Method	POST
Content types	`application/json, application/xml`
Media types	`application/json, application/xml`
Result	A Deletion Result object containing a Webservice Protocol of the execution.

Content

The content has to be a KPICalculationRequestParameter JSON object which is described in the following table

Properties of the POST request
Field	Required	Default	Datatype	Parameter description
kpisToDelete	yes	-	String Array	Specifies a list of KPIs for which persisted results (values and execution information) are to be deleted. If a KPI with a specific identifier is not registered, then there will be no deletion for it (will be logged as warning), but the remaining KPIs in the list are still considered. In case this parameter is not given, then all KPIs will be used that are contributed as KPI extension point.
referenceTime	yes	-	DATETIME	Reference time that specifies the end time of the time inteval that will be considered.
daysToBeBacktracked	yes	-	Integer	Specifies the days to be backtracked ending at the Date from the `referenceTime` parameter. Must be convertible to an integer that is >= 0.

Result

A Deletion result object containing the protocol of the deletion execution.

Properties of the returned object in the POST response
Field	Data type	Description
`protocol`		The protocol (also known as problem log) of the execution.
`infoCounter`	Integer	number of protocol entries with the INFO severity
`warningCounter`	Integer	number of protocol entries with the WARNING severity
`errorCounter`	Integer	number of protocol entries with the ERROR severity
`entries`	Array of protocol entries
severity	String	The severity of the protocol entry. Might be INFO, WARNING or ERROR
category	String	The category of the protocol entry
message	String	The message of the protocol entry
logDate	Date	The date when the protocol entry has been created
logTime	Time	The time when the protocol entry has been created

Examples

In the examples it is assumed that there is a KPI extension point contributed that has "AverageTimeSpentInWorkflow" as KPI identifier.

However there is no KPI extension contributed with the identifier "ProcessAllTimes".

Remove KPI calculation results for contributed KPI "AverageTimeSpentInWorkfow" and not contributed "ProcessAllTimes", a reference time of "2013-04-11T11:00:00" and 2 days to be backtracked

With a referenceTime set to "2013-04-11T11:00:00" and "daysToBeBacktracked" set to "2" the following time interval will be passed to the deletion execution for each KPI:

[2013-04-09T00:00:00 - 2013-04-11T11:00:00)

and there will be a warning entry in the protocol object of the result that there is no KPI registered with the identifier "ProcessAllTimes":

The KPI with identifier 'ProcessAllTimes' (which is defined in the rest parameters) is not registered.

Java Rest Client

Rest Client Java Code

KPIResultsDeletionRequestParameter requestParameter = new KPIResultsDeletionRequestParameter();
requestParameter.setKpisToDelete( Arrays.asList( "AverageTimeSpentInWorkflow", "ProcessAllTimes" ) );
requestParameter.setReferenceTime( "2013-04-11T11:00:00" );
requestParameter.setDaysToBeBacktracked( "2" );
 
KPIResultsDeletionRequest deletionRequest = getRestClient().createKPIResultsDeletionRequest();
 
deletionRequest.deleteKPIExecutions( requestParameter );

JSON

//POST to http://localhost:1501/rest/V1.0/manage/kpi/removeCalculationResults as body
{
	"kpisToDelete": ["AverageTimeSpentInWorkflow", "ProcessAllTimes"],
	"referenceTime": "2013-04-11T11:00:00",
	"daysToBeBacktracked": "2" 
}

The response contains a KPIDeletionResult object.

KPIDeletionResult object in JSON format

{
	"protocol": {
    	"infoCounter": 1,
    	"warningCounter": 1,
    	"errorCounter": 0,
    	"entries": [
    	  {
    	    "severity": "WARNING",
    	    "category": "CONSISTENCY",
    	    "message": "The KPI with identifier 'ProcessAllTimes' (which is defined in the rest parameters) is not registered.",
    	    "logDate": "2018-01-04",
    	    "logTime": "14:52:00"
    	  },
		  {
          	"severity": "INFO",
            "category": "SUMMARY",
            "message": "Removal of KPI values finished successfully.",
            "logDate": "2017-09-20",
            "logTime": "08:21:22"
          }
		]
	}
 }