XML API filter types

Overview

You can include a filter in an XML request to limit the returned objects to only those that you require. The following filter and result filtering types describe the fundamental elements of filtering objects requested through the XML API. These types are applicable to a variety of methods that perform functions such as inventory requests, alarm retrieval, statistics data retrieval, and object configuration.

The xmlApiTypes.xsd file in the Schema Reference describes the FilterHolder type and ChildrenFilterHolder type .

Note: Nokia recommends that you create filters that have a top-down hierarchical structure to make them as restrictive as possible. This means that a filter lists the higher-level object properties before the lower-level properties, as defined in the NFM-P object hierarchy. See the XML API Reference for object hierarchy information.

The SOAP header and footer are shown in code examples only if required to provide context.

FilterHolder type

The FilterHolder type limits or refines the objects returned by an XML API request. The following figure shows a filter example for service.Site objects that have a displayedName value equal to Some special site.

Figure 6-1: Filter example using equal operator

<filter class="service.Site">

   <equal name="displayedName" value="Some special site"/>

</filter>

The following figure shows a filter example that contains leaf and composite filter elements that use multiple operators to compare numeric and string values.

Figure 6-2: Filter example using multiple operators

<filter>

   <and>

      <greater name="localAS" value="0"/>

      <or>

         <equal name="domain" value="network"/>

         <between name="preference" first="150" second="200" />

      </or>

   </and>

</filter>

ChildrenFilterHolder type

The ChildrenFilterHolder type is similar to the FilterHolder type; however, the ChildrenFilterHolder type can contain nested children filters that are applied to the children of an object. This type is used for find and findToFile methods.

The attribute “childClass” is required if the attributes used in the children filter are specific to a child class.

Setting the attribute “withChildrenOnly” to “true” returns only objects with children present. Setting the attribute to “false” returns objects of the specified class regardless of child presence. This attribute is optional and is set to “false” by default.

Figure 6-3, Nested filter example returns only IES services, IES sites, L3 access interfaces and L3 anti-spoofing object if all filter level criteria are met. If at any level of the nested filter all the children are filtered out, none of parent objects are returned due to the withChildrenOnly equal true.

The first level filter applies to IES services which have a description that starts with “Static”.

The second level filter applies to only the IES sites because of the class specified in childClass attribute. If there exists an IES site that has a siteId in the 198.51.100.0/24 subnet, the IES service is returned.

The third level filter is applied to only L3 access interfaces because of the class specified in childClass attribute. If there exists L3 access interfaces that have a primary IPv4 address in the 10.1.2.0/24 subnet, the IES site is returned.

The fourth level filter applies to the L3 anti-spoofing object because of the class specified in childClass attribute. If there exists L3 anti-spoofing objects with arpPopulate attribute equal disabled, the L3 access interface is returned.

Figure 6-3: Nested filter example

<filter class="ies.Ies" >

   <wildcard name="description" value="Static%"/>

   <children>

      <filter class="ies.Ies" childClass="ies.Site" withChildrenOnly="true">

         <wildcard name="siteId" value="198.51.100.%" />

         <children>

            <filter class="ies.Site" childClass="ies.L3AccessInterface" withChildrenOnly="true" >

               <wildcard name="primaryIPv4Address" value="10.1.2.%"/>

               <children>

                  <filter class="ies.L3AccessInterface" childClass="antispoof.L3AntiSpoofing" withChildrenOnly="true">

                     <equal name="arpPopulate" value="disabled"/>

                  </filter>

               </children>

            </filter>

         </children>

      </filter>

   </children>

</filter>

Use subject to agreed restrictions on disclosure and use.