WebSphere Business Monitor, Version 6.2 Operating Systems: AIX, HP-UX, Linux, Solaris, Windows


KPI - KPI Definition Resource - POST Method

Create a new KPI.

Resource URI

POST /models/{model id}/versions/{version}/kpis/config/{kpi id}?{parameters}

Parameters

Optional Parameters
NameValue TypeDescription
locale string
The locale. This value consists of lowercase ISO language code (ISO 639) and the uppercase ISO country code (ISO 3166) joined by an underscore (for example, en_US). Results will be returned in the locale specified. If no locale is specified, the locale of the REST server will be used.
mode string
Indicates the request type.
ValueDescription
no value (default)
If "mode" is not specified or no value, then the KPI will be created or updated. This is the default behavior unless one of the two valid values is used.
validateOnly
Indicates that the KPI should be validated instead of created.
validateAndTest
Indicates that the KPI should be validated instead of created, and returns the calculated KPI value.

Request Content

MIME Type: application/json

The HTTP request can have a payload which contains parameters. The following table lists all input parameters that can be sent in the HTTP payload in JSON format.

Note: Required values marked with an asterisk are conditional with additional information in the Description.

Payload Parameter Name

Type

Required

Description

KPI ID

string

Yes*

The key performance indicator (KPI) ID. This value is required for KPI updates. It is not a required field to create a KPI. If it is provided in the URI for create, REST will try to create the KPI based on the supplied id. If a KPI with the same id already exists, REST will add a number to the end of the id and create the KPI. If KPI id is not provided in the URI for create, the KPI id is derived from the KPI Display Name.

Model ID

string

Yes

The monitor model ID

Version

number

Yes

The monitor model version

Locale

string

No

The locale. This value consists of lowercase ISO language code (ISO 639) and the uppercase ISO country code (ISO 3166) joined by an underscore (for example, en_US). Results will be returned in the locale specified. If no locale is specified, the locale of the REST server will be used.

KPI Context ID

string

No

The key performance indicator (KPI) context ID

KPI Display Name

string

Yes

The key performance indicator (KPI) display name

KPI Cache Override Interval

number

No

Time in minutes for the KPI to cache the value.  If set, this time interval overrides the KPI Cache Refresh set at the Model/version level on the Admin console.   A value of zero indicates that the KPI should not be cached.

KPI Description

string

No

The key performance indicator (KPI) description

KPI Origin

string

Yes

The key performance indicator (KPI) origin. Valid values are "modeled" and "runtime"

KPI Data Type

string

Yes

The key performance indicator (KPI) data type. Valid values are "decimal" and "duration"

Target

number

No

The key performance indicator (KPI) target value. If the data type is "duration", the target is in milliseconds

KPI Range Type

string

Yes

The key performance indicator (KPI) range type. Valid values are "actualValue" and "percentage". Percentage indicates a percent of the target, where 100 = 100% of target. Required if KPI Range Array is not empty.

KPI Calc Method

string

Yes

The key performance indicator (KPI) calculation method. Valid values are "aggregated" and "calculated"

Aggregated Metric ID

string

Yes*

The ID of the aggregated metric Required if KPI Calc Method is "aggregated". Required if KPI Calc Method is "aggregated".

Aggregated Metric MC ID

string

Yes*

The ID of the monitoring context of the aggregated metric. Required if KPI Calc Method is "aggregated".

Aggregated Function

string

Yes*

The aggregated function. Valid values are "avg", "sum", "min", "max", and "count". Required if KPI Calc Method is "aggregated".

Version Aggregation

string

Yes

The scope of the metric aggregation, whether it is for instances within the same model version as the KPI or for instances across all model versions. Valid values are "singleVersion"” and "allVersions". Required if KPI Calc Method is "aggregated".

Time Period Metric ID

string

Yes*

The ID of metric used for time period qualification. This is a date or datetime metric. Required if KPI Calc Method is "aggregated" and a Time Filter is used.

Time Period Method

string

Yes*

The time period method. Valid values are "repeatingPeriod", "rollingPeriod", and "fixedPeriod". Required if KPI Calc Method is "aggregated" and a Time Filter is used.

Repeating Period Duration

string

Yes*

The repeating period duration. Valid values are "yearly", "quarterly", "monthly", and "daily". Required if KPI Calc Method is "aggregated" and Time Period Method is "repeatingPeriod".

Repeating Period Basis

string

Yes*

The repeating period basis. Valid values are "previousPeriod" and "periodInProgress". For example, for year-to-date, use "periodInProgress". Required if KPI Calc Method is "aggregated" and Time Period Method is "repeatingPeriod".

Repeating Period Timezone

string

Yes*

The repeating period time zone. This is a Java timezone identifier (for example, America/Los Angeles). Required if KPI Calc Method is "aggregated" and Time Period Method is "repeatingPeriod".

Rolling Period Duration

string

Yes*

The rolling period duration. Valid values are "years", "months", "days", "hours", and "minutes". Required if KPI Calc Method is "aggregated" and Time Period Method is "rollingPeriod".

Rolling Period Quantity

number

Yes*

The number of rolling periods. Required if KPI Calc Method is "aggregated" and Time Period Method is "rollingPeriod".

Fixed Period Start

string

Yes*

The fixed period start time. Valid formats are '2007-01-01' and '2007-01-01T00:00:00' Either Fixed Period Start or Fixed Period End is required if KPI Calc Method is "aggregated" and Time Period Method is "fixedPeriod"

Fixed Period End

string

Yes*

The fixed period end time. Valid formats are '2007-01-01' and '2007-01-01T00:00:00' Either Fixed Period Start or Fixed Period End is required if KPI Calc Method is "aggregated" and Time Period Method is "fixedPeriod"

Fixed Period Timezone

string

Yes*

The fixed period time zone. This is a Java timezone identifier (for example, America/Los Angeles). Required if KPI Calc Method is "aggregated" and Time Period Method is "fixedPeriod".

Calculated KPI Expression

string

Yes*

The calculated key performance indicator (KPI) expression. This must be a valid XPath expression. Other KPIs and UDFs can be referenced. Required if the KPI Calc Method is "calculated".

User ID

string

No

The user ID of the key performance indicator (KPI) owner

View Access

string

Yes

The view access, whether the KPI can be viewed by others or not. Valid values are "public" and "personal".

Format Decimal Precision

number

No

The number of digits that are displayed after the decimal point for numeric KPIs.

Format Currency

string

No

The currency code to be used for formatting numeric KPIs. This 3-letter code must conform to ISO 4217 standards.

Format Percentage

boolean

No

The format percentage, whether the KPI will be displayed as a percentage or not. Valid values are "false" and "true".

Enable KPI History

boolean

No

Flag to indicate if KPI History is enabled.  Valid values are  true  and  false . Default value is  true .

History Include Predictions

boolean

No

Flag to indicate if KPI History should include predictions.  Valid values are “true” and “false”. This parameter is only available for KPI Update. It defaults to “false” upon KPI create.

KPI History Defaults

array

No

Array to contain KPI history default values. This parameter and all sub-parameters within the array are only available for KPI Update.

 

History Time Range Start

string

No

Fixed period start date for retrieving KPI History.  Valid formats are ‘20081201T123000’ ,’2008-12-01’ and ‘20081201’.

 

History Time Range End

string

No

Fixed period end date for retrieving KPI History.  Valid formats are ‘20081201T123000’ ,’2008-12-01’ and ‘20081201’.

 

History Repeating Period Quantity

number

No

The number KPI History periods to retrieve.  For a periodInProgress query, the current period would count as 1. It defaults to 2 upon KPI create.

 

History Rolling Period Duration

string

No

The repeating period duration. Valid values are "yearly", "quarterly", “weekly” "monthly", and "daily". It defaults to "monthly" upon KPI create.

 

History Repeating Period Basis

string

No

The repeating period basis. Valid values are "previousPeriod" and "periodInProgress". For example, for year-to-date, use "periodInProgress". It defaults to "periodInProgress" upon KPI create.

 

History All Versions

boolean

No

Flag to indicate if KPI History should include all version of the KPI.  This flag must be false if the KPI is a single version KPI.  Valid values are “true” and “false”. It defaults to “false” upon KPI create.

 

History Time Range Method

string

No

The time period method. Valid values are "repeatingPeriod", "rollingPeriod", and "fixedPeriod". It defaults to "repeatingPeriod" upon KPI create.

 

History Rolling Period Quantity

number

No

The number KPI History periods to retrieve.

 

History Display Ranges

string

No

Flag to indicate if KPI Ranges should be displayed in the KPI History widget.  Valid values are “true” and “false”. It defaults to “false” upon KPI create.

 

History Granularity

string

No

The value can be yearly, quarterly, monthly, weekly, daily and hourly. It defaults to "daily" upon KPI create.

 

History Valid From

string

No

Timestamp used to indicate the earliest date/time that KPI History is valid.  For example, this is initially set to the KPI creation date.  KPI History would not be valid prior to the creation of the KPI.

 

History Timezone

string

No

Timezone used by KPI History. This is a Java timezone identifier (for example, America/Los Angeles). It defaults to the server timezone upon KPI create.

 

History Repeating Period Duration

string

No

The repeating period duration. Valid values are "yearly", "quarterly", “weekly” "monthly", and "daily".

 

History Display Target

string

No

Flag to indicate if KPI Target should be displayed in the KPI History widget.  Valid values are “true” and “false”. It defaults to “false” upon KPI create.

Enable KPI Prediction

Boolean

No

Flag to indicate if KPI Prediction is enabled.  Valid values are “true” and “false”. This parameter is only available for KPI Update. It defaults to “false” upon KPI create.

Default Prediction Model ID

string

No

The ID for the default prediction model. This parameter is only available for KPI Update.

KPI Metric Filter Array

string

No

Array of filters of aggregated key performance indicators (KPIs)

 

KPI Metric Filter ID

string

No

The filter ID for each of the metric filters. This value is used if provided. Otherwise, it is automatically generated.

 

Filter Metric ID

string

No

The ID of the metric used for filtering

 

Filter Operator

string

Yes

The filter operator. Valid values are "equals", "lessThan", "lessThanOrEquals", "greaterThan", "greaterThanOrEquals", "notEquals", "in", "notIn", "isNull"”, "isNotNull", "like", "notLike".

 

Filter Operator Case Sensitive

boolean

Yes

Whether the filter operator is case-sensitive or not when using string-based metric filters. Valid values are "false" and "true".

 

Filter Value

string

Yes*

The filter value. For information on the format for each data type, see the section on filtering. Required unless the operators isNull or isNotNull are specified. The filter value can be specified as an array. For example, a string would be represented as [“’Smith’”]. An array of values included with the “in” operator would be represented as [“’Smith’”, “’Jones’”]. Note that string values are surrounded by a single quotation marks for the XPath formatting and double quotation marks for the JSON formatting.

KPI Range Array

array

No

Array to contain any KPI ranges

 

KPI Range ID

string

No

The range ID for each of the key performance indicator (KPI) ranges. This value is used if provided. Otherwise, it is automatically generated.

 

KPI Range Display Name

string

Yes

The key performance indicator (KPI) range display name

 

KPI Range Start Value

number

Yes

The key performance indicator (KPI) range start value. This value can be defined as an actual value or as a percent of a target as defined by KPI Range Type. If KPI Range Type is “percentage”, use a value such as 100 to represent 100%. If duration KPI and if KPI Range Type is an “actualValue”, then the start value is in milliseconds

 

KPI Range End Value

number

Yes

The key performance indicator (KPI) range end value. This value can be defined as an actual value or as a percent of a target as defined by KPI Range Type. If KPI Range Type is “percentage” use a value such as 100 to represent 100%. If duration KPI and if KPI Range Type is an “actualValue”, then the end value is in milliseconds

 

KPI Range Color

string

No

The display color in key performance indicator (KPI) gauges. Valid values are #000000 - #FFFFFF (omit the # sign)

 

KPI Range Icon

string

No

The key performance indicator (KPI) range icon display icon in key performance indicator (KPI) tables, e.g. images/kpi/monitorIcons/IBM_down_red.gif

Time filters, time period filtering and filter operators

Aggregated KPIs can be filtered based on metric values. The filtering is handled as two parts: optional metric filter arrays and an optional time period filter. The metric filters are passed as an array and use operators against metric filter values that are not date or datetime to limit the scope of the KPI. The time period filter is more specialized and uses time period definitions described below to create a date/time filter.

1.   Metric Filter arrays

 

The structure of the metric filter array is described in the Input JSON definition. The following is an example of two metric filters contained in an array that would be passed to the Rest Service:

 

[{"Filter Metric ID":"customerName","Filter Operator":"notIn","Case Sensitive":false,
"Filter Value":["'Smith'","'Store 1'"]}, 
{"Filter Metric ID":"customerID",
"Filter Operator":"greaterThan",
"Case Sensitive":false,"Filter Value":2}]

 

2.  REST expected data format for KPI metric filtering

REST expects a certain format when dealing with passed-in filtering data. For metric data types like Date, Time, DateTime, Duration, Integer, etc. the filter values should comply with XPath formats. Please see document at http://www.w3.org/TR/xmlschema-2/ for XPath format details.

The following are the REST expected formats for Time metrics:

1.  time format: time('HH:mm:ss-zzzzzz')

Example: time('13:20:00-05:00')

3.   Filter operators

The following is a table of allowed filter operators for each metric filter type. Note that Date and DateTime types are explained in the next section about Time Period filtering.

 

equals

lessThan

lessThanOrEquals

greaterThan

greaterThanOrEquals

notEquals

in

notIn

isNull

isNotNull

like

notLike

String

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Integer and Counter

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

N

N

Decimal

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

N

N

Date*

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

DateTime*

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

Time

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

N

N

Duration and Stopwatch

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

N

N

Boolean

Y

N

N

N

N

Y

N

N

Y

Y

N

N

 

 

4.  Time Period filtering

Time Period filtering is a special kind of filtering. They are used for Date or DateTime metric types. Just like other filters, they can either be passed in as a query parameter (a serialized JSON array) or as a payload JSON array.

 

    • Rolling Time Period (Sliding interval):

Rolling (or sliding) time period filters do not have time zones, "Rolling Period Quantity" must be an integer, and "Rolling Period Duration" can be "years", "months", "days", "hours" or "minutes".

 

JSON structure for rolling time period filtering:

 

[{"Filter Metric ID":"dateOrdered",
     "Filter Value":{"Time Period Method":"rollingPeriod",
                                    "Rolling Period Quantity":4,
                                    "Rolling Period Duration":"months"
                                    }
 }]
 
    • Fixed Time Period:

The time zone can be provided with this filter. If the time zone is not provided, it is set to Greenwich mean time (GMT). The timezone should be a location, for example, America/Los_Angeles. The "Fixed Period Start" and "Fixed Period End" parameters can be in the Date format "YYYY-MM-DD" (for example, "2007-03-05") or DateTime format "YYYY-MM-DDTHH:mm:ss" (for example, "2007-03-05T13:50:00").

 

JSON structure for fixed time period filtering:

 

[{"Filter Metric ID":"dateOrdered",
 "Filter Value":{"Time Period Method":"fixedPeriod",
                                    "Fixed Period Start":"2007-03-01",
                                    "Fixed Period End":"2007-04-13",
                                    "Fixed Period Timezone":"America/Los_Angeles"
                                    }
 }]   
 
    • Repeating Time Period (Last completed period or Current period):

The time zone can be provided with this filter. If the time zone is not provided, it is set to Greenwich mean time (GMT). The time zone is normally a location, for example, America/Los_Angeles. The "Repeating Period Duration" can be "daily", "monthly", "quarterly" and "yearly". The "Repeating Period Basis" can be "previousPeriod" or "periodInProgress".

 

JSON structure for repeating time period filtering:

 

[{"Filter Metric ID":"dateOrdered",
  "Filter Value":{"Time Period Method":"repeatingPeriod",
                                    "Repeating Period Duration":"quarterly",
                                    "Repeating Period Basis":"previousPeriod",
                                    "Repeating Period Timezone":"America/Los_Angeles"
                                    }
}] 

{"description": "KPI Create Input Payload", 
 "type": "object",
 "properties":
	{"KPI ID":{"type":"string"},
	"Model ID":{"type":"string"},
	"Version":{"type":"number"},
	"KPI Context ID":{"type":"string"},
	"KPI Display Name":{"type":"string"},
	"KPI Cache Override Interval":{"type":"number"},
	"KPI Description":{"type":"string"},
	"KPI Origin":{"type":"string",
	      		"enum":["modeled", "runtime"]},
	"KPI Data Type":{"type":"string",
	         	"enum":["decimal", "duration"]},
	"Target":{"type":"number"},
	"KPI Range Type":{"type":"string",
	          	"enum":["actualValue", "percentage"]},
	"KPI Calc Method":{"type":"string",
	           	"enum":["aggregated", "calculated"]},
	"Aggregated Metric ID":{"type":"string"}, 
	"Aggregated Metric Name":{"type":"string"},
	"Aggregated Metric Type":{"type":"string",
	           	  	"enum":["STRING", "BOOLEAN", "DECIMAL", "INTEGER", "DATE", "TIME", "DATETIME", "DURATION", "COUNTER", "STOPWATCH-A", "STOPWATCH-NA"]},
	"Aggregated Metric MC ID":{"type":"string"},
	"Aggregated Metric MC Name":{"type":"string"},
	"Aggregated Function":{"type":"string",
	               		"enum":["avg", "sum", "min", "max", "count"]},
	"Version Aggregation":{"type":"string",
	               		"enum":["singleVersion", "allVersions"]},
	"Time Period Metric ID":{"type":"string"}, 
	"Time Period Metric Name":{"type":"string"},
	"Time Period Method":{"type":"string",
	             	 "enum":["repeatingPeriod", "rollingPeriod", "fixedPeriod"]},
	"Repeating Period Duration":{"type":"string",
	              	     	"enum":["yearly", "quarterly", "monthly", "weekly", "daily", "hourly", "minutely"]},
	"Repeating Period Basis":{"type":"string",
	                  	"enum":["previousPeriod", "periodInProgress"]},
	"Repeating Period Timezone":{"type":"string",
			     	"description":"This is a Java timezone identifier. For example, America/Los Angeles"},
	"Rolling Period Duration":{"type":"string",
	                   	"enum":["years", "months", "days", "hours", "minutes"]},
	"Rolling Period Quantity":{"type":"number"},
	"Fixed Period Start":{"type":"string",
		      		"description":"Valid formats are '2007-01-01' or '2007-01-01T00:00:00'"},
	"Fixed Period End":{"type":"string",
		    	"description":"Valid formats are '2007-01-01' or '2007-01-01T00:00:00'"},
	"Fixed Period Timezone":{"type":"string",
			 	"description":"This is a Java timezone identifier. For example, America/Los Angeles"};
	"Calculated KPI Expression":{"type":"string"},
	"User ID":{"type":"string"},
	"View Access":{"type":"string",
	       		"enum":["public", "personal"]},
	"Format Decimal Precision":{"type":"number"},
	"Format Currency":{"type":"string",
		   	"description":"ISO4217 currency identifier. For example, 'USD'"}, 
	"Format Percentage":{"type":"boolean"},
	"Enable KPI History":{"type":"boolean"},
	"KPI Metric Filter Array":[
				{
				"KPI Metric Filter ID":{"type":"string"},
				"Filter Metric ID":{"type":"string"},
				"Filter Metric Name":{"type":"string"},
				"Filter Metric Type":{"type":"string",
	       					      "enum":["STRING", "BOOLEAN", "DECIMAL", "INTEGER", 
							      "DATE", "TIME", "DATETIME", "DURATION", 
							      "COUNTER", "STOPWATCH-A", "STOPWATCH-NA"]},
				"Filter Operator":{"type":"string",
	       					   "enum":["equals", "lessThan", "lessThanOrEquals", "greaterThan", 
							   "greaterThanOrEquals", "notEquals", "in", "notIn", 
							   "isNull", "isNotNull", "like", "notLike"]},
				"Filter Operator Case Sensitive":{"type":"boolean"},
				"Filter Value":{"type":["string","array of strings", "array of numbers"]}
  				}
 			]
	"KPI Range Array":[
    			{
      			"KPI Range ID":{"type":"string"},
      			"KPI Range Display Name":{"type":"string"},
      			"KPI Range Start Value":{"type":"number"},
      			"KPI Range End Value":{"type":"number"},
      			"KPI Range Color":{"type":"string",
					"description":"#000000 - #FFFFFF(omit the # sign)"},
      			"KPI Range Icon":{"type":"string",
					"description":"Relative path to the icon. For example, 
						images/kpi/monitorIcons/IBM_down_red.gif"}
			}
  		]     
	}                     
}

Example content:

{
   "Model ID":"OrderItem",
   "Version":20060803000000,
   "KPI Display Name":"Sum Price Today",
   "KPI Description":"",
   "KPI Cache Override Interval":null,
   "KPI Origin":"runtime",
   "KPI Data Type":"decimal",
   "Target":20000,
   "KPI Range Type":"actualValue",
   "KPI Range Array":[
      {
         "KPI Range ID":"Low",
         "KPI Range Display Name":"Low",
         "KPI Range Start Value":0,
         "KPI Range End Value":10000,
         "KPI Range Color":"014085",
         "KPI Range Icon":""
      },
      {
         "KPI Range ID":"My_Range",
         "KPI Range Display Name":"Medium",
         "KPI Range Start Value":10000,
         "KPI Range End Value":20000,
         "KPI Range Color":"0050a8",
         "KPI Range Icon":""
      },
      {
         "KPI Range ID":"High",
         "KPI Range Display Name":"High",
         "KPI Range Start Value":20000,
         "KPI Range End Value":30000,
         "KPI Range Color":"4070b8",
         "KPI Range Icon":""
      }
   ],
   "KPI Calc Method":"aggregated",
   "Aggregated Metric ID":"itemPrice",
   "Aggregated Metric MC ID":"OrderItem_MC",
   "Aggregated Function":"sum",
   "Version Aggregation":"singleVersion",
   "Time Period Method":"repeatingPeriod",
   "Time Period Metric ID":"dateOrdered",
   "Repeating Period Duration":"daily",
   "Repeating Period Basis":"periodInProgress",
   "Repeating Period Timezone":"America/New_York",
   "User ID":"",
   "View Access":"personal",
   "Format Currency":"USD",
   "KPI Metric Filter Array":[

   ],
   "Enable KPI History":true
}

Response Content

Every Target, Range Start/End and KPI Value is localized according to locale and KPI data type before being returned to the client.

KPI value is localized into a duration, a decimal, a percentage, or currency. The KPI value's decimal precision, whether it should be formatted to percentage or currency, is determined by the KPI definition.

The POST request type will return the same output as "KPI Definition with Value". For more information on the output parameters, see Retrieve KPI definition with a value.

The default content-type is application/json.

Error Response Content

Detailed error information.

The default content-type is application/json.

MIME Type: application/json


{ "description": "REST error response", 
  "type": "object",
  "properties":
   { "Status Code" : {"type":"integer"},
     "Error" : {"type":"string"},
   }
} 

Status Codes

The method returns one of the following status codes:
CodeDescription
200 OK
Successful completion - requested data returned. Note that the list may be empty.
403 Forbidden
Not authorized to request the resource.
404 Not Found
Resource not found or URL not supported.
400 Bad Request
The request contains invalid parameters or is missing parameters and inputs.
500 Internal Server Error
Internal error processing the request.

Available Since

6.1

Parent Topic: KPI Definition Resource