Inventory retrieval methods

Overview

The XML API provides the following methods to retrieve information:

• find—retrieves the set of objects that match the request criteria; the result is returned in XML format; see find method in this section for more information

• findToFile—retrieves the set of objects that match the request criteria and stores the result in a file on a local or remote host; see findToFile method in this section for more information

• findFaults—retrieves alarms that match the request criteria; see Chapter 11, Fault management for more information.

Note: Other methods in the equipment and network packages can be used to retrieve specific objects and classes. Nokia does not recommend the use of these methods because they are not optimized.

The following table lists and describes the XML methods and parameters that an OSS client can use to retrieve objects.

Table 13-1: XML object retrieval methods

find method

The find method returns a set of objects of the type specified in the <fullClassName> element that match the filter criteria. The method response is a streamed XML result.

The following figure shows a request to find an ACL IP filter.

Figure 13-2: find request example

<SOAP:Body> 

   <find xmlns="xmlapi_1.0"> 

      <fullClassName>aclfilter.IpFilter</fullClassName> 

      <filter> 

         <equal name="objectFullName" value="IP Filter:1000"/> 

      </filter> 

   </find> 

</SOAP:Body>

findToFile method

The findToFile method returns a set of objects of the type specified in the fullClassName element that match the filter criteria. You can specify the following result file storage options:

• save the file locally on the NFM-P server

• use FTP to transfer the results to a remote host

By default, the findToFile method runs synchronously, which means that one request has to complete and return before the processing of the next request begins.

The NFM-P returns the following when a findToFile request cannot be processed:

• asynchronous request:

  • HTTP error message, if a request timeout occurs

  • JMS notification, for an error during the query execution or file creation

• synchronous request:

  • HTTP error message, if the number of requests exceeds the maximum allowed or a request timeout occurs

The following figure shows a request to retrieve historical statistics from an NE.

Figure 13-3: findToFile request example

<SOAP:Body>

   <findToFile xmlns="xmlapi_1.0">

      <fullClassName>equipment.InterfaceAdditionalStatsLogRecord</fullClassName>

      <filter>

         <and>

            <equal name="monitoredObjectPointer" value="network:10.1.202.93:shelf-1:cardSlot-1:card:daughterCardSlot-1:daughterCard:port-3"/>

            <between name="timeCaptured" first="1127142900000" second="1127143800000"/>

         </and>

      </filter>

      <fileName>Equipment.InterfaceAdditionalStatsLogRecord.xml</fileName>

   </findToFile>

</SOAP:Body>

For synchronous findToFile requests, the NFM-P sends the following findToFile response shown in the following figure if the request contains no errors.

Figure 13-4: findToFileResponse message example

<findToFileResponse xmlns="xmlapi_1.0">

If a findToFile request contains an error, the response message contains an exception that indicates the type of error. See Chapter 9, XML message structure for information about the XML message structure and exception messages.

When all request processing is complete and the results are stored in a file, the NFM-P sends a fileAvailableEvent JMS notification. The notification includes the result and the request ID, as shown in the following figure.

Figure 13-5: fileAvailableEvent JMS notification example

<SOAP:Body>

   <jms xmlns="xmlapi_1.0">

      <fileAvailableEvent>

         <requestID>JMS_client@n</requestID>

         <fileName>asynchronous_request.xml</fileName>

      </fileAvailableEvent>

   </jms>

</SOAP:Body>

If the request does not complete successfully, the notification contains an exception. See FileAvailableEvent example in Appendix B, JMS events for more information.

Scheduled findToFile export

The findToFile method supports the export of data using the NFM-P scheduler framework. The following table describes how to schedule a findToFile data export.

Table 13-2: Scheduled findToFile export

<generic.GenericObject.configureChildInstance xmlns="xmlapi_1.0">
   <deployer>immediate</deployer>
   <distinguishedName>scheduleManager</distinguishedName>           
   <childConfigInfo>      
      <schedule.SamSchedule>        
         <actionMask>        
            <bit>create</bit>
         </actionMask>        
         <id>10</id>                    
         <displayedName>samSchedule-10</displayedName>
         <frequency>minute</frequency>
         <onGoing>true</onGoing>
         <runEveryMinute>5</runEveryMinute>
      </schedule.SamSchedule>        
   </childConfigInfo>      
</generic.GenericObject.configureChildInstance>

<generic.GenericObject.configureChildInstance xmlns="xmlapi_1.0">
   <deployer>immediate</deployer>
   <distinguishedName>scheduleManager</distinguishedName>
   <childConfigInfo>      
      <schedule.OssTask>       
         <actionMask>        
            <bit>create</bit>
         </actionMask>       
         <id>10</id>
         <displayedName>FindToFile</displayedName>
         <commandName>FindToFile</commandName>
         <command>       
            <findToFile xmlns="xmlapi_1.0">           
               <fullClassName>netw.NetworkElement</fullClassName>
               <fileName>netw.xml</fileName>
            </findToFile>          
         </command>             
      </schedule.OssTask>       
   </childConfigInfo>
</generic.GenericObject.configureChildInstance>

<generic.GenericObject.configureChildInstance xmlns="xmlapi_1.0">
   <deployer>immediate</deployer>
   <distinguishedName>scheduleManager</distinguishedName>
   <childConfigInfo>  
      <schedule.SamScheduledTask>  
         <actionMask>  
            <bit>create</bit>
         </actionMask>  
         <id>15</id>
         <administrativeState>2</administrativeState>
         <displayedName>FindToFileTask-15</displayedName>
         <description>FindToFileTask15</description>
         <scheduledObjectPointer>scheduleManager:OssTask-111</scheduled
ObjectPointer>
         <schedulePointer>scheduleManager:samSchedule-10</
schedulePointer>
      </schedule.SamScheduledTask>
   </childConfigInfo>  
</generic.GenericObject.configureChildInstance> 

Result file format

A findToFile result file has the same XML format as the streamed result of a find request. The result filters specified in a request determine the specific objects that a request returns. See Request filters for information about result filters.

Local result file storage

The findToFile output location is an NFM-P main server directory below /opt/nsp/nfmp/server/xml_output. By default, a main server keeps findToFile output files for a retention period of 15 minutes. Every five minutes, the main server deletes each output file that is older than the retention period. Contact technical support if you require different findToFile retention settings.

The following figure shows an example of local findToFile output storage; the output file name is specified between the fileName tags.

Figure 13-6: findToFile example, local storage

<?xml version="1.0" encoding="UTF-8"?>

<SOAP:Envelope 

  xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">

   <SOAP:Header>

      <header xmlns="xmlapi_1.0">

         <security>

            <user>username</user>

            <password>password</password>

         </security>

         <requestID>XML_API_client@n</requestID>

      </header>

   </SOAP:Header>

   <SOAP:Body>

      <findToFile xmlns="xmlapi_1.0">

         <fullClassName>equipment.PhysicalPort</fullClassName>

         <filter>

            <and>

               <equal name="siteId" value="10.1.202.93"/>

               <equal name="shelfId" value="1"/>

               <equal name="cardSlotId" value="1"/>

               <equal name="daughterCardSlotId" value="1"/>

               <equal name="mode" value="access"/>

            </and>

         </filter>             

         <fileName>equipmentPhysicalPort.xml</fileName>

      </findToFile>

   </SOAP:Body>

</SOAP:Envelope>

Remote result file storage

You can configure the findToFile method to record the query results to a file on a remote station using FTP. The fileName parameter of the findToFile method allows you to configure the optional FTP credentials, host identifier, and file path. If the FTP credentials are not specified, the XML API uses the following:

• username—anonymous

• password—an e-mail address

The following figure is a remote storage configuration example for the findToFile method.

Figure 13-7: findToFile example, remote storage

<findToFile xmlns="xmlapi_1.0">

   <synchronous>false</synchronous>

   <fullClassName>class_name</fullClassName>

   <fileName>

    [s]ftp://user:password@host:port/directory/filename

   </fileName>

   <resultFilter>

.

.

.

   </resultFilter>

</findToFile>

To configure remote findToFile result storage describes how to configure the permissions for the findToFile FTP directory and FTP account on a remote server.