Result filtering

Overview

Result filters limit the attributes, objects, and child objects that are returned in a result. If no attribute tags are defined in a result filter, then all properties at the level of resultFilter are returned. For more information, see the xmlApiTypes.xsd file in the Schema Reference.

The <attribute>propertyName</attribute> tag specifies that the property is to be returned. When using multiple levels of nested resultFilter, a single empty attribute tag <attribute/> returns no attributes for that object level.

The <children> list of nested resultFilters</children> tag specifies that the given types of children be returned. The nested resultFilters can contain the class attributes specifying the package qualified class name of the child to be returned.

If the children tag is empty, no children are returned. If the children tag is not defined, then all children of this object are returned.

The class attribute on nested child resultFilters allows a class of ManageObject to be specified, which is the base class for all classes.

If the optional recursive attribute is set to yes in the children specification, then the children are filtered according to the same rules as the parent; nested resultFilters are not required or allowed. The recursive attribute default is no. See Figure 6-5, resultFilter example using recursive children attribute for an example.

Within a nested class resultFilter, by specifying an empty <attribute/> tag, no attributes are returned for the specified class object. However, children and grandchildren of that class object can be returned by including attribute tags with values. See Figure 6-7, Nested resultFilter example specifying only child attributes for an example.

The following table lists some commonly used methods that implement the resultFilter type as a filter input parameter. See the Schema Reference and XML API Reference for information about other methods.

Table 6-1: Commonly used methods type definitions

The following figure shows a nested resultFilter that returns the objectFullName and status attributes from the top-level object. The top-level object may have many children but the nested resultFilter specifies only objects of equipment.Port class are returned. Therefore, only the objectFullName attribute of equipment.Port object is returned with no children of its own.

Figure 6-4: Nested resultFilter example

<resultFilter>

   <attribute>objectFullName</attribute>

   <attribute>status</attribute>

   <children>

      <resultFilter class="equipment.Port">

         <attribute>objectFullName</attribute>

         <children/>

      </resultFilter>

   </children>

</resultFilter>

The following figure shows the same result filter rule applied to returned objects and their children, where only objectFullName is returned for all children.

Figure 6-5: resultFilter example using recursive children attribute

<resultFilter>

   <attribute>objectFullName</attribute>

   <children recursive="yes"/>

</resultFilter> 

The following figure shows a nested resultFilter that returns four attributes from the top-level object along with attributes from two specific children classes.

Figure 6-6: Nested resultFilter example for multiple child classes

<resultFilter>

   <attribute>objectFullName</attribute>

   <attribute>displayedName</attribute>

   <attribute>name</attribute>

   <attribute>description</attribute>

   <children>

      <resultFilter class="nqueue.Entry">

         <attribute>objectFullName</attribute>

         <attribute>id</attribute>

         <attribute>cir</attribute>

         <attribute>pir</attribute>

      </resultFilter>

      <resultFilter class="nqueue.ForwardingClass">

         <attribute>objectFullName</attribute>

         <attribute>forwardingClass</attribute>

         <attribute>queueId</attribute>

      </resultFilter>

   </children>

</resultFilter>

The following figure shows a nested resultFilter with a class definition and no attribute defined. This returns two attributes from the top-level object and attributes from the CardSlot class, but nothing from the Shelf class.

Figure 6-7: Nested resultFilter example specifying only child attributes

<resultFilter>

   <attribute>activeManagementIp</attribute>

   <attribute>ipAddress</attribute>

   <children>

      <resultFilter class="equipment.Shelf">

         <attribute/>

         <children>

            <resultFilter class="equipment.CardSlot">

               <attribute>assignedCardSubType</attribute>

               <attribute>cardProtectionRowStatus</attribute>

               <attribute>slotId</attribute>

               <children/>

            </resultFilter>

         </children>

      </resultFilter>

   </children>

</resultFilter>

The following figure shows an example of a resultFilter in an object configuration request that uses the generic.GenericObject.configureInstanceWithResult method. See Configuration methods for information about the generic methods that apply to all object types.

Figure 6-8: resultFilter example using generic method

<SOAP:Body>

   <generic.GenericObject.configureInstanceWithResult xmlns="xmlapi_1.0">

      <deployer>immediate</deployer>

      <!-- Network Interface -->

      <distinguishedName>network:10.1.1.223:router-1:ip-interface-5</distinguishedName>

      <includeChildren>false</includeChildren>

      <configInfo>

         <rtr.NetworkInterface>

            <actionMask>

               <bit>modify</bit>

            </actionMask>

            <!-- vRtrIfUp/vRtrIfDown -->

            <administrativeState>vRtrIfUp</administrativeState>

         </rtr.NetworkInterface>

      </configInfo>

      <resultFilter>

         <attribute>objectFullName</attribute>

         <attribute>displayedName</attribute>

         <children recursive="yes" />

      </resultFilter>

   </generic.GenericObject.configureInstanceWithResult>

</SOAP:Body>