Search API

The Search API provides methods to search entities and metrics that are available in BMC Helix Capacity Optimization. The use of search syntax invokes the Search API. The search results are split in separate pages with each page containing 20 results.

Before you begin

Ensure that the following requirements are met:

API methods

The API supports the following methods:

Method

URI pattern

Description

Required activity

Example XSD files

Request

Response

POST

dh-services/search/entity  

Searches the specified entity in the catalog based on the query expression specified in the request and returns the available results.

For example, use this API to search for a specific system, domain, analysis, or model.

Read access to Search API

POST

dh-services/search/tag

Searches the specified tag in the catalog based on the query expression specified in the request and returns the available results.

Read access to Search API

POST

dh-services/search/tagindex/build

Builds the catalog of tags.

Write access to Search API

-

POST

dh-services/search/tagindex/update

Updates the tag index with the list of items (SearchableItems).

Write access to Search API

POST

dh-services/search/tagindex/delete

Deletes the specified tag entry in the catalog based on the query parameter.

Write access to Search API

POST

dh-services/search/rebuild

Rebuilds the indexes specified in RebuildIndexRequest argument.

Write access to Search API

Sample request and response files

The following examples describe the type of searches that can be conducted using the Search API:

Search for entity

The following sample request and response files are used to search for an entity and view the search results. The search query must be specified as per the Search-syntax.

Sample request file
<SearchQuery>
  <queryString>BCPPOD-1</queryString>
  <pageSize>20</pageSize>
  <pageNo>0</pageNo>
</SearchQuery>
Sample response file
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchResults>
    <searchQuery>vl-tlv-bcm-dv01</searchQuery>
    <hasMoreResults>true</hasMoreResults>
    <estimatedMatches>36</estimatedMatches>
    <pageNumber>0</pageNumber>
    <underlyingQuery>(((+relclass_high:vl +relclass_high:tlv +relclass_high:bcm +relclass_high:dv01)^7.0) | ((+relclass_mid:vl +relclass_mid:tlv +relclass_mid:bcm +relclass_mid:dv01)^2.0) | (+relclass_low:vl +relclass_low:tlv +relclass_low:bcm +relclass_low:dv01))</underlyingQuery>
    <items>
   <item>
            <idField></idField>
            <score>7.134374</score>
            <fields>
                <entry>
                    <fieldName>itemtype</fieldName>
                    <fieldList>
                        <field>
                            <name>itemtype</name>
                            <type>0</type>
                            <values>normal</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>series</fieldName>
                    <fieldList>
                        <field>
                            <name>series</name>
                            <type>1</type>
                            <compositeValues>
                                <entry>
                                    <key>SOB3042</key>
                                    <value>GLOBAL</value>
                                </entry>
                            </compositeValues>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>relevantseries</fieldName>
                    <fieldList>
                        <field>
                            <name>relevantseries</name>
                            <type>1</type>
                            <compositeValues>
                                <entry>
                                    <key>SOB3042</key>
                                    <value>Datastore Ids</value>
                                </entry>
                            </compositeValues>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>location</fieldName>
                    <fieldList>
                        <field>
                            <name>location</name>
                            <type>0</type>
                            <values>UNKNOWN</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>sys</fieldName>
                    <fieldList>
                        <field>
                            <name>sys</name>
                            <type>0</type>
                            <values>vl-tlv-bcm-dv01</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>seriesid</fieldName>
                    <fieldList>
                        <field>
                            <name>seriesid</name>
                            <type>0</type>
                            <values>SOB3042</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>appid</fieldName>
                    <fieldList>
                        <field>
                            <name>appid</name>
                            <type>0</type>
                            <values>2045</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>type</fieldName>
                    <fieldList>
                        <field>
                            <name>type</name>
                            <type>0</type>
                            <values>object</values>
                            <values>series</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>metricname</fieldName>
                    <fieldList>
                        <field>
                            <name>metricname</name>
                            <type>0</type>
                            <values>Datastore Ids</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>resname</fieldName>
                    <fieldList>
                        <field>
                            <name>resname</name>
                            <type>0</type>
                            <values>DSTORE_IDS</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>ID</fieldName>
                    <fieldList>
                        <field>
                            <name>ID</name>
                            <type>0</type>
                            <values>SOB3042</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>subobject</fieldName>
                    <fieldList>
                        <field>
                            <name>subobject</name>
                            <type>0</type>
                            <values>GLOBAL</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>sysid</fieldName>
                    <fieldList>
                        <field>
                            <name>sysid</name>
                            <type>0</type>
                            <values>2050</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
            </fields>
        </item>
        <item>
        ...
           
    </items>
</SearchResults>

Search for tag

The following sample request and response files are used to search for a tag and view the search results. The search query must be specified as per the Search-syntax.

Sample request file
<SearchQuery>
<queryString>Xen</queryString>
<pageSize>20</pageSize>
<pageNo>0</pageNo>
</SearchQuery>
Sample response file
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchResults>
    <searchQuery>Xen</searchQuery>
    <hasMoreResults>false</hasMoreResults>
    <estimatedMatches>1</estimatedMatches>
    <pageNumber>0</pageNumber>
    <underlyingQuery>(relclass_high:xen^3.0 | relclass_mid:xen^2.0 | relclass_low:xen)</underlyingQuery>
    <items>
        <item>
            <idField></idField>
            <score>3.8033605</score>
            <fields>
                <entry>
                    <fieldName>itemtype</fieldName>
                    <fieldList>
                        <field>
                            <name>itemtype</name>
                            <type>0</type>
                            <values>normal</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>statusid</fieldName>
                    <fieldList>
                        <field>
                            <name>statusid</name>
                            <type>0</type>
                            <values>3</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>color</fieldName>
                    <fieldList>
                        <field>
                            <name>color</name>
                            <type>0</type>
                            <values>#00FFFF</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>tagid</fieldName>
                    <fieldList>
                        <field>
                            <name>tagid</name>
                            <type>0</type>
                            <values>10010</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>description</fieldName>
                    <fieldList>
                        <field>
                            <name>description</name>
                            <type>0</type>
                            <values>The OS family of the system</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>tagtypeid</fieldName>
                    <fieldList>
                        <field>
                            <name>tagtypeid</name>
                            <type>0</type>
                            <values>2</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>ID</fieldName>
                    <fieldList>
                        <field>
                            <name>ID</name>
                            <type>0</type>
                            <values>10010</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>tag</fieldName>
                    <fieldList>
                        <field>
                            <name>tag</name>
                            <type>0</type>
                            <values>Xen</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
                <entry>
                    <fieldName>tagtype</fieldName>
                    <fieldList>
                        <field>
                            <name>tagtype</name>
                            <type>0</type>
                            <values>OS Family</values>
                            <compositeValues/>
                        </field>
                    </fieldList>
                </entry>
            </fields>
        </item>
    </items>
</SearchResults>

Build tag index

The following sample response file is generated for a request to build the tag index.

Sample response file
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseMessage>
   <status>OK</status>
   <message>Index TAG_INDEX has been successfully built.</message>
</ResponseMessage>

Update tag index

The following sample response file is generated for a request to update TAG_INDEX entries.

Sample response file
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseMessage>
   <status>OK</status>
   <message>Index TAG_INDEX has been successfully udpated.</message>
</ResponseMessage>

Delete tag index entries

The following sample response file is generated for a request to delete all TAG_INDEX entries.

Sample response file
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseMessage>
   <status>OK</status>
   <message>Delete operation for tag index: TAG_IDX based on search expression: DELETE_ALL_TAG_IDX_ENTRIES  was successful.</message>
</ResponseMessage>

Rebuild index

The following sample request and response files are used to rebuild the TAG_INDEX index and view the status.

Sample request file
<?xml version="1.0" encoding="UTF-8"?>
<RebuildIndexRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="RebuildIndexRequest.xsd">
 <index>TAG_INDEX</index>
</RebuildIndexRequest>
Sample response file
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseMessage>
   <status>OK</status>
   <message>Sucessfully rebuilt indexes</message>
</ResponseMessage>

Result attributes

The following table describes the result attributes contained in the XML Schema:

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*