Inventory retrieval methods

Overview

The XML API provides the following methods to retrieve 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

Method and parameters

Parameter description

find

fullClassName

The package-qualified class name in dot-separated format

filter

(strongly recommended)

A filter that is based on the class properties

timeout (optional)

The time, in milliseconds, after which the NFM-P aborts the request and returns an exception

resultFilter

(strongly recommended)

A filter that reduces the amount of object information that is retrieved

continueOnFailure (optional)

Whether to continue processing requests in the stream if an exception other than a request parsing error occurs

findToFile

fullClassName here

The package-qualified class name in dot-separated format

fileName

The relative file in which to store the results. The format is:

ftp://user:password@host:port/directory/filename

or, if secure FTP is used:

sftp://user:password@host:port/directory/filename

The following rules apply:

  • When using a remote client, the directory must be relative to the default FTP directory on the remote client.

  • The characters ‘/’ and ‘;’ are reserved and must be encoded. For example, to specify a file in /tmp directory on the remote client, the path must be encoded as ftp://name@password/%2Ftmp/filename.xml. The path ftp://name@password/tmp/filename.xml specifies a file in a /tmp directory under the default FTP directory of the user.

See RFC 1738 Uniform Resource Locators (URL), Section 3.2.2 for more information about the FTP URL requirements.

timeStamp (optional)

Whether to include the timestamp in the name of the result file

compress (optional)

Whether to compress the result file using gzip compression; the default is False

timeout (optional)

The time, in milliseconds, after which the NFM-P aborts the request and returns an exception

filter

(strongly recommended)

A filter that is based on the class properties

resultFilter

(strongly recommended)

A filter that reduces the amount of object information that is retrieved

synchronous (optional)

Whether the method runs synchronously, in which case the result is returned only when the operation is complete; the default is true

continueOnFailure (optional)

Whether to continue processing requests in the stream if an exception other than a request parsing error occurs

findFaults

faultFilter

A filter that is based on the alarm properties

resultFilter

(optional)

A filter that reduces the amount of object information that is retrieved

continueOnFailure (optional)

Whether to continue processing requests in the stream if an exception other than a request parsing error occurs

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:

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:

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

Step

Request example

1. Create a schedule, or choose an existing schedule.

<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>

2. Create a findToFileTask, or refer to an existing task.

<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>

3. Create a samScheduledTask that points to a schedule, and a findToFile task.

<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> 

4. Turn up, shut down, start, or stop the samScheduledTask.

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:

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.