WebSphere Business Monitor, Version 6.2
Operating Systems: AIX, HP-UX, Linux, Solaris, Windows
POST /models/{model id}/versions/{version}/kpis/config/{kpi id}?{parameters}
Name | Value Type | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
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.
|
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 |
|
|
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, |
|
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, |
|
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. |
|
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. |
|
|
|
string |
No |
Fixed period start date for retrieving KPI
History. Valid formats are
‘20081201T123000’ ,’2008-12-01’ and ‘20081201’. |
|
|
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. |
|
History Rolling Period Duration |
string |
No |
The
repeating period duration. Valid values are "yearly",
"quarterly", “weekly” "monthly", and "daily". |
|
History Repeating Period Basis |
string |
No |
The
repeating period basis. Valid values are "previousPeriod"
and "periodInProgress". For example, for
year-to-date, use "periodInProgress" |
|
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” |
|
|
string |
No |
The
time period method. Valid values are "repeatingPeriod",
"rollingPeriod", and "fixedPeriod" |
|
History Rolling Period Quantity |
number |
No |
The number KPI History periods to retrieve. |
|
|
string |
No |
Flag to indicate if |
|
History Granularity |
string |
No |
The value can be yearly, quarterly, monthly,
weekly, daily and hourly. |
|
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, |
|
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” |
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. |
|
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. |
|
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. |
|
|
string |
Yes |
The key performance indicator (KPI) range display
name |
|
|
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 |
|
|
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 |
|
|
string |
No |
The display color in key performance indicator
(KPI) gauges. Valid values are #000000 - #FFFFFF (omit the # sign) |
|
|
string |
No |
The key performance indicator (KPI) range icon display
icon in key performance indicator (KPI) tables, e.g. images/kpi/monitorIcons/ |
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('
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 (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"
}
}]
The
time zone can be provided with this filter. If the time zone is not provided,
it is set to Greenwich mean time (
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"
}
}]
The
time zone can be provided with this filter. If the time zone is not provided,
it is set to Greenwich mean time (
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 }
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.
The default content-type is application/json.
{ "description": "REST error response", "type": "object", "properties": { "Status Code" : {"type":"integer"}, "Error" : {"type":"string"}, } }
Code | Description |
---|---|
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.
|
6.1
Parent Topic: KPI Definition Resource