The WSAPI includes a number of queries that allow callers to retrieve various types of data from the Operations Center server.
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.
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:
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>
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.
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.
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.
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. |
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. |
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. |