XML message structure

Overview

The XML API uses request, response, and fault messages to handle the XML message data related to network objects. Messages are sent to the XML API using an RPC pattern. The messages are constructed and wrapped in a SOAP envelope. The XML API then returns a success response message or a failure fault message.

The SOAP encoding transports the XML data. Three types of SOAP messages are used:

• requests

• responses for a successful or unsuccessful execution

• faults for SOAP messages that are not well-formed

Message structure

The following figure shows the structure of the three SOAP message types.

Figure 9-1: SOAP message types

The following table describes the SOAP message types.

Table 9-1: SOAP message type details

Notes:

1. For XML string values, there are five special characters that should not be used in plain text. Instead, it is recommended they be replaced with their entity references. See Table 9-2, Entity references for special characters for more information.

Requests

The XML API supports the following request types:

• synchronous

• asynchronous (default)

There are three scenarios for a message request:

• The OSS requests a database interaction that causes network deployments, for example, provisioning a service. See Figure 9-2, Database interaction with synchronous network deployment and Figure 9-3, Database interaction with asynchronous network deployment .

• The OSS requests a database interaction that does not cause network deployments. See Figure 9-4, Database interaction without network deployment .

• The OSS requests read information, for example, inventory information or an alarm feed. See Figure 9-5, Read from database interaction .

Note: The NFM-P maps the object FDNs to a corresponding database index. Nokia recommends using FDN properties in queries to maximize the processing speed of the query. It is recommended that XML API queries also use concrete classes rather than an abstract class to optimize performance.

Figure 9-2: Database interaction with synchronous network deployment

Figure 9-3: Database interaction with asynchronous network deployment

Figure 9-4: Database interaction without network deployment

Figure 9-5: Read from database interaction

Network interactions are performed using deployments. When a request fails before being committed to the database, a fault message is sent to the OSS client. For a synchronous request, the XML response indicates the success or failure of deployments. A single request may result in multiple deployments. The success or failure of multiple deployments is returned. OSS clients must be designed to accept more than one deployment in a response.

See Faults and exceptions   in this section for more information about deployment failure recovery. See Deployments for more information about deployment failure JMS alarms and deployment request configurations.

Special characters

There are five special characters used in the XML language that should not be used in plain text. Instead, it is recommended they be replaced with their entity references. The following table lists the special characters and their entity references. The characters < and & are illegal in the XML language, but it is good practice to replace all other characters.

Table 9-2: Entity references for special characters

Request example

CAUTION Service Disruption

The request examples are provided to show the request format only, and are intended for use as a template for your requests.

Ensure that you test each request that you create before you deploy the request in a live network.

The XML/SOAP request examples in this guide are intended as a base on which to build your own requests. The sample requests may contain:

• Methods that are deprecated by the XML API

• Configuration information that is not applicable to your network architecture

The request example in the following figure changes the configuration of port 1/1/3 on NE 10.1.202.93 to be access, dot1q, and administratively up.

Figure 9-6: XML request example

<?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 hashed="false">password</password>

         </security>

         <requestID>XML_API_client@n</requestID>

      </header>

   </SOAP:Header>

   <SOAP:Body>

      <generic.GenericObject.configureInstanceWithResult xmlns="xmlapi_1.0">

         <deployer>immediate</deployer>

         <distinguishedName>network:10.1.202.93:shelf-1:cardSlot-2:card:daughterCardSlot-1:daughterCard:port-3</distinguishedName>

         <includeChildren>true</includeChildren>

         <configInfo>

            <equipment.PhysicalPort>

               <actionMask>

                  <bit>modify</bit>

               </actionMask>

               <administrativeState>portInService</administrativeState>

               <mode>access</mode>

               <encapType>qEncap</encapType>

               <children-Set/>

            </equipment.PhysicalPort>

         </configInfo>

      </generic.GenericObject.configureInstanceWithResult>

   </SOAP:Body>

</SOAP:Envelope>

The request includes the following:

• generic.GenericObject.configureInstanceWithResult, which identifies:

  • the use of the generic package

  • the configureInstanceWithResult method defined in the GenericObject class

• the standards-based schema and version identifiers

• the distinguishedName tag, which contains the FDN of the NFM-P object

• the configInfo object, which can contain one or more objects

The configureInstanceWithResult method, as indicated in the request, is defined in the genericMethods.xsd. The equipmentTypes.xsd schema file defines the valid parameters available for configuration on equipment.PhysicalPort. The request is executed by the server according to the parameters specified in the configureInstanceWithResult method.

Note: The actionMask object is of type bitmask.

A bitmask is a small set of Booleans. Each bit is by default false and needs to be explicitly enabled in a single operation. Specifying only a single bit will result in the remaining bits being reset to false even if they were previously enabled.

XML request grouping

You can concatenate multiple message requests in the body of a single SOAP message. The response contains the result of each request.

The following figure shows an example of a SOAP message with multiple message requests.

Figure 9-7: Example of multiple requests in one SOAP message

<?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 hashed="false">password</password>

         </security>

         <requestID>XML_API_client@n</requestID>

      </header>

   </SOAP:Header>

   <SOAP:Body>

      <find xmlns="xmlapi_1.0">

         <fullClassName>equipment.DaughterCard</fullClassName>

         <filter>

            <equal name="siteName" value="sim202_93"/>

         </filter>

         <resultFilter>

            <attribute>objectFullName</attribute>

            <attribute>operationalState</attribute>

            <attribute>administrativeState</attribute>

            <attribute>specificType</attribute>

            <children/>

         </resultFilter>

      </find>

      <find xmlns="xmlapi_1.0">

         <fullClassName>equipment.PhysicalPort</fullClassName>

         <filter>

            <equal name="siteName" value="sim202_93"/>

         </filter>

         <resultFilter>

            <attribute>objectFullName</attribute>

            <attribute>operationalState</attribute>

            <attribute>administrativeState</attribute>

            <attribute>mode</attribute>

            <children/>

         </resultFilter>

      </find>

   </SOAP:Body>

</SOAP:Envelope>

Password format

The NFM-P server accepts XML requests with plaintext or MD5-hashed passwords. See Secure communication for more information.

Action on failure

The <continueOnFailure> and <onFailure> options help manage failed requests.

<continueOnFailure>false</continueOnFailure>

When the <continueOnFailure> option is set to false and a request in a concatenated message fails, the NFM-P:

• ignores the remaining requests in the concatenated message

• returns responses for successful requests up to the failed request

• generates an exception message for the failure

When the <continueOnFailure> option is set to true, the execution of the requests continues even if a failure occurs. Responses and exceptions are returned for each success or failure.

Note: Execution does not continue if there is a parsing error in the XML request. For example, incorrectly formatted XML or specifying a className or attribute that does not exist results in a parsing error.

The <execute> and <onFailure> options allow requests to recover from a failure. Multiple message requests can be placed within <execute> and <onFailure> blocks. The execution starts with the first request in the <execute> block. If there is a failure, the execution branches to the start of the <onFailure> block. The results are for the requests up to the failed request in the <execute> block, and the requests up to the failed request, if any, in the <onFailure> block. Only one level of nesting is allowed in an <onFailure> block.

Each <execute> block can have a timeout parameter, as shown in Figure 9-9, VPLS site creation request example :

Figure 9-8: execute and onFailure options

<execute timeout="500000" xmlns="xmlapi_1.0">

.

.

</execute>

<onFailure>

.

.

</onFailure>

Elapsed time is verified between requests in the <execute> block. If the timeout is exceeded, the execution is terminated and a request timed out failure is returned in the result.

The following figure shows a request to create a VPLS site.

Figure 9-9: VPLS site creation request example

<?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 hashed="false">password</password>

         </security>

         <requestID>XML_API_client@n</requestID>

      </header>

   </SOAP:Header>

   <SOAP:Body>

      <generic.GenericObject.configureChildInstance xmlns="xmlapi_1.0">

         <distinguishedName>svc-mgr:service-67</distinguishedName>

         <childConfigInfo>

            <vpls.Site>

               <actionMask>

                  <bit>create</bit>

                  <bit>modify</bit>

               </actionMask>

               <siteId>10.1.241.69</siteId>

               <displayedName>Customer_12:VPLS:100020:site_14</displayedName>

               <administrativeState>1</administrativeState>

               <mtu>0</mtu>

            </vpls.Site>

         </childConfigInfo>

      </generic.GenericObject.configureChildInstance>

   </SOAP:Body>

</SOAP:Envelope>

The following figure shows a deletion request that can be used after a failure occurs when creating the VPLS site.

Figure 9-10: VPLS site deletion request example

<?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 hashed="false">password</password>

         </security>

         <requestID>XML_API_client@n</requestID>

      </header>

   </SOAP:Header>

   <SOAP:Body>

      <generic.GenericObject.deleteInstance xmlns="xmlapi_1.0"> 

         <distinguishedName>svc-mgr:service-67:10.1.241.69

         </distinguishedName>

      </generic.GenericObject.deleteInstance>

   </SOAP:Body>

</SOAP:Envelope>

You can combine both requests in Figure 9-9, VPLS site creation request example and Figure 9-10, VPLS site deletion request example with the execute and onFailure blocks, as shown in the following figure.

Figure 9-11: Request example with execute and onFailure elements

<?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 hashed="false">password</password>

         </security>

         <requestID>XML_API_client@n</requestID>

      </header>

   </SOAP:Header>

   <SOAP:Body>

      <execute>

         <generic.GenericObject.configureChildInstance xmlns="xmlapi_1.0">

            <distinguishedName>svc-mgr:service-67</distinguishedName>

            <childConfigInfo>

               <vpls.Site>

                  <actionMask>

                     <bit>create</bit>

                     <bit>modify</bit>

                  </actionMask>

                  <siteId>10.1.241.69</siteId>

                  <displayedName>Customer_12:VPLS:100020:site_14</displayedName>

                  <administrativeState>1</administrativeState>

                  <mtu>0</mtu>

               </vpls.Site>

            </childConfigInfo>

         </generic.GenericObject.configureChildInstance>

      </execute>

      <onFailure>

         <generic.GenericObject.deleteInstance xmlns="xmlapi_1.0">

            <distinguishedName>svc-mgr:service-67:10.1.241.69</distinguishedName>

         </generic.GenericObject.deleteInstance>

      </onFailure>

   </SOAP:Body>

</SOAP:Envelope>

Responses

Responses identify the execution of a method.

The following figure shows a successful response to the request to configure a network interface.

Figure 9-12: Request success response example

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

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

   <SOAP:Header>

      <header xmlns="xmlapi_1.0">

         <requestID>XML_API_client@n</requestID>

      </header xmlns="xmlapi_1.0">

   </SOAP:Header>

   <SOAP:Body>

      <rtr.RoutingInstanceSite.configureResponse xmlns="xmlapi_1.0">

         <objectFullName>network:10.1.202.95:router-1:ip-interface-24</objectFullName>

      </rtr.RoutingInstanceSite.configureResponse>

   </SOAP:Body>

</SOAP:Envelope>

You can also include the content type information in the HTTP response header, using the <xmlapi> element in the main server configuration. The xmlContentType parameter defines the content; for example, using the default value of text/xml; charset=ISO-8859-1. You can use any valid string to configure the parameter.

The customProperty fields that can be configured for the network element object, support UTF-8 with the following limitations:

• 4-byte UTF-8 characters are supported for customProperty fields in HTTP requests via the XML API and also supported in the NFM-P, however, 4-byte UTF-8 characters are not displayed in HTTP responses.

• Certain 4-byte characters are in the supplementary range of the UTF-8 character set and are handled differently. Specifically, any characters above the 0x0FFFF mark are represented as pairs of two 2-byte characters which are not able to be inserted into XML without using escape characters and code point values. These supplementary 4-byte characters are not supported in requests or responses.

HTTP response codes

The following table defines the HTTP response codes based on the RFC 2616 standard. The XML API does not use all responses defined by the RFC 2616 standard. The HTTP response codes are associated with the successful or unsuccessful transmission of the XML response.

Table 9-3: HTTP response codes

Notes:

1. The XML API does not send 1xx and 3xx messages.

The XML API client must check the HTTP response code before it attempts to parse the XML API results. An HTTP response code between 200 and 299 identifies successful execution of the request. The HTTP body for a 2xx response contains a valid XML SOAP response. All other response codes may not contain well-formed XML.

Faults and exceptions

The XML API produces a SOAP fault message when there is a problem processing a SOAP header or empty SOAP body. The subsequent errors result in an exception within the SOAP body.

SOAP exception messages can contain the following fault-related details:

• <faultcode> provides some standard SOAP information, including:

  • version mismatch between SOAP versions

  • server problems

  • client problems, for example, sending a request to execute a method that does not exist on the server

• <faultstring> error message

• <faultactor> is the URL of the server if the server is the problem

The XML API uses the following format for the <faultstring> element:

<faultstring>[error_string] message</faultstring>

The following table lists the error types that are associated with the &lt;faultstring&gt; element.

Table 9-4: <faultstring> error types for SOAP fault messages

The following table describes the faults and exceptions that can appear in an XML response.

Table 9-5: Summary of XML response faults and exceptions

<SOAP:Fault>
   <faultcode>value</faultcode>
   <faultstring>value</faultstring>
   <faultactor>value</faultactor><detail>
   <requestID>value</requestID></detail>
</SOAP:Fault>

<XMLException xmlns="xmlapi_1.0">
   <description>value</description>
   <line>value</line>
   <column>value</column>
</XMLException>

<IMException>
   <cause>value</cause>
   <description>value</description>
</IMException

<BaseException xmlns="xmlapi_1.0">
   <description>value</description>
</BaseException>

Table 9-6, Sample faults and exceptions lists sample faults and exceptions that can appear in an XML response, as described in Table 9-5, Summary of XML response faults and exceptions .

Note: The code examples in Table 9-6, Sample faults and exceptions do not contain the SOAP envelope or header information.

Table 9-6: Sample faults and exceptions

<SOAP:Fault>
   <faultcode>SOAP:Client</faultcode>
   <faultstring>[security] Users require OSS Management privileges to use XML API</faultstring>
   <faultactor>XmlApi</faultactor>
      <detail>
         <requestID>XML_API_client@n</requestID>
      </detail>
</SOAP:Fault>

<SOAP:Body>
   <XMLException xmlns="xmlapi_1.0">
      <description>Command 'fm.FaultManager.findFault2s' is not defined</description>
      <line>4</line>
      <column>57</column>
   </XMLException>
</SOAP:Body>

<SOAP:Body>
   <IMException xmlns="xmlapi_1.0">
      <cause>java.lang.SecurityException</cause>
      <description>SecurityManager:Security Breach: No such user: 'oss_client'</description>
   </IMException>
</SOAP:Body>

<SOAP:Body>
   <script.ScriptManager.configureException xmlns="xmlapi_1.0">
      <description>[app: script] [class: script.Script] [instance: -unknown-] [descr: the NE type is invalid type,{neType=craig}] </description>
   </script.ScriptManager.configureException>
</SOAP:Body>

Figure 9-13, Exception message example, configuration failure shows an exception message generated when a user does not have the required OSS management privileges to use XML API. The sample exception provides the following details:

• <faultcode> element indicates that the server could not execute the request because of a fault of the client

• <faultstring> element provides the security error string, which indicates that the Client user specified does not have the required OSS management privileges to use XML API

• <faultactor> element identifies the XmlApi as the fault factor

Figure 9-13: Exception message example, configuration failure

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

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

   <SOAP:Header>

      <header xmlns="xmlapi_1.0">

         <requestID>XML_API_client@n</requestID>

         <requestTime>Jan 2, 2007 1:18:53 PM</requestTime>

         <responseTime>Jan 2, 2007 1:18:53 PM</responseTime>

      </header>

   </SOAP:Header>

   <SOAP:Fault>

      <faultcode>SOAP:Client</faultcode>

      <faultstring>[security] Users require OSS Management privileges to use XML API</faultstring>

      <faultactor>XmlApi</faultactor>

      <detail>

         <requestID>XML_API_client@n</requestID>

      </detail>

   </SOAP:Fault>

</SOAP:Envelope>

Note: The <responseTime> tag in an XML API header is the time at which the response stream is opened.

The <detail> element in the SOAP exception message identifies the command that caused the request failure.

The XML API validates the XML request when it is sent to the server. If the validation fails, an exception message is generated and sent, as shown in Figure 9-13, Exception message example, configuration failure . If the request requires changes to the managed network, deployments are created and queued to send the changes to the routers. If the deployment fails, an alarm is raised which includes details for the particular deployment ID. The network can be in an indeterminate state because another configuration request may have succeeded. See Deployments for more information about creating and viewing deployment requests and alarms.

To recover from request errors, the OSS application may need to check the affected objects in the deployment and issue appropriate requests to undo the action that caused the error. Another option is to manually maintain a list of failures for resolution at a later date.

Note: See Workflow to handle deployment failures in Chapter 15, Configuration management overview for more information about how to handle deployment errors that may cause the NFM-P database to be out of synchronization with the managed network.

Logged exception messages

The EmsServer log files on an NFM-P main server contain additional exception message information. You can view the file contents using a text editor or the LogViewer application. See the NSP Troubleshooting Guide for information about using LogViewer. See Mapping XML methods to GUI operations for information about enabling debug logging and viewing EmsServer log files.

Logging XML requests, responses, and exceptions

CAUTION Service Disruption

The prolonged use of XML message logging in a busy network environment may have network management performance impacts.

Use the log functions for a limited time to debug a specific problem.

You can enable the logging of XML API request, response, and exception messages on an NFM-P main server. The entries in the message logs can assist you with the following:

• identifying the user associated with an XML request

• debugging the OSS requests from a user

You can enable XML message logging for an individual user or multiple users. See Identifying XML messages from specific users for more information. The NFM-P creates log files for each HTTP request and response associated with the user defined by the <systemOssiLog> element in the NFM-P main server configuration. An HTTP request and response can contain multiple XML requests and responses.

The NFM-P stores the log file in the directory defined by the <systemOssiLog> element in the main server configuration, typically .../log/. The NFM-P uses the following naming convention for log files:

• ossiuserRequestn.log

• ossiuserResponsen.log

where

user is the NFM-P user name

n is the incremental request number

The request log contains the body of the SOAP message. The response log contains the entire SOAP envelope of the response.

The following figure shows a sample request for an XML message log file.

Figure 9-14: Request example, ossiuserRequest1.log file

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

<Request user="username" requestId="XML_API_client@n">

   <find>

      <fullClassName>...</fullClassName>

      <filter>

.

.

.

      </filter>

   </find>

</Request>

The following figure shows an example of a response to an XML message log file request.

Figure 9-15: Response example, ossiuserResponse1.log file

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

<Response user="user" requestId="XML_API_client@n">

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

      <SOAP:Header>

         <header xmlns="xmlapi_1.0">

            <requestID>XML_API_client@n</requestID>

            <requestTime>Jan 2, 2007 3:10:41 PM</requestTime>

            <responseTime>Jan 2, 2007 3:10:41 PM</responseTime>

         </header>

      </SOAP:Header>

      <SOAP:Body>

         <findResponse xmlns="xmlapi_1.0">

            <result>    

.

.

.

            </result>

         </findResponse>

      </SOAP:Body>

   </SOAP:Envelope>

</Response>

Note: The <responseTime> tag in the header is the time at which the response stream is opened.

The XML message logging parameters are defined in the NFM-P main server configuration. The system administrator is responsible for the maintenance and backup of log files.

To modify the main server configuration, contact Nokia technical support.

As part of debug logging policy configuration, the system administrator can configure the maximum disk space for storing log messages. The NFM-P disables the log option and raises an alarm if the size of the log file exceeds the storage allocation. The default log file retention period is 24 hours. See Identifying XML messages from specific users for information about how to modify the log file retention period.

In a redundant system, the NFM-P logs the activities for the primary main server.

See Identifying XML messages from specific users for information about how to enable the logging of NFM-P XML message transactions.

The User Activity form in the NFM-P client GUI displays user activity. See the section on user activity logging in the NSP System Administrator Guide for more information.