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
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:
| |
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: See Faults and exceptions for more information about the fault details. |
Notes:
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:
-
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
Special character |
Entity reference |
---|---|
< |
< |
> |
> |
& |
& |
‘ |
' |
“ |
" |
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:
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 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:
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
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:
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:
-
<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 <faultstring> 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 |
|
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 |
| |
XMLException |
| |
IMException |
| |
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:
-
<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:
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.