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 activityExample XSD files
RequestResponse

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
SearchQuery

SearchableItems

SearchResults

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 APISearchQuerySearchResults
POST
dh-services/search/tagindex/build
Builds the catalog of tags.Write access to Search API-ResponseMessage
POST
dh-services/search/tagindex/update
Updates the tag index with the list of items (SearchableItems).Write access to Search APISearchableItemsResponseMessage
POST
dh-services/search/tagindex/delete
Deletes the specified tag entry in the catalog based on the query parameter.Write access to Search APISearchQueryResponseMessage
POST
dh-services/search/rebuild
Rebuilds the indexes specified in RebuildIndexRequest argument.Write access to Search APIReloadIndexRequestResponseMessage

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.

<SearchQuery>
  <queryString>BCPPOD-1</queryString>
  <pageSize>20</pageSize>
  <pageNo>0</pageNo>
</SearchQuery>
 <?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.

<SearchQuery>
<queryString>Xen</queryString>
<pageSize>20</pageSize>
<pageNo>0</pageNo>
</SearchQuery>
<?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.

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

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

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

<?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>
<?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:

Artifact

Attribute

Description

searchResult

estimatedMatches

Represents the number of results retrieved by the query string

hasMoreElements

True if there are more pages contain results

pageNumber

Represents the current page of results

query

Represents the query executed

item

app

Represents the name of the domain where the entity is contained

appid

Represents the id of the domain

breadcrumb

Represents the breadcrumb of the entity

breadcrumbid

Represents the breadcrumb id of the entity

entid

Represents the id of the entity (for example, SYS1234,WKLD4321)

enttype

Represents the type of the entity (for example, Virtual Machine - AIX LPAR)

sys

Represents the name of the system

sysid

Represents the id of the system

wkld

Represents the name of the business driver

wkldid

Represents the id of the business driver

tag

Represents the tag of the entity

type

Represents the type of the result (for example, sys, report, app)


Was this page helpful? Yes No Submitting... Thank you

Comments