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:

Message structure

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

Figure 9-1: SOAP message types
SOAP message types

The following table describes the SOAP message types.

Table 9-1: SOAP message type details

SOAP message type

Contents

Details

Request

SOAP envelope

Contains all message data

SOAP header

The header contains:

  • user security details:

    • user IDs in plain-text format

    • passwords in plain text 1 or an MD5-hashed format. A utility to convert plain text passwords to an MD5-hashed format is available. See Secure communication for information.

  • sequence information in the form of a requestID to associate requests with responses and faults. You can use a string for the requestID. The requestID must be unique per HTTP request.

    Do not use the following formats:

    • packageName-packageName.ObjectName-[instanceFullNameIfApplicable].methodName.

      For example:

      netw-netw.Topology-[].configure

    • AreqObjectNameMethodName-CLIENT-userId-sequenceNumber

      For example:

      AreqVirtualInterfaceConfigureIpAddresses-CLIENT-admin-2

    • SreqObjectNameMethodName-CLIENT-userId-sequenceNumber

      For example:

      SreqTopologyConfigure-CLIENT-operator-12

SOAP body

Contains the XML request in the general format:

<package.object.method> or <internal_method>

<inParam1>value</inParam1> 1

<inParamX>value</inParamX> 1

</package.object.method> or </internal_method>

Response

SOAP envelope

Contains all message data

SOAP header

Contains sequence information in the form of the request ID of the original request

SOAP body

Contains the XML response in the general format:

<package.object.methodResponse> or

<package.object.methodException> or

<XMLException> or

<IMException>

<outParam1>value</outParam1>

<outParamX>value</outParamX>

Fault

SOAP envelope

Contains all message data

SOAP header

Contains sequence information in the form of the request ID of the original request

SOAP fault

Contains:

  • SOAP fault information

  • exception details

See Faults and exceptions for more information about the fault 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:

There are three scenarios for a message request:

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
Database interaction with synchronous network deployment
Figure 9-3: Database interaction with asynchronous network deployment
Database interaction with asynchronous network deployment
Figure 9-4: Database interaction without network deployment
Database interaction without network deployment
Figure 9-5: Read from database interaction
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 &lt; and &amp; are illegal in the XML language, but it is good practice to replace all other characters.

Table 9-2: Entity references for special characters

Special character

Entity reference

<

&lt;

>

&gt;

&

&amp;

&apos;

&quot;

Request example
CAUTION 

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:

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:

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:

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:

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

Code Range

Definition

1xx 1

Informational - Request received, continuing process.

2xx

Success - The action was successfully received, understood, and accepted.

3xx 1

Redirection - Further action must be taken in order to complete the request.

4xx

Client Error - The request contains bad syntax or cannot be fulfilled.

5xx

Server Error - The server failed to fulfill an apparently valid request.

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:

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

[error_string]

Details

license

Not licensed to use the XML API

soap

Incomplete or incorrect SOAP construction

xml-header

XML API header is missing, or is missing necessary information, such as the user ID or the MD5-hashed password

security

Authentication error, for example, invalid user ID

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

Fault or exception

Format

Description

SOAPFault

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

Errors in a SOAP header.

The <faultstring> in a <SOAP:Fault> response provides details on the fault.

The strings may change over different releases of the NFM-P and therefore it is recommended they not be parsed by the OSS application.

XMLException

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

Errors in the XML syntax or because of a non-existent method or attribute in the XML API.

The XMLException <description> field provides details on the XML errors.

The strings may change over different releases of the NFM-P and therefore it is recommended they not be parsed by the OSS application.

IMException

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

Errors in the object model. For example, binding a SAP to a non-existent tunnel.

The <description> field provides details about the error.

The strings may change over different releases of the NFM-P and therefore it is recommended they not be parsed by the OSS application.

BaseException

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

Operation-related exceptions, such as configurationException and creationException. The BaseException appears in the XML response in these exceptions.

The <description> field in the XML response provides details about the error.

The strings may change over different releases of the NFM-P and therefore it is recommended they not be parsed by the OSS application.

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

Fault or exception

Example fault or exception

SOAPFault

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

XMLException

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

IMException

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

BaseException

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

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 

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:

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:

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.

© 2023 Nokia. Nokia Confidential Information

Use subject to agreed restrictions on disclosure and use.