Search API (POST method)
Search API (POST method) uses the POST method to search the CIs. It searches the CIs based on the input parameters that are provided in the JSON format. The advantage of using the search API (POST method) over the search API (GET method) is that you can use any slot names to search the CIs.
You can use the usage API to get details about the slots that you can use to search a CI. For information about the usage API, see Retrieving searchable slots and supported enumerations for each slot.
You also have the option of sorting the search results. You must provide authentication credentials by using the login API before accessing the data. For information about authentication, see Web-services-authentication.
URL to access the search API (POST method)
The generic format of a URL for search API (POST method) is as follows:
http|https://<serverHost>:<port>/bppmws/api/CI/search?
Entry | Description |
|---|---|
http|https | Type of protocol to send the request. Infrastructure Management support both HTTP and HTTPS protocols. |
serverHost | Host name of the BMC TrueSight Infrastructure Management Server |
port | Port number through which communication is established. The default port number is 80 if you use the HTTP protocol and 443 if you use the HTTPS protocol. |
Available query parameters (Optional) | |
page | Page number of the paginated data from which you want to retrieve the data. When your request generates a huge volume of data, the response data is paginated with page numbers. This parameter helps to retrieve data from any particular page by using the page number. This parameter is applicable only when you send the web service request from a Central Server. |
resultSize | Indicates whether you want to retrieve the details of the CIs or partial details of CIs. The supported values are as follows:
The default value for this parameter is default. |
Input parameters in the JSON format for the search API (POST method)
You can use the usage API to list the searchable slots and the supported enumerations for each slot along with the supported operators with which the enumerations can be searched. Based on the usage API's response, you can provide input parameters. For information about the usage API, see Retrieving searchable slots and supported enumerations for each slot.
When you provide input parameters for any web service request, you must specify the content-type parameter in the header of the web service request as follows:
Sample input parameters in the JSON format are as follows:
Sample input parameters for the search API (POST method) without sort criteria
"criteria": {
"value": "BMC_BaseElement",
"identifier": "CLASS",
"operator": "SUBCLASS_OF"
}
}
Sample input parameters for the search API (POST method) with sort criteria
"sortCriteria": [
{
"sortOrder": 1,
"attributeName": "Name"
}
],
"criteria": {
"groupingOperator": "AND",
"leftExpression": {
"value": "BMC",
"identifier": "Name",
"operator": "contains"
},
"rightExpression": {
"value": "UNAVAILABLE",
"identifier": "status",
"operator": "equals"
}
}
}
Attributes | Description |
|---|---|
sortCriteria | Condition based on which search results are sorted. You can define up to three sort criteria. If two or more entries match the first criterion, sorting happens based on the second and third criteria. This parameter is optional. The usage API responds with a sample sort criteria to help you to understand it thoroughly. See Response information for the usage API. |
sortOrder | Type of sorting. It can either be ascending or descending. The supported values are as follows:
1 indicates ascending sort, and 2 indicates descending sort. |
attributeName | Slot name based on which the search results are sorted For example, if the value of attributeName parameter is CLASS and the value of sortOrder parameter is 1, the search results are sorted in the ascending order based on the values of class slot. |
criteria | Conditions based on which the CIs are searched. You can have a single condition using identifier, operator, and value parameters or nested conditions using the leftExpression, groupingOperator, and rightExpression parameters. |
groupingOperator | Boolean operator. The supported Boolean operators are as follows:
For example, if you use the AND operator, both the leftExpression condition and the rightExpression condition must be fulfilled for a CI to match the search criteria. |
leftExpression | One of the conditions based on which the CIs are searched |
value | String to search |
identifier | Slot name of a CI. All the specified slot values are searched for the specified string. You can use the usage API to know the supported values of any slot. For information about the usage API, see Retrieving-searchable-slots-and-supported-enumerations-for-each-slot. |
operator | Condition that relates the identifier and value parameters To know the supported operators for an identifier, you can use the usage API. For information about the usage API, see Retrieving-searchable-slots-and-supported-enumerations-for-each-slot. |
rightExpression | One of the conditions based on which the CIs are searched |
JSON response to the search API (POST method)
A sample JSON response is as follows:
Parameters | Description |
|---|---|
count | Total CIs that match the search criteria. If the count value is greater that the page size, the number of CIs that you see in a page is equal to the page size. |
ciList | List of CIs that match the search criteria. A value of null indicates that there are no CIs that qualify to be displayed. For example, in the request, you have the page parameter value as 10. In the response, the count parameter value is 30, and the ciList displays null because there are no CIs to be displayed in the 10th page. In this case, the count shows a valid number, although ciList shows null. |
"response": {
"count": 1,
"status": "OK",
"ciList": [
{
"id": "mc.pncell_bppmwsserver.e4e58cd.0",
"className": "BMC_BaseElement",
"hasProviders": false,
"hasConsumers": false,
"attributeMap": {
"Name": "10",
"status": "OK",
"mc_udid": "mc.pncell_bppmwsserver.e4e58cd.0",
"CLASS": "BMC_BaseElement",
"sub_status": "NONE",
"sla_rollup_status": "NO_SLAS",
"computed_priority": "PRIORITY_5",
"direct_events_count": "0",
"pn_predict_to_occur_time": "0",
"highest_pn_predicted_severity": "",
"any_open_event_max_sev": "OK",
"any_event_max_sev": "OK",
"impacting_open_event_max_sev": "OK",
"maintenance_mode": "NO",
"OwnerName": "",
"OwnerContact": "",
"ShortDescription": "n/a",
"manual_status": "NONE",
"schedule_status": "IN"
},
"hostUri": "http://bppmwsserver:80"
}
],
"statusCodes": [
"200"
],
"errorList": [
"OK"
]
},
"statusCode": "200",
"statusMsg": "OK",
"responseTimeStamp": "2011-08-22T09:14:22"
}