Query the CMDB

The CMDB is queried using the APIs described in UCMDB Query Methods. The queries and the returned CMDB elements always contain real UCMDB IDs. For examples of using query methods, see Query Example.

Just In Time Response Calculation

For all query methods, the UCMDB server calculates the values requested by the query method when the request is received, and returns results based on the latest data. The result is always calculated at the time the request is received, even if the TQL query is active and there is a previously calculated result. Therefore, the results of running a query returned to the client application may be different from the results of the same query displayed on the user interface.

Processing Large Responses

The response to a query always includes the structures for the data requested by the query method, even if no actual data is being transmitted. For many methods where the data is a collection or map, the response also includes the ChunkInfo structure, comprised of chunksKey and numberOfChunks. The numberOfChunks field indicates the number of chunks containing data that must be retrieved.

The maximum transmission size of data is set by the system administrator. If the data returned from the query is larger than the maximum size, the data structures in the first response contain no meaningful information, and the value of the numberOfChunks field is 2 or greater. If the data is not larger than the maximum, the numberOfChunks field is 0 (zero), and the data is transmitted in the first response. Therefore, in processing a response, check the numberOfChunks value first. If it is greater than 1, discard the data in the transmission and request the chunks of data. Otherwise, use the data in the response.

For information on handling chunked data, see pullTopologyMapChunks and releaseChunks in the UCMDB Module Query Methods topic, and the schema documentation for ChunkInfo.

Specifying Properties to Return

CIs and relations generally have many properties. Some methods that return collections or graphs of these items accept input parameters that specify which property values to return with each item that matches the query. The CMDB does not return empty properties. Therefore, the response to a query may have fewer properties than requested in the query.

This section describes the types of sets used to specify the properties to return. For more information, see the documentation on the PropertiesSets schema.

Properties can be referenced in two ways:

• By their names

• By using names of predefined properties rules. Predefined properties rules are used by the CMDB to create a list of real property names.

When an application references properties by name, it passes a PropertiesList element.

There are two types of predefined properties: qualifier properties and simple properties.

• Qualifier properties. Use this when the client application should pass a QualifierProperties element (a list of qualifiers that can be applied to properties). The CMDB converts the list of qualifiers passed by the client application to the list of the properties to which at least one of the qualifiers applies. The values of these properties are returned with the CI or Relation elements.

• Simple properties. To use simple rule-based properties, the client application passes a SimplePredefinedProperty or SimpleTypedPredefinedProperty element. These elements contain the name of the rule by which the CMDB generates the list of properties to return. The rules that can be specified in a SimplePredefinedProperty or SimpleTypedPredefinedProperty element are CONCRETE, DERIVED, and NAMING.

Concrete Properties

Concrete properties are the set of properties defined for the specified CIT. The properties added by derived classes are not returned for instances of those derived classes.

A collection of instances returned by a method may consist of instances of a CIT specified in the method invocation and instances of CITs that inherit from that CIT. The derived CITs inherit the properties of the specified CIT. In addition, the derived CITs extend the parent CIT by adding properties.

Derived Properties

Derived properties are the set of properties defined for the specified CIT and, for each derived CIT, the properties added by the derived CIT.

Naming Properties

The naming properties are display_label and data_name.

Other Property Specification Elements

• PredefinedProperties

  PredefinedProperties can contain a QualifierProperties element and a SimplePredefinedProperty element for each of the other possible rules. A PredefinedProperties set does not necessarily contain all types of lists.

• PredefinedTypedProperties

  PredefinedTypedProperties is used to apply a different set of properties to each CIT. PredefinedTypedProperties can contain a QualifierProperties element and a SimpleTypedPredefinedProperty element for each of the other applicable rules. Because PredefinedTypedProperties is applied to each CIT individually, derived properties are not relevant. A PredefinedProperties set does not necessarily contain all applicable types of lists.

• CustomProperties

  CustomProperties can contain any combination of the basic PropertiesList and the rule-based property lists. The properties filter is the union of all the properties returned by all the lists.

• CustomTypedProperties

  CustomTypedProperties can contain any combination of the basic PropertiesList and the applicable rule-based property lists. The properties filter is the union of all the properties returned by all the lists.

• TypedProperties

  TypedProperties is used to pass a different set of properties for each CIT. TypedProperties is a collection of pairs composed of type names and properties sets of all types. Each properties set is applied only to the corresponding type.