Retrieving results

Overview

Test result objects are subclasses of sas.TestResult (abstract). The concrete classes are defined in the package for the tested object. For example, the results of a VCCV ping are a svt.VccvPingResult.

The following describes the ways for an OSS to access test results:

Run a test and get the rest result as a response.
Retrieve results of past tests (for example, for a particular time period).
Register to get notification of scheduled test results as they become available. This is the preferred method. See Performance and scalability for more information.

Run a test and get a response

An OSS can run an existing test (using sas.Test.executeAndWait) or create and run a test (using sas.Test.adhocExecuteAndWait). Both of these methods return the test result in their response. See the XML API Reference for detailed descriptions of these methods. See CreateAndUse.xml in the code samples. See the XML API SDK Sample Code Navigator for sample XML code.

Retrieve results of past tests

An OSS can use findToFile to retrieve results of tests that have already run. A common implementation would be to retrieve tests of a particular type for a specific time interval. See findToFile method in Chapter 13, Inventory management for more information. An OSS which employs this option must keep in mind the lifetime of test result storage in the database. See Performance and scalability for more information.

Register for notification of test results

XML API clients can use the registerSasLogToFile method to retrieve OAM test result export files for specific test class results. A LogFileAvailableEvent is sent each time a file is available for retrieval; a client must subscribe to JMS to receive the events. By default, if the client is not subscribed, no result files are created, and the NFM-P deregisters the client after a period of client inactivity. A JMS subscription for registerSasLogToFile is optional, however; you can disable the JMS client inactivity check to ensure that no deregistration occurs. See To configure the registerLogToFile or registerSasLogToFile client inactivity check for information.

OAM data is exported to a result file after the data is read from the NE. The file is saved to a specified directory on the NFM-P server.

Note: Not all OAM tests provide OAM data when the registerSasLogToFile method is used. The following conditions are required for OAM data to be generated for registerSasLogToFile:

OAM test sas.Test.neSchedulable attribute is true
OAM test sas.Test.accountingPolicyObjectPointer attribute is not empty
OAM test sas.Test.accountingFiles attribute is true
OAM test sas.Test.testResultStorage attribute value is logToFile or logToDBAndFile

See “OAM diagnostic tests” in the NSP NFM-P Classic Management User Guide for configuration information.

The NFM-P server verifies the presence of the JMS client subscription that is specified in the registerSasLogtoFile method using the jmsClientId input parameter. If the client is not subscribed, the server deregisters the registerSasLogToFile request. This means that OAM result export files are not generated after the Log Retention Time expires.

It is recommended that you run the registerSasLogToFile method every time the client establishes a JMS session.

The following table describes the input parameters of the registerSasLogToFile method.

Table 12-1: registerSasLogToFile method input parameters

Input parameter	Description	Values
fullClassName	A comma-separated list of package qualified class names to register. Superclasses may be specified. If a class in the list is not an instance of sas.TestResult or sas.TraceHop, an exception occurs, none of the classes are registered, and request processing terminates unless continueOnFailure is true. (String)	Comma-separated list of OAM results
dirName	The relative path of the directory in which to save the files; the path is relative to the oam directory below the OSS XML export directory. The parameter is mandatory. A best practice is to use a separate directory for each application that exports different test results or uses different filters.	String
compress	Specifies whether export files are to be compressed when they are created. A value of True saves files with gzip compression and a filename extension of gz. The default is False. (Optional) Specifying a compression option increases the CPU processing load.	False (default) True
jmsClientId	The JMS client ID or Kafka Subscription ID that is notified when a new export file is created based on the specified parameters; a notification is sent to each client that is registered for OAM logs when an export file is created. If the JMS client inactivity check is disabled, an empty string must be specified.	See Chapter 4, Event monitoring using JMS for information about the JMS client ID format.
filter	Filter on the text attribute(s) of the log record that will be written to the stats file, or accountingPolicyId integer attribute (applies only to accounting statistics). (Optional) The following filter tags are supported: and equal in not notEqual or wildcard	<filter>element</filter>
resultFilter	The attribute set to include in the OAM result export file, where the attributes are part of the specific test result object; you can also use the parameter to reduce the size of the result file by reducing the number of attributes included per test result object. (Optional)	<attribute>attribute_name</attribute>
continueOnFailure	Optional parameter that specifies whether to continue processing requests in the stream if an exception occurs, except in the case of a request parsing error; the default is false. (Boolean) (Optional)	False (default) True

The OAM result files are created using unique names in a directory relative to /opt/nsp/nfmp/server/xml_output/oam.

OAM result file retrieval using the registerSasLogToFile method requires a RHEL user account on each main server. Such a user account requires FTP or SFTP access, depending on whether TLS is enabled on the XML API. See Configuring FTP and SFTP access for OSS clients for the specific requirements and best practices for creating OSS client user accounts.

See the XML API SDK Sample Code Navigator, OAM directory, for registerSasLogToFile request, jms logFileAvailableEvent, and OAM result export file samples.

The following figure shows an OAM log file request using the registerSasLogToFile method.

Figure 12-1: OAM log file request example

<registerSasLogToFile xmlns="xmlapi_1.0">

   <fullClassName>sas.TestResult, sas.TraceHop</fullClassName>

   <dirName>jmsclientdir</dirName>

   <jmsClientId>JMS_client@n</jmsClientId>

   <resultFilter>

      <attribute>testSuiteId</attribute>

      <attribute>testId</attribute>

      <attribute>fromNodeId</attribute>

      <attribute>neTestRunIndex</attribute>

      <attribute>resultStatus</attribute>

   </resultFilter>

</registerSasLogToFile>

The configuration of testResultStorage is different for OAM PM Diagnostics test results. The OAM PM diagnostic tests results are modeled from sas.PmStats. You can retrieve the results of the following classes of OAM PM diagnostic test sessions from LogToDB, LogTofFile or both.

ethernetoam.CfmDmmSession
ethernetoam.CfmLmmSession
ethernetoam.CfmSlmSession
sas. MplsDmSession
sas. TWLSession

To store the test results in the database, you can specify the writeAccountingResultsToDb attribute per session test or globally as System Preferences. See the Assurance section of the User Guide for more details.

registerSasLogToFile filtering

To reduce the volume of exported statistics data, a client can apply a filter during registerSasLogToFile registration. The filter criteria determine which records are returned to a client; for example, if multiple API clients are individually responsible for statistics collection in specific subnet; each client can apply a filter to return only the statistics associated with the NEs in specific subnets.

You can filter on any properties of a statistics log record that are string-based, such as monitoredObjectClass or monitoredObjectSiteId. See the LogRecord class definition in the XML API Reference for a list of the class properties.

For accounting statistics, you can configure an NFM-P system preference to include the accounting policy ID in each accounting statistics record. This enables an OSS client to use registerSasLogToFile and JMS filters based on the accounting policy ID.

See the system preferences configuration procedures in the NSP System Administrator Guide for more information.

See the registerSasLogToFile method description in the XML API Reference for a list of the supported filter elements and syntax.

See JMS message filtering for information about creating JMS filters.

Use subject to agreed restrictions on disclosure and use.