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


Monitoring Context Instance Data - Cross-version Monitoring Context Instances Resource - GET Method

Use this method if there is no payload sent with the request. GET has some limitations (e.g., the length limit of query parameters) that can be overcome if using POST with a payload instead.

Resource URI

GET /models/{model id}/mcs/{mc id}/instances?{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.
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'.
ValueDescription
asc (default)
Sort the instances by the sort column in ascending order.
desc
Sort the instances by the sort column in descending order.
accept string
New to 6.1.2 and later releases. Specify the response output type.
ValueDescription
json (default)
The response output is in JSON format
csv
The response output is in CSV format (can be directly opened in Microsoft Excel ©)
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.
ValueDescription
true (default)
Return the immediate child instances grouped by child monitoring contexts.
false
Do not return the immediate child instances.
returncount boolean
New to 6.2 fixpack 1 (6.2.0.1) and later releases. Whether to return the instance count.
ValueDescription
true (default)
Return the instance count.
false
Do not 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 a 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 under POST for format.

Request Content

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.

Export instances

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. Note that when sending the instance data under the "input" form parameter in a GET request, the data is included in the query component of the request URI and may be suject to a length limit. Therefore, POST is recommended when exporting current page.

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 rules to set the HTTP "content-type" header:

1. Regular JSON response: no content type is required with GET requests.

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, no content type is required.

3. CSV response for export (current page passed in): not possible with GET requests.

MIME Type: application/x-www-form-urlencoded

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.

 

Response Content

For each globalized metric (for example, "deliveryDate") in "Metric ID Array", a new field called "metricID Localized" (for example, "deliveryDate Localized") is inserted after the original metric. The globalized value will be inserted in the "Metric Data" array at the same index as "metricID Localized" metric in "Metric ID Array". For any null metric, "null" will be the localized value. Any Date/Time/DateTime metric will be returned in XPath format. Localized formats for Date/Time/DateTime metrics are determined by ICU depending on locale.

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

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

 


+ View Schema
{ "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]
				}
			   ]
          }
	]
}

MIME Type: text/csv

This is the output content type for export instance requests when the record count is less than or equal to 5000

MIME Type: application/zip

This is the output content type for export instance requests when the record count is greater than 5000

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

Parent Topic: Cross-version Monitoring Context Instances Resource