Search API

The Search API provides methods to search entities and metrics present in TrueSight Capacity Optimization. This is made possible by making use of the Search syntax. The search results are split in separate pages, each page containing 20 elements.

Before you begin

  • Ensure that you have valid user credentials in Base64-encoded format for the Authorization HTTP header. For more details, see Restful web services authentication.
  • Ensure that your user role has the Enable access to Search API activity (API_SEARCH) assigned to it. The out-of-the-box role API-Client has access to all the APIs by default. For more information about managing roles and activities, see Adding and managing roles.

All methods

Method

URI pattern

Description

Samples

Example XSD files
RequestResponse

POST

search/entity  

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

Sample

SearchQuery

SearchableItems

SearchResults

POST
search/tag
Searches the TAG_INDEX based on the query expression specified in the request and returns the available results.

Sample

SearchQuerySearchResults
POST
search/tagindex/build
Builds the TAG_INDEX.

Sample

-ResponseMessage
POST
search/tagindex/update
Updates the tag index with the list of items (SearchableItems).

Sample

SearchableItemsResponseMessage
POST
search/tagindex/delete
Deletes the TAG_INDEX entries based on the SearchQuery.

Sample

SearchQueryResponseMessage
POST
search/rebuild
Reloads the indexes specified in ReloadIndexRequest argument.SampleReloadIndexRequestResponseMessage

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.

 Click here to view/hide the request sample file...
<SearchQuery>
  <queryString>BCPPOD-1</queryString>
  <pageSize>20</pageSize>
  <pageNo>0</pageNo>
</SearchQuery>
 Click here to view/hide the response sample 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.

 Click here to view/hide the request sample file...
<SearchQuery>
<queryString>Xen</queryString>
<pageSize>20</pageSize>
<pageNo>0</pageNo>
</SearchQuery>
 
 Click here to view/hide the response sample 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.

 Click here to view/hide the response sample 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.

 Click here to view/hide the response sample 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.

 Click here to view/hide the response sample 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.

 Click here to view/hide the request sample file...
<?xml version="1.0" encoding="UTF-8"?>
<ReloadIndexRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ReloadIndexRequest.xsd">
  <index>TAG_INDEX</index>
</ReloadIndexRequest>
 Click here to view/hide the response sample 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:

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