Page tree

Use this endpoint to perform a search and return results synchronously.

Recommendation

If your search query is too generic and is likely to produce a large set of results, search performance might be impacted. In such a scenario, BMC recommends you to use the Searching and getting results asynchronously with a REST API.

Notes

  • Before running this endpoint, you need to generate an authorization token by running the login endpoint. This token is used to authenticate a user into the product. You need to pass this token in the header each time you want to run the endpoint.
  • To log out from a given session, you need to run the logout endpoint.

For more information, see Developing.

This topic contains the following information:

Endpoint overview

You can use this API to run by using the GET method and by using the POST method.

With the GET method, you can run the search by specifying the saved search name or the saved search ID and by specifying minimum parameters. The time range used for running the search is based on the saved search specified.

With the POST method, you can run the search by specifying the saved search name, saved search ID, or a query string. With this kind of search, you can specify many more parameters (as compared to the GET method). 

Notes

  • Tabular commands are not supported in the saved search query and the query string (specified as input). For more information about tabular commands, see Search commands.
  • The parameter names and their corresponding values must be enclosed in double quotes ("). For example, "searchType":"savedSearchName".
  • To obtain the saved search ID, you need to run the Getting details of a saved search with a REST API.

Using the search ID while performing a search (rather than a saved search name) might be more useful in scenarios when duplicate saved search names occur. Duplicate saved searches can occur in a scenario where one user creates a saved search with a particular name, while another user creates a saved search with the same name and also marks it as public. In this scenario, the first user can see two saved searches with the same name. Similarly, a duplicate saved search can occur when you import a content pack containing saved search with a duplicate name.

The expected response of this API is a set of search results returned synchronously.

Before you begin

Ensure that the following requirements are met:

  • The data on which you want to search is available for searching. This means the data needs to be already collected and indexed.
  • You have appropriate permissions to view the data that you want to search.
  • The saved search that you want to use for searching is created by you or is a public saved search (that is accessible by all users).

Request URL

Use the following request URL to run a search by the saved search name or saved search ID by using the GET method:

GET <protocol>://<host>:<port>/olaengine/itdaws/searchservices/search?<supportedParameters>&version=<apiVersion>

Use the following request URL to run a search by the saved search name, saved search ID, or query string by using the POST method:

POST <protocol>://<host>:<port>/olaengine/itdaws/searchservices/search?version=<apiVersion>

In the preceding URLs, the following definitions apply:

  • <protocol> refers to the protocol that you want to use for communication with the Console Server.
  • <host> refers to the host name of the Console Server
  • <port> refers to the port number of the Console Server. The default port is 9797.
  • <supportedParameters> refers to parameters to be specified for running the search. These parameters need to be specified as name=value pairs separated by an ampersand (&).
    For more information, see the parameter definitions and examples.
  • (Optional) <apiVersion> refers to the API version. In this case, the value must be 2.5.

    Tip

    Generally the API version is the same as the product version on which the API can be run.

Request body

The request body is applicable only for running a search by using the POST method. For more information about the parameters that can be used in the request body, see Parameter definitions (advanced search).

To understand the structure of the request body, see the Examples for running an advanced search.

Examples

The following examples illustrate the inputs for running a search by using the GET method and the POST method.

Example 1: Search by the saved search name (GET method)

The following example illustrates the input for running the saved search, "SS9".

Request URL
GET http://localhost:9797/olaengine/itdaws/searchservices/search?searchValue=SS9

To understand the response structure and its elements, see Response elements.

Example 2: Search by the saved search imported via a content pack (GET method)

The following example illustrates the input for running the saved search, "SS1", imported via the content pack, "BPPMCP".

Request URL
GET http://localhost:9797/olaengine/itdaws/searchservices/search?searchValue=SS1&searchType=savedSearchName&source="cp"&sourceName="BPPMCP"

To understand the response structure and its elements, see Response elements.

Example 3: Search by saved search ID (GET method)

The following example illustrates the input for running the saved search ID, "102be3d4-8729-44e8-b962-927bfdc30bbc".

Request URL
GET http://localhost:9797/olaengine/itdaws/searchservices/search?searchValue=102be3d4-8729-44e8-b962-927bfdc30bbc&searchType=savedSearchID

To understand the response structure and its elements, see Response elements.

Example 4: Search by the saved search name for the epoch time specified (POST method)

The following example illustrates the input for running a saved search, "ITDA collection polls with no data" with the following inputs by using the POST method:

  • Specified epoch time
  • Page number set to 5
  • Page size set to 50
Request URL

POST http://localhost:9797/olaengine/itdaws/searchservices/search

Request body
{
    "searchValue": "ITDA collection polls with no data",
    "searchType": "savedSearchName",
    "startTime": 1450956821246,
    "endTime": 1451561621246,
    "pageSize": 50,
    "pageNumber": 5
}

To understand the response structure and its elements, see Response elements.

Example 5: Search by the saved search that is imported via a content pack (POST method)

The following example illustrates the input for running a saved search, "DetectDowntime" with the following inputs by using the POST method:

  • Specified time – last 60 minutes
  • Page number set to 1
  • Page size set to 100
  • Content pack name (or source name) set to "BPPMCP2"
Request URL

POST http://localhost:9797/olaengine/itdaws/searchservices/search

Request body
{
    "searchValue": "DetectDowntime",
    "searchType": "savedSearchName",
    "startTime": "now-60m",
    "endTime": "now",
    "pageSize": "100",
    "pageNumber": "1",
    "source": "cp",
    "sourceName": "BPPMCP2"
}

To understand the response structure and its elements, see Response elements.

Parameter definitions

The following parameters can be used in the request URL and the request body.

All the parameters can be used in the request body, while a limited set is supported in the request URL (while running the GET method).

Note

The parameter names are case sensitive.

Parameter nameDescription

searchType

Supported with both POST and GET methods

Required for the POST method

Optional for the GET method, default is saved search name

Search criteria by which you want to search.

Can be one of the following:

  • savedSearchName: Indicates that you want to search by the saved search name.
  • savedSearchId: Indicates that you want to search by the saved search ID.
  • queryString: Indicates that you want to search by a query string. This parameter is not supported while running a GET request.

searchValue

Supported with both POST and GET methods

Required

Value corresponding to the searchType specified.

Can be one of the following:

  • Saved search name
  • Saved search ID
  • Query string

Note: Tabular commands are not supported in the query string or the saved search query. For more information about tabular commands, see Search commands.

startTime

Supported with POST method only

Optional, default is now-60min


Date and time marking the starting point of the search.

Can be one of the following:

  • Time in the epoch format (in milliseconds). 
  • Time in the format, now<sign><value><unit>
    For example, now+60m or now-2.

The following definitions apply while specifying time in the format, now<sign><value><unit>:

  • <sign>: can be "+" or "-" depending on whether you want to specify a value after some time from now (+) or before some time from now (-).
  • <value>: refers to a whole number.
  • <unit>: can be either seconds, minutes, hours, or days.
    Units can be specified in the following ways:
    • Seconds: s, sec, secsseconds
    • Minutes: m, min, minsminutes
    • Hours: h, hr, hrs, hourhours
    • Days: d, daydays

Note: While running the POST request, the start time and end time parameters function in the following way:

  • While searching with the saved search name or ID: If not specified, the start and end time of the saved search is used.
  • While searching with the search query: If not specified, the default start and end time values are used (that is last 60 minutes from the time of running the search).

 

endTime

Supported with POST method only

Optional, default is now

Date and time marking the ending point of the search.

Can be one of the following:

  • Time in the epoch format. 
  • Time in the format, now<sign><value><unit>
    For example, now+60m or now-2.

The following definitions apply while specifying time in the format, now<sign><value><unit>:

  • <sign>: can be "+" or "-" depending on whether you want to specify a value after some time from now (+) or before some time from now (-).
  • <value>: refers to a whole number.
  • <unit>: can be either seconds, minutes, hours, or days.
    Units can be specified in the following ways:
    • Seconds: s, sec, secsseconds
    • Minutes: m, min, minsminutes
    • Hours: h, hr, hrs, hourhours
    • Days: d, daydays

Note: While running the POST request, the start time and end time parameters function in the following way:

  • While searching with the saved search name or ID: If not specified, the start and end time of the saved search is used.
  • While searching with the search query: If not specified, the default start and end time values are used (that is last 60 minutes from the time of running the search).

 

pageNumber

Supported with POST method only

Optional, default is 0

Index of the page from which records (or events) must be returned.

pageSize

Supported with POST method only

Optional, default is 100

Maximum number of records (or events) to return in a page.

resultCountReq

Supported with both POST and GET methods

Optional, default is Yes

Total count of search results available for the search run.

Can be one of the following:

  • Yes
  • No

source

Supported with both POST and GET methods

Optional, applicable only if the searchType is a saved search name.

Source type of the saved search.

Can be one of the following:

  • cp: Indicates that the saved search was imported via a content pack.
  • user: Indicates that the saved search was created by a user.

sourceName

Supported with both POST and GET methods

Optional, applicable only if the searchType is a saved search name.

Value corresponding to the source specified.

Can be one of the following:

  • Name of the content pack via which the saved search was imported.
  • Name of the user who created the saved search.

Response elements

The following sections help you understand the response elements:

Element definitions

Response elementDescription
Successful response

statusCode

String

A string describing the status code returned.

For more information, see HTTP status codes.

statusMessage 

String

Message explaining the reason for the response.

results

Array

Set of search results corresponding to the search type and search value specified.

totalRecords

Long

The total number of records (search results) present in the system.
Unsuccessful response

messages

Array

Details of the error – severity, error code, and error message.

Successful response sample

Note: Because search results can be quite verbose, in the following response, repeated elements have been omitted for clarity.

Response
{
    "statusCode": "200",
    "statusMessage": "Ok",
    "results": [{
        "timestamp": 1463764706366,
        "fieldValues": {
            "COLLECTOR_NAME": {
                "values": [{
                    "value": "ITDA Collection Metrics_Collection Metrics_clm-pun.bmc.com"
                }]
            },
            "HOST": {
                "values": [{
                    "value": "clm-pun.bmc.com"
                }]
            },
            "COLLECTOR": {
                "values": [{
                    "value": "C:\\Program Files\\BMC Software\\TrueSight\\ITDA\\station\\collection\\logs\\Collection_metrics.log"
                }]
            },
            "DATA_PATTERN": {
                "values": [{
                    "value": "ITDA Metrics"
                }]
            },
            "events": {
                "values": [{
                    "value": "1"
                }]
            }
        },
        "raw": "[2016-05-20 22:48:26.366] [COLLECTION_STATION] [collection-station_clm-pun.bmc.com] [duration-in-milliseconds=0, source=ITDA Collection Metrics_Collection Metrics_clm-pun.bmc.com, events=1, indexing-lag=60047]",
        "score": 0,
        "host": "clm-pun.bmc.com",
        "id": "AVTPLc7sQ0CjiY-3F2kF",
        "fields": ["COLLECTOR_NAME", "HOST", "COLLECTOR", "DATA_PATTERN", "events"]
    }],
    "totalRecords": 1
}

Unsuccessful response sample

{
    "messages": [{
        "severity": "Error",
        "code": "saved.search.with.provided.searchtype.or.searchvalue.doesnot.exist",
        "text": "No saved search found with provided savedSearchName "SS1" or User does not have access to it."
    }]
}

HTTP status codes

The following table describes the status codes that are likely to appear while working with this endpoint.

Status codeDescription
200

Request completed successfully.

Also occurs if no results were found.

400Invalid search type.
401Authorization error (invalid authorization token or authorization token not present).
404Incorrect saved search name.
500

Error occurred while processing the request. Occurrence of this error is rare.

For more information, see the error message. Alternatively, see the itda.log located at %BMC_ITDA_HOME%\logs.