HTTP communication

Connections

HTTP connection limit

The XML API supports a limited number of concurrent HTTP connections. The exact limit depends on the available system resources. See the NSP Planning Guide for the platform requirements regarding the HTTP connection limit.

The OSS requests of a specific NFM-P user have a priority that is assigned during user or user group configuration. The prioritization may cause some lower-priority requests to time out in a high-volume environment. Nokia recommends that you design each OSS application to include a configurable request duration timeout in order to avoid request timeouts.

Nokia recommends that only one HTTP connection is used for XML SOAP requests from each OSS. If more than one HTTP connection is required, the number of concurrent HTTP connections must be configurable in the OSS application so that system integrators can manage the HTTP connections across multiple applications.

HTTP security

The NFM-P supports both secure and non-secure communication over HTTP. Nokia recommends that an OSS application support both protocols.

Sending SOAP requests

Inventory commands

The NFM-P can concurrently execute a maximum of five concurrent find and findToFile OSS requests. An OSS can potentially consume all available HTTP connections if the number of simultaneous inventory requests is not configurable. When an OSS must send simultaneous inventory requests, Nokia recommends that the number be configurable at run time.

Streaming SOAP XML commands

An efficient way to perform multiple XML API requests is to use SOAP streaming. This eliminates the overhead of establishing HTTP connections for every XML API request.

In SOAP streaming, the OSS client first opens a HTTP connection, encapsulates the XML API command into a SOAP envelope, and posts the request to the XML API. After the NFM-P server response is received by the OSS client and while keeping the connection open, the next request, encapsulated into a SOAP envelope, can be posted using the same HTTP connection. See Chapter 5, XML requests and Chapter 9, XML message structure for more information about HTTP connection and XML message structures.

Nokia recommends that an OSS client use SOAP streaming. An OSS client using SOAP streaming should implement a configurable idle timer to close the HTTP connection when not in use, to reduce the number of consumed HTTP connections.

Avoid configuration with children hierarchy

It is more difficult to troubleshoot a failure that follows an XML API request with multiple configuration operations in comparison to an XML API request with a single configuration operation. To execute corrective action, for example to reverse a partial configuration, it is important to first precisely identify which part of the configuration request failed.

Nokia recommends that each configuration request contain no more than one configuration operation. For example, to configure a service, each service object should be configured individually in its own XML API request, as opposed to configuring all service objects in a single, complex XML API request.

Avoid configuration with children hierarchy

Response processing

Depending on the network and the XML request, the size of the XML response may be quite large. Nokia recommends that OSS software process the XML response as it is streamed. This avoids the need to buffer the entire XML response and the OSS software is able to process the response without having to wait for the entire response to be generated.

Monitoring the NFM-P main server

Nokia recommends that you use JMS to monitor the NFM-P; see Chapter 4, Event monitoring using JMS for more information.

Nokia also recommends that you monitor the NFM-P HTTP and SOAP responses to ensure that the requests are correctly processed. The following table lists and describes the response error messages.

Table A-1: HTTP error messages

Error message	Recommended action
Connection refused	The NFM-P is not fully initialized; try again later.
HTTP code 405	The standby main server has received the request; redirect the request to the primary main server.
HTTP code 905	The maximum number of concurrent OSS sessions for one user is reached; try again later.
HTTP code 503	The HTTP connection limit is reached; try again later.

Failure handling

An OSS may or may not be designed to perform automatic rollback from failure. Nokia recommends that the OSS application should log the failure details for reference, which can be used later for manual troubleshooting and error recovery. Failed deployments must be cleared because uncleared deployments consume resources on the NFM-P server. The total number of deployments on the NFM-P server is finite. If all of the deployments are being consumed on the NFM-P server, any future network configurations are blocked.

Nokia recommends the following deployment-handling strategy:

Do not change the default value (false) of the <clearOnDeployFailure> parameter. The OSS should retrieve the failure details from the deployment (use the generic.GenericObject.getDeployer(s) method), then immediately delete the deployment (use the generic.GenericObject.clearDeployer method).
Do not change the default value (0) of the <deployRetries> and <deployRetryInterval> parameters.

See Deployments for more information about deployments and deployment failure handling procedures.

Inventory retrieval

When obtaining a full inventory from the NFM-P, all objects of a specified class should be retrieved in a single request. Requests should not be hierarchical. For example, children objects should be retrieved in separate requests from the parent. Filters and result filters can be used to achieve these goals.

Filters

When only a subset of a particular object class is required, filters can be used to limit the objects being returned. Filters should only specify attributes that are part of the object being requested. Filters that depend on attributes of children classes should be avoided.

Result filters

Result filters should be used to limit the attributes that are returned. Only those attributes that are of interest to the OSS should be included in the filter. To uniquely identify objects at a later time, the fully distinguished name (<objectFullName>), which is guaranteed unique, should be used.

find and findToFile methods

The find and findToFile methods can be used to retrieve an inventory of general objects. Table A-2, find and findToFile comparison lists the advantages and disadvantages of each method.

Note: Nokia does not recommend making find or findToFile requests on a large scale network, compared to a smaller scope, because requests could take longer for larger data sets. Frequent large find or findToFile operations require more system resource so these requests may need to be timed for appropriate daily windows. If an application needs updates more frequently, event notification can be used by applications without extracting full inventory.

Note: Alarm retrieval requires the findFaults method.

Table A-2: find and findToFile comparison

Method	Advantages	Disadvantages
find	Easy to send requests and parse results using HTTP Results can be parsed as they become available	Subject to failure due to network conditions (latency, dropped packets)
findToFile	Can resume file transfer after network interruptions Does not require HTTP connection to remain open (requires asynchronous requests used in conjunction with JMS notifications)	Requires waiting for entire response before results can be parsed

Method

Advantages

Disadvantages

find

Easy to send requests and parse results using HTTP
Results can be parsed as they become available

Subject to failure due to network conditions (latency, dropped packets)

findToFile

Can resume file transfer after network interruptions
Does not require HTTP connection to remain open (requires asynchronous requests used in conjunction with JMS notifications)

Requires waiting for entire response before results can be parsed

Use subject to agreed restrictions on disclosure and use.