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


Monitoring Context Instance Data - Cross-version Monitoring Context Instances Resource - POST (X-METHOD-OVERRIDE=GET) Method

Use this method if there is a payload sent with the request. The X-METHOD-OVERRIDE parameter in the HTTP header needs to be set to GET. This indicates to the REST service that the GET method should be used instead of the POST request when processing the request.

Resource URI

POST /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.
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".
ValueDescription
true
Return the metric values for only the metrics listed in the payload under "Metrics".
false (default)
Return all metric values.
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 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.

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.

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.

The default content-type is application/json.

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.

 

MIME Type: application/json

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

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.

Time filters, time period filtering and filter operators

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('13:20:00-05:00')

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 Time Period (Sliding interval):

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"
                                    }
 }]
 
    • Fixed Time Period:

The time zone can be provided with this filter. If the time zone is not provided, it is set to Greenwich mean time (GMT). The timezone should be a location, for example, America/Los_Angeles. The "Fixed Period Start" and "Fixed Period End" parameters can be in the Date format "YYYY-MM-DD" (for example, "2007-03-05") or DateTime format "YYYY-MM-DDTHH:mm:ss" (for example, "2007-03-05T13:50:00").

 

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"
                                    }
 }]   
 
    • Repeating Time Period (Last completed period or Current period):

The time zone can be provided with this filter. If the time zone is not provided, it is set to Greenwich mean time (GMT). The time zone is normally a location, for example, America/Los_Angeles. The "Repeating Period Duration" can be "daily", "monthly", "quarterly" and "yearly". The "Repeating Period Basis" can be "previousPeriod" or "periodInProgress".

 

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"
                                    }
}] 

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

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

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]
				}
			   ]
          }
	]
}

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