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


KPI - KPI Definition with Value Resource - GET Method

Resource URI

GET /models/{model id}/versions/{version}/kpis/value/{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.

Request Content

None.

Response Content

Every Target, Range Start/End and KPI Value is localized into a decimal or duration 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 default content-type is application/json.

MIME Type:

The following table lists all parameters in the JSON output:

Payload Parameter Name

Type

Description

KPI ID

string

The key performance indicator (KPI) ID.

Model ID

string

The monitor model ID

Version

number

The monitor model version

Model Display Name

string

The model display name

KPI Context ID

string

The key performance indicator (KPI) context ID

KPI Context Name

string

The key performance indicator (KPI) context name

KPI Display Name

string

The key performance indicator (KPI) display name

KPI Cache Override Interval

number

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

The key performance indicator (KPI) description

KPI Origin

string

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

KPI Data Type

string

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

Target

number

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

Target Localized

string

The key performance indicator (KPI) target value in localized format. For example, duration KPIs are displayed as #d, #h, #m, #s

KPI Range Type

string

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.

KPI Calc Method

string

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

Aggregated Metric ID

string

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

Aggregated Metric Name

string

The name of the aggregated metric

Aggregated Metric Type

string

The aggregated metric type. Valid values are "STRING", "BOOLEAN", "DECIMAL", "INTEGER", "DATE", "TIME", "DATETIME", "DURATION", 'COUNTER", "STOPWATCH-A", and "STOPWATCH-NA"

Aggregated Metric MC ID

string

The ID of the monitoring context of the aggregated metric

Aggregated Metric MC Name

string

The name of the monitoring context of the aggregated metric

Aggregated Function

string

The aggregated function. Valid values are "avg", "sum", "min", "max", "count", and "stddev"

Version Aggregation

string

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".

Time Period Metric ID

string

The ID of metric used for time period qualification. This is a date or datetime metric.

Time Period Metric Name

string

The name of time period metric

Time Period Method

string

The time period method. Valid values are "repeatingPeriod", "rollingPeriod", and "fixedPeriod"

Repeating Period Duration

string

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

Repeating Period Basis

string

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

Repeating Period Timezone

string

The repeating period time zone. This is a Java timezone identifier (for example, America/Los Angeles).

Rolling Period Duration

string

The rolling period duration. Valid values are "years", "months", "days", "hours", and "minutes".

Rolling Period Quantity

number

The number of rolling periods.

Fixed Period Start

string

The fixed period start time. Valid formats are '2007-01-01' and '2007-01-01T00:00:00'.

Fixed Period End

string

The fixed period end time. Valid formats are '2007-01-01' and '2007-01-01T00:00:00'.

Fixed Period Timezone

string

The fixed period time zone. This is a Java timezone identifier (for example, America/Los Angeles).

Effective End Date

string

The effective end date timestamp for fixed or repeating time period.

Effective End Date Localized

string

The localized effective end date timestamp for fixed or repeating time period.

Calculated KPI Expression

string

The calculated key performance indicator (KPI) expression. This must be a valid XPath expression. Other KPIs and UDFs can be referenced.

User ID

string

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

View Access

string

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

Format Decimal Precision

number

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

Format Currency

string

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

Format Percentage

boolean

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

KPI Value

string

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

KPI Value Localized

string

The key performance indicator (KPI) value in localized format. For example, duration KPIs are displayed as #d, #h, #m, #s

Enable KPI History

boolean

Flag to indicate if KPI History is enabled.  Valid values are “true” and “false”

History Include Predictions

boolean

Flag to indicate if KPI History should include predictions.  Valid values are “true” and “false”

KPI History Defaults

object

Object to contain KPI history default values

 

History Time Range Start

string

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

 

History Time Range End

string

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

 

History Repeating Period Quantity

number

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

 

History Rolling Period Duration

string

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

 

History Repeating Period Basis

string

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

 

History All Versions

boolean

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”

 

History Time Range Method

string

The time period method. Valid values are "repeatingPeriod", "rollingPeriod", and "fixedPeriod"

 

History Rolling Period Quantity

number

The number KPI History periods to retrieve.

 

History Display Ranges

string

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

 

History Granularity

string

The value can be yearly, quarterly, monthly, weekly, daily and hourly.

 

History Valid From

string

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

Timezone used by KPI History. This is a Java timezone identifier (for example, America/Los Angeles).

 

History Repeating Period Duration

string

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

 

History Display Target

string

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

KPI History Granularity Options

array

Array to contain KPI granularity options

 

KPI History Granularity Default

string

The default history granularity selection. The value can be yearly, quarterly, monthly, weekly, daily and hourly.

 

KPI History Granularity Hours

number

The number of KPI history granularity hours

 

KPI History Granularity Supported

array

Array to contain supported KPI granularity selections

 

 

Granularity Value

string

The granularity selection. The value can be yearly, quarterly, monthly, weekly, daily and hourly.

Enable KPI Prediction

Boolean

Flag to indicate if KPI Prediction is enabled.  Valid values are “true” and “false”

Default Prediction Model ID

string

The ID for the default prediction model.

Prediction Model Array

array

Array containing prediction models for the KPI

 

Prediction Model ID

string

The ID for the prediction model.

 

Prediction Model Name

string

Name of the KPI Prediction Model

 

Prediction Interval Unit

string

Unit used for the KPI Prediction Interval.  Valid values are:  hourly, daily, weekly, monthly, quarterly, yearly

KPI Metric Filter Array

string

Array of filters of aggregated key performance indicators (KPIs)

 

KPI Metric Filter ID

string

The filter ID for each of the metric filters.

 

Filter Metric ID

string

The ID of the metric used for filtering

 

Filter Metric Name

string

The name of the metric used for filtering

 

Filter Metric Type

string

The filter metric type. Valid values are "STRING", "BOOLEAN", "DECIMAL", "INTEGER", "DATE", "TIME", "DATETIME", "DURATION", 'COUNTER", "STOPWATCH-A", and "STOPWATCH-NA"

 

Filter Operator

string

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

 

Filter Operator Case Sensitive

boolean

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

 

Filter Value

string

The filter value.

KPI Range Array

array

Array to contain any KPI ranges

 

KPI Range ID

string

The range ID for each of the key performance indicator (KPI) ranges.

 

KPI Range Display Name

string

The key performance indicator (KPI) range display name

 

KPI Range Start Value

number

The key performance indicator (KPI) range start value. If duration KPI and if KPI Range Type is an “actualValue”, then the start value is in milliseconds

 

KPI Range Start Value Localized

string

The key performance indicator (KPI) range start value in localized format. For example, duration KPIs are displayed as #d, #h, #m, #s

 

KPI Range End Value

number

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 duration KPI and if KPI Range Type is an “actualValue”, then the end value is in milliseconds

 

KPI Range End Value Localized

string

The key performance indicator (KPI) range start value in localized format. For example, duration KPIs are displayed as #d, #h, #m, #s

 

KPI Range Icon

string

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

 

KPI Range Color

string

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

Warnings

array

Array of warning messages

 

Warning

string

String containing a warning message for the KPI

 


{"description": "KPI with value output", 
 "type": "object",
 "properties":
	{"KPI ID":{"type":"string"},
	"Model ID":{"type":"string"},
	"Version":{"type":"number"},
	"Model Display Name":{"type":"string"},
	"KPI Context ID":{"type":"string"},
	"KPI Context Name":{"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"},
	"Target Localized":{"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"};
	"Effective End Date":{"type":"string"},
	"Effective End Date Localized":{"type":"string"},
	"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"},
	"KPI Value":{"type":"string"},
	"KPI Value Localized":{"type":"string"},
	"Enable KPI History":{"type":"boolean"},
	"History Include Predictions":{"type":"boolean"},
	"KPI History Defaults":{
 				"type": "object",
 				"properties":
			{		
			"History Time Range Start":{"type":"string",
						"description":"Valid formats are ‘20081201T123000’, ’2008-12-01’ 
								and ‘20081201’"},
			"History Time Range End":{"type":"string",
						"description":"Valid formats are ‘20081201T123000’, ’2008-12-01’ 
								and ‘20081201’"},
			"History Repeating Period Quantity":{"type":"number"},
			"History Rolling Period Duration":{"type":"string",
	              	     				"enum":["yearly", "quarterly", "monthly", "weekly", "daily"]},
			"History Repeating Period Basis":{"type":"string",
	                  				"enum":["previousPeriod", "periodInProgress"]},
			"History All Versions":{"type":"boolean"},
			"History Time Range Method":{"type":"string",
	             	 			"enum":["repeatingPeriod", "rollingPeriod", "fixedPeriod"]},
			"History Rolling Period Quantity":{"type":"number"},
			"History Display Ranges":{"type":"boolean"},
			"History Granularity":{"type":"string",
	              	     			"enum":["yearly", "quarterly", "monthly", "weekly", "daily", "hourly"]},
			"History Valid From":{"type":"string"),
			"History Timezone":{"type":"string",
			     		"description":"This is a Java timezone identifier. For example, America/Los Angeles"},
			"History Repeating Period Duration":{"type":"string",
	              	     				"enum":["yearly", "quarterly", "monthly", "weekly", "daily"]},
			"History Display Target":{"type":"boolean"},
			}
		}
	"KPI History Granularity Options":[
					{
					"KPI History Granularity Default":{"type":"string",
	              	     			"enum":["yearly", "quarterly", "monthly", "weekly", "daily", "hourly"]},
					"KPI History Granularity Hours":"type":"number"),
					"KPI History Granularity Supported":[
									{
						"Granularity Value":{"type":"string",
	              	     			"enum":["yearly", "quarterly", "monthly", "weekly", "daily", "hourly"]},
									}
								]
					}
				]
	"Enable KPI Prediction":{"type":"boolean"},
	"Default Prediction Model ID":{"type":"string"},
	"Prediction Model Array":[
				{
				"Prediction Model ID":{"type":"string"},
				"Prediction Model Name":{"type":"string"},
				"Prediction Interval Unit":{"type":"string",
	              	     			"enum":["yearly", "quarterly", "monthly", "weekly", "daily", "hourly"]},
				}
			]
	"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 Start Value Localized":{"type":"string"},

      			"KPI Range End Value":{"type":"number"},
      			"KPI Range Start Value Localized":{"type":"string"},
      			"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"}
			}
  		]   
	"Warnings": [
			{
			"Warning": {"type":"string"}
			}
		]
	}                     
}

Example content:

{
   "KPI ID":"SumPriceToday",
   "Model ID":"OrderItem",
   "Version":20060803000000,
   "Model Display Name":"Order Item",
   "KPI Context ID":"TimePeriodKPIs",
   "KPI Context Name":"TimePeriodKPIs",
   "KPI Display Name":"Sum Price Today",
   "KPI Cache Override Interval":30,
   "KPI Description":null,
   "KPI Origin":"modeled",
   "KPI Data Type":"decimal",
   "Target":"20000.0",
   "Target Localized":"$20,000.00",
   "KPI Range Type":"actualValue",
   "KPI Calc Method":"aggregated",
   "Aggregated Metric ID":"itemPrice",
   "Aggregated Metric Type":"DECIMAL",
   "Aggregated Metric MC Name":"OrderItem MC",
   "Aggregated Metric Name":"Item Price",
   "Aggregated Metric MC ID":"OrderItem_MC"
   "Aggregated Function":"sum",
   "Version Aggregation":"singleVersion",
   "Time Period Metric ID":"dateOrdered",
   "Time Period Metric Name":"Date Ordered",
   "Time Period Method":"repeatingPeriod",
   "Repeating Period Basis":"periodInProgress",
   "Repeating Period Timezone":"America/New_York",
   "Repeating Period Duration":"daily",
   "Rolling Period Quantity":null,
   "Rolling Period Duration":null,
   "Fixed Period Timezone":null,
   "Fixed Period Start":null,
   "Fixed Period End":null,
   "User ID":null,
   "Effective End Date":"2008-12-05T04:59:59",
   "Effective End Date Localized":"December 4, 2008 11:59:59 PM",
   "KPI History Defaults":{
      "History Time Range Start":null,
      "History Repeating Period Quantity":2,
      "History Rolling Period Duration":null,
      "History Repeating Period Basis":"periodInProgress",
      "History All Versions":false,
      "History Time Range Method":"repeatingPeriod",
      "History Time Range End":null,
      "History Rolling Period Quantity":null,
      "History Display Ranges":false,
      "History Granularity":"daily",
      "History Valid From":null,
      "History Timezone":null,
      "History Repeating Period Duration":"monthly",
      "History Display Target":false
   },
   "KPI Value":5009.6711483585408,
   "KPI Value Localized":"$5,009.67",
   "KPI Range Array":[
      {
         "KPI Range End Value":"10000.0",
         "KPI Range Start Value":"0.0",
         "KPI Range Color":"014085",
         "KPI Range Start Value Localized":"$0.00",
         "KPI Range Display Name":"Low",
         "KPI Range ID":"Low",
         "KPI Range End Value Localized":"$10,000.00",
         "KPI Range Icon":null
      },
      {
         "KPI Range End Value":"20000.0",
         "KPI Range Start Value":"10000.0",
         "KPI Range Color":"0050a8",
         "KPI Range Start Value Localized":"$10,000.00",
         "KPI Range Display Name":"Medium",
         "KPI Range ID":"My_Range",
         "KPI Range End Value Localized":"$20,000.00",
         "KPI Range Icon":null
      },
      {
         "KPI Range End Value":"25000.0",
         "KPI Range Start Value":"20000.0",
         "KPI Range Color":"4070b8",
         "KPI Range Start Value Localized":"$20,000.00",
         "KPI Range Display Name":"High",
         "KPI Range ID":"High",
         "KPI Range End Value Localized":"$25,000.00",
         "KPI Range Icon":null
      }
   ],
   "History Include Predictions":false,
   "Format Percentage":false,
   "KPI Metric Filter Array":[

   ],
   "Format Decimal Precision":0,
   "Prediction Model Array":[
      {
         "Prediction Model ID":"hourly",
         "Prediction Interval Unit":"hourly",
         "Prediction Model Name":"hourly"
      },
      {
         "Prediction Model ID":"weekly",
         "Prediction Interval Unit":"weekly",
         "Prediction Model Name":"weekly"
      },
   ],
   "Format Currency":"USD",
   "Default Prediction Model ID":null,
   "Calculated KPI Expression":null,
   "Enable KPI History":true,
   "KPI History Granularity Options":[
      {
         "KPI History Granularity Default":"hourly",
         "KPI History Granularity Hours":0,
         "KPI History Granularity Supported":[
            {
               "Granularity Value":"hourly"
            },
            {
               "Granularity Value":"daily"
            },
            {
               "Granularity Value":"weekly"
            },
            {
               "Granularity Value":"monthly"
            },
            {
               "Granularity Value":"quarterly"
            },
            {
               "Granularity Value":"yearly"
            }
         ]
      },
   ],
   "View Access":"public",
   "Enable KPI Prediction":true,
}

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 with Value Resource