WebSphere Business Monitor, Version 6.2
Operating Systems: AIX, HP-UX, Linux, Solaris, Windows
POST /models/{model id}/mcs/{mc id}/instances?{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.
|
||||||
timezoneoffset | integer |
The amount of time in minutes to add
to or subtract from the Greenwich Mean Time (GMT) time in order to get the
local time. The timezone offset will be applied to the "localized" value for
any Time/DateTime type metrics that are returned.
|
||||||
page | integer |
The instance page to retrieve. Use -1 to indicate
all instances on a single-page request. The parameter
is optional and defaults to 1. There is an upper limit
of 5000 on the number of instances returned for one
request when "-1" is used. This limit does not apply to
instance export requests.
|
||||||
pagesize | integer |
The number of instances per page. If this
value is not provided, the default of 10 is used.
The page size has an upper limit of 5000. If
the parameter value is larger than 5000, 5000
will be used.
|
||||||
sortby | string |
The metric used to sort the instances. This parameter needs to be set to the
metric id, not metric display name.
|
||||||
order | string |
The order in which the sort should be conducted.
Valid values are 'asc' and 'desc'.
|
||||||
displaymetrics | boolean |
New to 6.1.2 and later releases. Whether to return the metric values for only the metrics listed in the payload under "Metrics".
|
||||||
accept | string |
New to 6.1.2 and later releases. Specify the response output type.
|
||||||
returnchildren | boolean |
New to 6.2 and later releases. Whether to return the child instance data. If true, all immediate children of the instance will be returned in the result.
|
||||||
returncount | boolean |
New to 6.2 fixpack 1 (6.2.0.1) and later releases. Whether to return the instance count.
|
||||||
filter | string |
Typically filters are sent using an HTTP payload
in JSON format using a POST request. However, this JSON can
be serialized into a string and sent as a query parameter
using either a GET or POST request instead. This is true if the length
of the serialized JSON does not exceed the length limit
of an HTTP request. See the HTTP payload for format.
|
The HTTP "Accept" header is used to specify which type of output the client (caller) wants to receive.
The Accept header must be set to "text/csv" when you are exporting instances and "application/json"
for JSON output. The default is "application/json" if the header is not set. Another way to set the
output type is to use the query parameter "accept" (see query parameter section for details). If
both the "Accept" header and "accept" query parameter are set in the HTTP request, the query parameter
takes precedence. There are two types of exports: export queried instances and export current page. When exporting queried
instances, the instances are retrieved from the database using the passed-in filters (if any) and put in
a tab-delimited CSV file and the file is returned. If "page" and "pagesize" are provided in the HTTP request,
the requested page is returned in the CSV file. This option works the same way as the JSON output except that
the instances are returned in a CSV file, not in JSON format. When exporting the current page of instances, no database query is performed. Instead, the instance data
to be exported is sent by the client (caller) in JSON format as "input" form parameter in the HTTP request.
For details about the format of the form post, please see the input parameter section below. When exporting all instances that fall into the filter criteria, if the instance count is
less than or equal to 5000, one CSV file "exportinstances.csv" is returned; otherwise, the instances are
put in more than one CSVs with 5000 instances in each file. The CSV files are then zipped up and
returned to the client in one zip file. The name of the CSV files follows the pattern [model id]_[mc id]_xx.csv
where "xx" is a numeric index. Please follow the following rules to set the HTTP "content-type" header: 1. Regular JSON response: Content type is recommended to be set to "application/json" when
sending a payload. 2. CSV response for export (queries db): if a browser prompt to save the download is desired, the
content type must be set to "application/x-www-form-urlencoded". Otherwise, content type is
recommended to be set to "application/json" when sending a payload. 3. CSV response for export (current page passed in): if a browser prompt to save the download is desired, the
content type must be set to "application/x-www-form-urlencoded". Otherwise, content type is
recommended to be set to "application/json" when sending a payload.Export instances
The default content-type is application/json.
The following form post parameters are used for exporting instances.
Form Parameter Name |
Type |
Description |
|
input |
string |
The value of this form parameter is the payload to be sent with the HTTP request. For details about payload contents, please see the section "MIME Type: application/json". In the case of export page, the instance page data to be exported is put under this parameter. |
|
content_type |
string |
This parameter indicates the content type of the form payload. The value can be set to "application/json", which is also the default value. In the future, more content types will be supported. |
When exporting the current page of instances, the instance data needs to be sent in the form under "input" form parameter. The instance data needs to be sent in JSON format as follows:
{“Export Data”: {instance page}}
"Instance page" is a JSON object. It has the same format as the JSON output of this URI.
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.
Payload Parameter Name |
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). Instance results will be localized in the
locale specified. If no locale is specified, the locale of the REST server
will be used. |
|
Time Zone Offset |
number |
The amount of time in minutes to add to or subtract from the
Greenwich Mean Time ( |
|
Metrics |
string array |
An array of metrics that needs to be formatted |
|
Decimal |
number array |
The number of decimal places to display per metric. Array must
be in the same order as the Metrics array above. Use -1 if no decimal
formatting should be applied to a metric. |
|
Currency |
string array |
The 3-letter currency codes, which must confirm to ISO4217
standards, per metric. Array must be in the same order as the Metrics array
above. Use null if no currency should be applied to a metric. |
|
Filter |
|
Array of metric filters to apply to the instance query |
|
|
Filter Metric ID |
string |
The ID of the metric used for filtering |
|
Filter Operator |
string |
The filter operator. Valid values are "equals",
"lessThan", "lessThanOrEquals", "greaterThan",
"greaterThanOrEquals", "notEquals", "in",
"notIn", "isNull"”, "isNotNull",
"like", "notLike". |
|
Case Sensitive |
boolean |
Whether the filter operator is case-sensitive or not. Valid
values are "false" and "true". |
|
Filter Value |
string or array of strings |
The filter value, represented in XPath format. For information on
the format for each data type, see the usage 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 quote for the XPath formatting, and a double quote for the JSON
formatting. For time
period filtering, see the section on filtering below. |
1. REST expected data format for instance 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('
2.
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 |
3. 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": "Payload Input for Instances REST Services", "type": "object", "properties": { "Locale":{"type":"string" "optional": true }, "Time Zone Offset":{"type":"integer" "optional": true }, "Metrics":{"type":["string"], "optional": true }, "Decimal":{"type":["integer"], "optional": true }, "Currency":{"type":["string"], "optional": true }, "Filter":[ { "Filter Metric ID":{"type":"string", "description": "The ID of the metric that will be filtered on." }, "Filter Operator":{"type":"string", "enum":["equals","lessThan","lessThanOrEquals","greaterThan", "greaterThanOrEquals","notEquals","in","notIn","isNull", "isNotNull","like","notLike"], "description": "The filter operator." }, "Case Sensitive":{"type":"boolean", "optional": true, "default": true, "description": "Whether the filter is case-sensitive." }, "Filter Value":{"type":["string", "number", "boolean","array"], "description": "Filter value can be a single value or an array of values (for IN and NOTIN operators)." } } ] } }
Example content:
{ "Locale": "en_US", "Time Zone Offset": 300, "Metrics": ["customerID", "customerName", "itemPrice"] , "Decimal": [-1, -1, 2], "Currency": [null, null, "USD"], "Filter":[ { "Filter Metric ID": "customerName", "Filter Operator": "like", "Case Sensitive": false, "Filter Value": "%ner" } { "Filter Metric ID": "itemPrice", "Filter Operator": "greaterThan", "Filter Value": 30 } { "Filter Metric ID": "customerName", "Filter Operator": "in", "Filter Value": {"store 1","pizzaria","coffee shop"} } ] }
This is the output content type for export instance requests when the record count is less than or equal to 5000
This is the output content type for export instance requests when the record count is greater than 5000
The default content-type is application/json.
The following table lists all parameters in the JSON output:
Parameter Name |
Type |
Description |
||
Model ID |
string |
The monitor model ID |
||
MCID |
string |
The monitoring context ID |
||
Record Count |
integer |
The record count. If "returncount" parameter is false, record count will be returned as -1. |
||
Page Size |
integer |
The number of records on each page |
||
Page Number |
integer |
The page number |
||
Metric ID Array |
array |
Array of metric IDs (strings) |
||
Instance Data |
array |
|
||
|
Instance ID |
string |
The instance ID |
|
|
Version |
integer |
The monitoring context version |
|
|
Metric Data |
array |
All metric data for one instance in the same order as the Metric
ID Array |
|
|
Children |
array |
Child instance array. This array is returned if returnchildren=true or is not
set in the HTTP request header. |
|
|
|
Child MC ID |
string |
The child monitoring context ID |
|
|
Child Instance IDs |
array |
The child instance IDs |
{ "description": "Cross Version Monitoring Context Instances", "type": "object", "properties": { "Model ID":{"type":"string"}, "MCID":{"type":"string"}, "Record Count":{"type":"integer"}, "Page Size":{"type":"integer"}, "Page Number":{"type":"integer"}, "Metric ID Array":{"type":["string"]}, "Instance Data": { "Instance ID":{"type":"string"}, "Version":{"type":"integer"}, "Metric Data": {"type":["any"]}, "Children" :[ "description": "This array is returned if and only if returnchildren=true." { "Child MC ID": {"type":"string"}, "Child Instance IDs": {"type":["number"]} } ] } } }
Example content:
{ "Model ID":"OrderItem_MC", "MCID":"OrderItem_MC", "Record Count":120, "Page Size":20, "Page Number":3, "Metric ID Array":["customerID", "customerName", "itemPrice","itemPrice Localized","orderDate","orderDate Localized"] "Instance Data": [ { "Instance ID":"12", "Version": 20060803000000, "Metric Data": ["store1", "Store 1", "12.99", "$12.99", "2008-10-18T02:44:18", "October 17, 2008 10:44:18 PM"], "Children" : [ { "Child MC ID": "OrderBook", "Child Instance IDs": [101, 102, 201, 202] } { "Child MC ID": "OrderMusic", "Child Instance IDs": [303, 304] } ] } { "Instance ID":"15", "Version": 20070912000000, "Metric Data": ["Pizzaria", "Pizzaria", "10.00", "$10.99", "2008-12-24T13:30:00", "December 24, 2008 08:30:00 AM"], "Children" : [ { "Child MC ID": "OrderBook", "Child Instance IDs": [221, 223] } { "Child MC ID": "OrderMusic", "Child Instance IDs": [419] } ] } ] }
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: Cross-version Monitoring Context Instances Resource