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


KPI - KPI History Resource - GET Method

Retrieve the KPI history information.

Resource URI

GET /models/{model id}/versions/{version}/kpis/history/{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.
granularity string
Granularity of the KPI History to be displayed. Valid values are hourly, daily, weekly, monthly, quarterly and yearly. If a granularity is not specified, a default granularity based on the KPI definition and time range will be used.
timeperiodmethod string
KPI History time period method. Valid values are 'repeatingPeriod', 'rollingPeriod' and 'fixedPeriod'.
repeatingperiodbasis string
KPI repeating time period basis. Valid values are 'previousPeriod' and 'periodInProgress'.
repeatingperiodduration string
KPI repeating time period duration. Valid values are daily, monthly, quarterly and yearly.
repeatingperiodquantity number
Number of periods to include.
rollingperiodduration string
Time scale of the KPI History to be displayed. Valid values are hours, days, weeks, months, quarters and years. If a rollingperiodduration is not specified, a default based on the KPI definition and granularity will be used. This parameter is used with the rollingperiodquantity parameter. For example, to display the last 3 months, the query would be: ?rollingperioduration=months&rollingperiodquantity=3
rollingperiodquantity number
Number of periods to include. This parameter is used with the rollingperiodduration parameter. For example, to display the last 3 months, the query would be: ?rollingperiodduration=months&rollingperiodquantity=3
timerangestart string
The time range start time. Valid formats are "2007-01-01" or "2007-01-01T00:00:00". This parameter is used with timerangeend and timezone to select a specific range of KPI history.
timerangeend string
The fixed period end time. Valid formats are "2007-01-01" or "2007-01-01T00:00:00". This parameter is used with timerangestart and timezone to select a specific range of KPI history.
timezone string
The timezone to be used in selecting the KPI History.
includepredictions boolean
Whether to include predicted values for the KPIs. Valid values are 'true' and 'false'.
allversions boolean
Whether to include all KPI versions. Valid values are 'true' and 'false'. Default value is 'false'.
predictionhorizon number
Number of predictions to display. If not specified, then the number of predictions is determined by the KPI Prediction Model.
predictionmodelid string
KPI Prediction Model ID of the model to be used in generating the KPI Predictions.

Request Content

None.

Response Content

Every Target, Range Start/End and KPI Value is localized according to locale and KPI data type. Locale is passed to REST using a query parameter. If locale is not given to REST, the default locale from the host where REST services are running is used to localize KPI data.

KPI value is localized into a duration, a decimal, a percentage, or currency. Target and Range Start/End values are localized into decimals or durations. The KPI value's decimal precision, whether it should be formatted to percentage or currency, is determined by KPI definition.

The default content-type is application/json.

MIME Type: application/json

The following table lists all parameters in the JSON output:

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

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

Model Display Name

string

The model display name

KPI Display Name

string

The key performance indicator (KPI) display name

KPI Description

string

The key performance indicator (KPI) description

KPI Data Type

string

The key performance indicator (KPI) data type. Valid values are “decimal” or “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

Range Start Timestamp

string

Start date for the KPI History returned

Range Start Timestamp Localized

string

Localized start date for the KPI History returned

Range Start Timestamp in Timezone

string

Start date for the KPI History returned corrected to the local timezone

Range End Timestamp

string

End date for the KPI History returned

Range End Timestamp Localized

string

Localized end date for the KPI History returned

Range End Timestamp in Timezone

string

End date for the KPI History returned corrected to the local timezone

KPI Value Array

array

Array of historical values for KPI

 

KPI Period Timestamp

string

Timestamp of the historical KPI value

 

KPI Period Timestamp Localized

string

Localized timestamp of the historical KPI value

 

KPI Period Timestamp In Timezone

string

Timestamp of the historical KPI value corrected to the local timezone.

 

KPI Value

number

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

 

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 Prediction Array

array

Array of predicted values for KPI

 

KPI Period Timestamp

string

Timestamp of the predicted KPI value

 

KPI Period Timestamp Localized

string

Localized timestamp of the predicted KPI value

 

KPI Period Timestamp In Timezone

string

Timestamp of the predicted KPI value corrected to the local timezone.

 

KPI Value

number

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

KPI Range Array

array

 Array to contain any KPI Ranges.

 

KPI Range ID

string

The range ID for each of the ranges.  This value is used if provided, otherwise it is generated.

 

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. 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 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 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 End Value Localized

string

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

 

KPI Range Color

string

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

 

KPI Range Icon

string

The key performance indicator (KPI) range icon display icon in key performance indicator (KPI) tables

Time Period Ranges

  1. Repeating Time Range:

The repeatingperiodbasis, repeatingperiodduration, repeatingperiodquantity and timezone query parameters are used to specify a repeating time range.  The repeating time range query parameters are mutually exclusive of the fixed and rolling time range query parameters.  The repeatingperiodbasis indicates if the current period should be included in the query.  The repeatingperiodquantity indicates the number of periods to be included in the query.  If the “periodInProgress” is specified by the repeatingperiodbasis then the current period is included in the period count.  The following example is a repeating time range for the last three full months plus the current month using a daily granularity:

 

granularity=daily&repeatingperiodbasis=periodInProgress&repeatingperiodduration=monthly& repeatingperiodquantity=4&timezone=America/Los_Angeles

 

  1. Rolling Time Range:

The rollingperiodduration and rollingperiodquantity query parameters are used to specify a rolling time range.  The rolling time range query parameters are mutually exclusive of the fixed and repeating time range query parameters.  The following example is a rolling time range  for the last three months using a daily granularity:

 

granularity=daily&rollingperiodduration=months&rollingperiodquantity=3&timezone=America/Los_Angeles

 

  1. Fixed Time Range:

The timerangestart, timerangeend and timerangetimezone query parameters are used to specify a fixed time range. The use of the fixed time range parameters is mutually exclusive of the repeating and rolling time range query parameters.  The following is a sample of passing fixed time range as query parameters:

 

timerangestart=2007-03-01&timerangeend=2007-04-13&timezone=America/Los_Angeles


+ View Schema
{ "description": "KPI History", 
  "type": ["object"],
  "properties":
   {
	{
   	"KPI ID":{"type":"string"},
   	"Model ID":{"type":"string"},
   	"Model Display Name":{"type":"string"},
   	"Version":{"type":"number"},
   	"KPI Description":{"type":"string"},
   	"KPI Display Name":"{"type":"string"},
   	"KPI Data Type":{"type":"string",
	         	"enum":["decimal", "duration"]},
   	"Range Start Timestamp":{"type":"string"},
   	"Range Start Timestamp Localized":{"type":"string"}
   	"Range Start Timestamp In Timezone":{"type":"string"},
   	"Range End Timestamp":{"type":"string"},
   	"Range End Timestamp Localized":{"type":"string"},
   	"Range End Timestamp In Timezone":{"type":"string"},
   	"Target":{"type":"number"},
   	"Target Localized":{"type":"string"},
   	"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 End 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"}
     		},
   	],
   	"KPI Prediction Array":[
     		{
		"KPI Value":{"type":"number"},
		"KPI Value Localized":{"type":"string"},
         	"KPI Period Timestamp":{"type":"string"},
         	"KPI Period Timestamp Localized":{"type":"string"},
        	"KPI Period Timestamp In Timezone":{"type":"string"}
      		}   
   	],
   	"KPI Value Array":[
      		{
         	"KPI Value":{"type":"number"},
         	"KPI Value Localized":{"type":"string"},
         	"Target":{"type":"number"},
         	"Target Localized":{"type":"string"},
         	"KPI Period Timestamp":{"type":"string"},
         	"KPI Period Timestamp Localized":{"type":"string"},
        	"KPI Period Timestamp In Timezone":{"type":"string"}
      		}
   	],
}

Example content:

{
   "KPI ID":"avgPrice",
   "Model ID":"OrderItem",
   "Model Display Name":"Order Item",
   "Version":20060803000000,
   "KPI Description":"avgOrderPrice",
   "KPI Display Name":"Avg Order Price",
   "KPI Data Type":"decimal",
   "Range Start Timestamp":"2008-11-01T04:00:00",
   "Range Start Timestamp Localized":null
   "Range Start Timestamp In Timezone":"2008-11-01T00:00:00",
   "Range End Timestamp":"2008-12-10T05:00:00",
   "Range End Timestamp Localized":null,
   "Range End Timestamp In Timezone":"2008-12-10T00:00:00",
   "Target":100.0,
   "Target Localized":"$100.00",
   "KPI Range Array":[
      {
         "KPI Range ID":"range1",
         "KPI Range Display Name":"Low",
         "KPI Range Start Value":0.0,
         "KPI Range Start Value Localized":"$0.00",
         "KPI Range End Value":50.0,
         "KPI Range End Value Localized":"$50.00",
         "KPI Range Color":"#CC0000",
         "KPI Range Icon":""
      },
      {
         "KPI Range ID":"range2",
         "KPI Range Display Name":"Medium",
         "KPI Range Start Value":50.0,
         "KPI Range Start Value Localized":"$50.00",
         "KPI Range End Value":100.0,
         "KPI Range End Value Localized":"$100.00",
         "KPI Range Color":"#FFFF00",
         "KPI Range Icon":""
      },
      {
         "KPI Range ID":"range3",
         "KPI Range Display Name":"High",
         "KPI Range Start Value":100.0,
         "KPI Range Start Value Localized":"$100.00",
         "KPI Range End Value":200.0,
         "KPI Range End Value Localized":"$200.00",
         "KPI Range Color":"#339900",
         "KPI Range Icon":""
      }
   ],
   "KPI Prediction Array":[
     {
	"KPI Value":90
	"KPI Value Localized":"90.00"
	"KPI Period Timestamp":"'2008-02-01T03:00:00'"
        "KPI Period Timestamp Localized":"Jan 31, 2008",
        "KPI Period Timestamp In Timezone":"2008-01-31T22:00:00",
      }   
   ],
   "KPI Value Array":[
      {
         "KPI Value":4.433333333333333570180911920033395290374755859375,
         "KPI Value Localized":"$4.43",
         "Target":100,
         "Target Localized":"$100.00",
         "KPI Period Timestamp":"2008-12-04T05:00:00"
         "KPI Period Timestamp Localized":"Dec 3, 2008",
         "KPI Period Timestamp In Timezone":"2008-12-04T00:00:00",
      },
      {
         "KPI Value":8.973290874501984562906537892010555894563095460021,
         "KPI Value Localized":"$8.97",
         "Target":100,
         "Target Localized":"$100.00",
         "KPI Period Timestamp":"2008-12-06T05:00:00"
         "KPI Period Timestamp Localized":"Dec 5, 2008",
         "KPI Period Timestamp In Timezone":"2008-12-06T00:00:00",
      },
   ],
}

Error Response Content

Detailed error information.

The default content-type is application/json.

MIME Type: application/json


+ View Schema
{ "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.2

Parent Topic: KPI History Resource