2.3 Queries

The WSAPI includes a number of queries that allow callers to retrieve various types of data from the Operations Center server.

2.3.1 Throttle Mechanism

To prevent query responses from becoming unmanageably large, many queries support a response throttling mechanism. To limit the response size, the caller specifies a maximum record count, which truncates the response and provides a cursor for retrieving the remaining records.

For example, the following alarms request limits the number of alarms in the response to 50:

<getAlarms xmlns="http://wsapi.mosols.com">
<session>

   . . .
</session>
<elementDName>device_port=6789/server_host=devtower18.mosol.com/computer_minicomputer=Monitor+Distribution/BEM+Root+Element=Adapter%3A+Operations+Center+Experience+Manager/root=Elements</elementDName> 
<channelName>REALTIME</channelName> 
<throttle>
<maxRecords>50</maxRecords> 
</throttle>
</getAlarms>

If the target element has more than 50 alarms, the response includes the first 50 alarms, a cursor to access the remaining alarms, and a count of the remaining records in the query response:

<getAlarmsReturn>
<alarms>
   . . . <!-- 50 Alarm records here -->
</alarms>
<cursor>1172681096613</cursor>
<remainingAlarmsCount>31</remainingAlarmsCount> 
</getAlarmsReturn>

The caller can then pass the provided cursor value to the nextAlarms service to retrieve the remaining 31 alarms in the query response:

<< insert sample nextAlarms here >>>

Response throttling is available on Alarm, Element, Series Data, SLA, and SLA Health Data queries. Cursors returned in a throttled query are valid for the duration of the user session.

2.3.2 Element Queries

The API includes the element query services listed in Table 2-3.

Table 2-3 Element Query Services

Name

Description

getElement(session:WsSession, dName:string, inclusionSpec:ElementInclusionSpec, contentSpec:ElementContentSpec, throttle:ResponseThrottle):ElementResultSet

Retrieves an element and optionally, associated elements.

getAssociatedElements(session:WsSession, dName:string, inclusionSpec:ElementInclusionSpec, contentSpec:ElementContentSpec, throttle:ResponseThrottle):ElementResultSet

Retrieves elements associated with the specified element.

getRootElements(session:WsSession, inclusionSpec:ElementInclusionSpec, contentSpec:ElementContentSpec, throttle:ResponseThrottle):ElementResultSet

Retrieves elements starting at the Enterprise root.

findElements(session:WsSession, baseElemDName:string, searchSpec:ElementSearchSpec, contentSpec:ElementContentSpec, throttle:ResponseThrottle):ElementResultSet

Searches for child elements of a specified element using search strings.

nextElements(session:WsSession,cursor:string, throttle:ResponseThrottle):ElementResultSet

Retrieves additional records from a previous query.

Element queries have three basic components:

  • A starting point. For all queries except getRootElements, the starting point is specified in the call with a DName argument. The getRootElements service assumes the Enterprise root element is the starting point.

  • A specification for the elements to return. This specification is accomplished by using an <inclusionSpec> argument for the get services and a <searchSpec> for findElements.

  • A specification for the data to include in each returned element. A <contentSpec> argument specifies which data to include in each returned element for each of the service calls.

All element queries are capable of retrieving multiple element records and support a throttle (for more information, see Section 2.3.1, Throttle Mechanism).

To retrieve the undeliverable portion of an element query response, use the nextElements service.

The following sections describes services used to find and retrieve elements and their contents:

<inclusionSpec>

An <inclusionSpec> (WSDL type: <ElementInclusionSpec>) is used to traverse the physical and logical associations of the query’s base element to retrieve associated elements (see Section 2.1.1, Elements and their Relationships for more information on element relationships).

The following is a sample <inclusionSpec>:

<inclusionSpec>
  <childDepth>2</childDepth> 
  <includeLeftElements>true</includeLeftElements> 
  <includeRightElements>true</includeRightElements> 
  <forceDiscovery>true</forceDiscovery> 
</inclusionSpec>

When processing this <inclusionSpec>, the childDepth field first retrieves the physical (name) children of the query’s base element, up to the specified depth of 2. Then, for the base element and each included child, any element that is associated through a “left” or “right” relationship is included in the result set.

Each element in a result set (that was created with an <inclusionSpec>) includes lists of associated element DNames in the same result set. These DName lists are called includedChildDNames, includedLeftDNames, and includedRightDNames to reflect the type of relationship between the elements. For example, the following element view shows the Service Models root with one physical child named localMonitor. localMonitor has two source elements named END_USER_RESPONSE and HTTP.

Figure 2-7 Operations Center Explorer Pane

If the above <inclusionSpec> is used to query the Service Models element, the result set would include the following:

<elements>
  <item>
    <DName>root=Organizations</DName> 
    <includedChildDNames>
      <item>org=localMonitor/...</item> 
    </includedChildDNames>
    <includedLeftDNames /> 
    <includedRightDNames>
      <item>org=localMonitor/...</item> 
    </includedRightDNames>
    :    :    :
  </item>
  <item>
    <DName>org=localMonitor/...</DName> 
    <includedChildDNames /> 
    <includedLeftDNames> 
      <item>root=Organizations</item>
    </includedLeftDNames> 
    <includedRightDNames> 
      <item>END_USER_RESPONSE=END_USER_RESPONSE/...</item> 
      <item>HTTP=HTTP/...</item> 
    </includedRightDNames> 
    :    :    :
  </item>
  <item>
    <DName>END_USER_RESPONSE=END_USER_RESPONSE/...</DName> 
    <includedChildDNames /> 
    <includedLeftDNames> 
      <item>org=localMonitor/...</item> 
    </includedLeftDNames> 
    <includedRightDNames /> 
    :    :    :
  </item>
  <item>
    <DName>HTTP=HTTP/...</DName> 
    <includedChildDNames /> 
    <includedLeftDNames> 
      <item>org=localMonitor/...</item> 
    </includedLeftDNames> 
    <includedRightDNames /> 
    :    :    :
  </item>
</elements>

<searchSpec>

A <searchSpec> (WSDL type: <ElementSearchSpec>) is used in the findElements query in place of an <inclusionSpec>. With a <searchSpec>, a searchString field specifies which children of the query’s base element should be returned. (Refer to Using Find to Search for Elements in the Operations Center 5.6 User Guide for instructions on creating a search string using the Find command’s Advanced tab.) Thus, a findElements result set can include elements in any part of the base element’s downward hierarchy, without including the elements in between. Queries using a <searchSpec> also do not populate the included nnn lists in the returned elements.

Another important distinction between a <searchSpec> and an <inclusionSpec> is that a <searchSpec> does not distinguish between logical and physical relationships. With a <searchSpec>, right-relation (source) elements are treated as if they are physical (name) children, for the purpose of scoping the search. With a <searchSpec>, the caller can retrieve the name children of a source element.

A sample <searchSpec>:

<searchSpec>
  <maxDepth>10</maxDepth> 
  <maxRecords>50</maxRecords> 
  <maxWaitSeconds>60</maxWaitSeconds> 
  <searchString>(objectClass=HTTP)</searchString> 
</searchSpec>

By using this <searchSpec> against the Service Models root shown in the previous section, the caller can retrieve all of the HTTP test elements downward in its hierarchy.

<contentSpec>

For all element queries, a <contentSpec> (WSDL type: <ElementContentSpec>) specifies the optional contents of the included elements that should be populated in the result set. Specific parts of an element have been made optional either because they were deemed unnecessary for many Web services clients (for example, icon descriptors), or because there is an implicit overhead cost to retrieving the information that should not be incurred unless the data is actually needed (for example, certain attribute values). Overhead for retrieved data is most severe when querying elements from a Operations Center InterConnection adapter.

2.3.3 Alarm Queries

The API includes the alarm query services listed in Table 2-4.

Table 2-4 Alarm Query Services

Name

Description

getAlarms(session:WsSession, elementDName:string, channelName:String, throttle:ResponseThrottle):AlarmResultSet

Retrieves alarms for an element in a real-time channel.

getHistoricalAlarms(session:WsSession, elementDName:string, channelName:String, from:Date, to:Date, throttle:ResponseThrottle): AlarmResultSet

Retrieves alarms for an element in a historical channel.

getBreaches(session:WsSession, elementDName:string, slaName:String, objectiveName:String, from:Date, to:Date, throttle:ResponseThrottle): AlarmResultSet

Retrieves SLA breach alarms for an element.

getOutages(session:WsSession, elementDName:string, slaName:String, objectiveName:String, from:Date, to:Date, throttle:ResponseThrottle): AlarmResultSet

Retrieves SLA outage alarms for an element.

nextAlarms(session:WsSession,cursor:string, throttle:ResponseThrottle):AlarmResultSet

Retrieves additional records from a previous query.

All alarm queries are scoped to a single element, specified by the elementDName argument. The channelName argument specifies the type of alarm to be retrieved. Valid channel names for a Operations Center server should be retrieved by using the getServerInfo service.

Date arguments are always required.

The getOutages and getBreaches services include optional slaName and objectiveName arguments. These can limit the alarms query to a specified SLA, or to a specified objective name within an SLA. If slaName is not specified, objectiveName is ignored.

All alarm queries are capable of retrieving multiple alarm records and support a throttle (see Section 2.3.1, Throttle Mechanism for more information).

To retrieve the undeliverable portion of an alarm query response, use the nextAlarms service.

2.3.4 Series Data Queries

The API includes a single service, listed in Table 2-5, for querying series data.

Table 2-5 Series Data Queries

Name

Description

getSeriesData(session:WsSession, elementDName:string, seriesDescriptor:MosSeriesDescriptor, throttle:ResponseThrottle):SeriesDataResultSet

Retrieves the specified series data for an element.

A series data query requires an elementDName and a valid <seriesDescriptor> (WSDL type: <MosSeriesDescriptor>) for that element. Series descriptors for an element are part of the optional data that can be returned with an element by setting the includeSeriesInfo flag in the <contentSpec> argument of an element query. Here are some sample series descriptors as returned by an element query:

<seriesDescriptors>
  <item>
    <expressionName>devtower18.mosol.com:6789.NTLM test on qaoracledb.HTTP.001-main page qaoracledb.TransactionTime</expressionName> 
    <from>1970-01-01T00:00:00.000Z</from> 
    <profileName>ElementProfile</profileName> 
    <to>2007-03-05T22:24:05.580Z</to> 
    <type>TYPE_SIMPLE_FLOAT</type> 
  </item>
  <item>
    <expressionName>Element Condition Change</expressionName> 
    <from>2006-12-12T23:04:32.257Z</from> 
    <profileName>Service Levels</profileName> 
    <to>2007-03-05T22:24:05.580Z</to> 
    <type>TYPE_CONDITION</type> 
  </item>  :    :    :

When a series descriptor is embedded in an element, the From and To time stamps reflect the available data range for series. When returning a series descriptor to the server in a series data query, clients should update these date fields to specify the desired portion of the series.

The type field of the series descriptor is important for processing the response data. The primary payload of a series data result set is an array of DataPoint objects. Close examination of the WSDL reveals that DataPoint is an abstract type:

Figure 2-8 The DataPoint Abstract Type

Table 2-6 lists the correlation between the type field in the series descriptor and the type of DataPoint objects returned in a series data query.

Table 2-6 Correlation between Field and DataPoint Types

Type

DataPoint Type

TYPE_SIMPLE_STRING

SimpleDataPoint

TYPE_SIMPLE_NUMERIC

SimpleDataPoint

TYPE_SIMPLE_FLOAT

SimpleDataPoint

TYPE_ALARM

AlarmDataPoint

TYPE_CONDITION

ConditionDataPoint

TYPE_CONDITION_COUNT

ConditionCountDataPoint

The series data query can retrieve multiple records and supports a throttle (for more information, see Section 2.3.1, Throttle Mechanism).

To retrieve the undeliverable portion of a series data query response, use the nextSeriesData service as described in Table 2-7.

Table 2-7 nextSeriesData Service

Name

Description

nextSeriesData(session:WsSession,cursor:string, throttle:ResponseThrottle):SeriesDataResultSet

Retrieves additional records from a previous query.

2.3.5 Health Data Queries

The API includes a single service for querying SLA health data, as shown in Table 2-8.

Table 2-8 Health Data Queries

Name

Description

getSlaHealthData(session:WsSession, elementDName:string, slaName:string, objectiveName:string, from:dateTime, to:dateTime, blockSize:IntervalBlock, throttle:ResponseThrottle):HealthDataResultSet

Retrieves the SLA health data for an element.

The health data query is similar to the series data query and some of the alarm queries. The primary difference is that health data responses represent a state over a period of time. The length of time represented by each health data record in the result set is specified by blockSize argument, ranging from a minute to a month.

As with the getBreaches and getOutages queries, the slaName and objectiveName arguments are optional in this query. If they are not specified, the results represent the health of the element across all SLAs in which it participates.

The health data query can retrieve multiple records and supports a throttle (see Section 2.3.1, Throttle Mechanism for more information).

To retrieve the undeliverable portion of a health data query response, use the nextHealthData service as described in Table 2-9.

Table 2-9 nextHeathData Service

Name

Description

nextHealthData(session:WsSession,cursor:string, throttle:ResponseThrottle):HealthDataResultSet

Retrieves additional records from a previous query.

2.3.6 SLA Queries

The API includes a single service for querying SLAs, as shown in Table 2-10.

Table 2-10 SLA Queries

Name

Description

getAllSlas(session:WsSession, throttle:ResponseThrottle):SlaResultSet

Retrieves all SLAs defined on the server.

As the name implies, this query simply retrieves all defined SLAs. Throttling is available to manage response size. To retrieve subsequent portions of a SLA query, use nextSlas as shown in Table 2-11.

Table 2-11 nextSlas

Name

Description

nextSlas(session:WsSession,cursor:string, throttle:ResponseThrottle):SlaResultSet

Retrieves additional records from a previous query.