Contents

1   Introduction

1.1   Document Purpose and Scope

This document is a description of the SOAP interface offered by the SAPC to other network elements (such as an external database) to receive notifications about data changes.

This document only applies when the SAPC subscriber data is stored in an external database.

1.2   Revision Information

1.3   Concepts

2   Overview

External database notifies the SAPC about changes of the SAPC subscriber-related data held in the external database by using the SOAP notification interface provided by the SAPC.

The notification interface offered by the SAPC is based on Simple Object Access Protocol (SOAP), Reference [1].

The transport protocol used to carry the SOAP notification messages is the Hypertext Transfer Protocol (HTTP), Reference [2].

3   SOAP Protocol

SOAP is a communication protocol between applications that provides a simple and lightweight mechanism for exchanging structured and typed information in a decentralized and distributed environment based on XML.

3.1   SOAP Message Structure

A SOAP message is an XML document that consists of an optional SOAP header and a mandatory SOAP body, within an overall mandatory SOAP envelope.

• SOAP Envelope: Root element of the message. It identifies the XML document as a SOAP message.
• SOAP Header: Mechanism used to add features to a SOAP message in a decentralized manner without prior agreement between the communicating parties.
• SOAP Body: It is a container for mandatory information intended for the ultimate recipient of the message. Inside the SOAP Body, a SOAP Fault element can be included to carry error and status information.

4   Notification WSDL Data Structures

This section describes the XML data structures used.

Note:  

XML elements and attributes are case-sensitive.

4.1   Envelope XML Elements

There is no specific information to be included in the SOAP Envelope but the specified in Reference [1].

4.2   Header XML Elements

No specific treatment of the SOAP Header element is defined for notifications towards the SAPC. If received, the SAPC shall behave as specified in Reference [1].

4.3   Body XML Elements

4.3.1   Notification Request Messages

The root of the SOAP Body for Notification Request messages is a notify XML element, composed of the following XML elements:

• notificationEvent
• additionalInformation
• modificationInformation

Note:  

There is also an Extension XML element for future purposes, but the SAPC does not use it. It is ignored if received.

Next figure shows the main information elements:

4.3.1.1   notificationEvent

It is an XML string that indicates the purpose of the notification. It is mandatory in SOAP notifications towards the SAPC.

The SAPC supports the following values:

• provisioningEvent to indicate that the SOAP notification is triggered by a provisioning event

4.3.1.2   additionalInformation

It is a structure providing relevant information for the handling of the notification. It is optional and can be used to convey for example identifiers and location information of the subscriber or users subject of the notification event. There may be multiple instances of this XML element present in the notification request with the restriction that all the instances refer to the same subscriber.

It is composed of series of ldapAttribute XML elements and the XML attributes shown in the following table:

4.3.1.2.1   ldapAttribute

It is a structure representing an LDAP attribute related to the subscriber or users subject of the notification event.

The following table contains the XML attributes that can be set in it:

ldapAttribute is composed of a series of ldapAttributeValue XML elements.

ldapAttributeValue

XML string containing the value of the attribute. For multivalued LDAP attributes, there can be a series of ldapAttributeValue.

4.3.1.3   modificationInformation

It is a structure representing the LDAP object instance whose modification triggered the notification event.

It is mandatory for ProvisioningEvent notifications.

If the SAPC receives multiple instances of this element, the SAPC processes them in the received order. If the processing of all them works fine, the SAPC returns success. In case one of them results in a failure, the SAPC returns an error (Section 6), and the SAPC does not continue processing the rest of instances.

It consists of a series of affectedLdapAttributes XML elements and the XML attributes shown in the following table:

4.3.1.3.1   affectedLdapAttribute

It is a structure representing the LDAP attribute whose modification triggered the event. The following table contains the XML attributes that can be set in it:

affectedLdapAttribute consists of the ordered sequence of:

• a series of oldLdapAttributeValue XML elements
• a series of newLdapAttributeValue XML elements

For multivalued LDAP attributes, a series of oldLdapAttributeValue and/or newLdapAttributeValue may be present including all the attribute values before and after the event which triggered the notification.

4.3.2   SOAP Notification Response Messages

For successful SOAP Notification Response messages, the root of the SOAP body is an empty notificationResponse XML element.

For unsuccessful SOAP Notification Response messages, the root of the SOAP body is a SOAP Fault XML element with the corresponding SOAP Fault Code as defined in Reference [1].

5   Bindings

The transport protocol used to carry SOAP messages is the Hypertext Transfer Protocol (HTTP). The HTTP request/response message model is followed as defined in Reference [2], providing SOAP request parameters in an HTTP request and SOAP response parameters in HTTP response. The only supported binding to carry the SOAP messages is the HTTP POST message request and its answer.

The HTTP content-type entity header must be always set to "text/xml".

The SOAPAction HTTP request header field is received as part of the HTTP request.

SOAP HTTP follows the semantics of the HTTP Status codes defined in Reference [2] for communicating status information in HTTP.

5.1   SOAP HTTP Request

The general format of the HTTP request is the following:

requested-web-service contains the Uniform Resource Locator (URL)-path of the SOAP server managing the notifications request. It is the following:

<VIP for Ext-DB>:8080/sapc/v1/notifications

For more information about the possible HTTP headers, see Reference [2].

The information to include in the different HTTP headers to carry a SOAP message in the HTTP request is specified in Reference [1]. The SOAPAction HTTP request header field (specific for SOAP) is defined as mandatory in Reference [1], however the SAPC ignores its value.

5.2   SOAP HTTP Answer

The general format of the HTTP answer is the following:

For more information about the possible HTTP headers to be defined in the request, see Reference [2].

The message body contains a SOAP message including the envelope and the body. If a header was present in the request, the SOAP message of the SOAP HTTP answer also contains a header.

The following HTTP Status codes defined in Reference [2] with their corresponding Reason-Phrase can be sent by the SAPC:

• 200 OK, when the operation was successful.
• 500 Internal Server Error when the operation was not successful (even for client faults at application level). After sending this response the SAPC closes the HTTP connection.See Section 6.

Other Status Codes related to HTTP protocol errors could be also sent by the SAPC, for more information see Reference [2]. In these cases, no SOAP message is included in the response.

6   Error Handling

The SAPC can return the following errors within SOAP Responses:

7   XML Schemas and WSDL

The WSDL including the XML schemas defined for the SOAP notification service, can be get in the following URL:

<VIP for Ext-DB>:8080/sapc/v1/notifications?wsdl

8   Message Examples

Example of Notification SOAP Request

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:ns1="http://schemas.ericsson.com/udc/1.0/"
   xmlns:ns2="http://schemas.ericsson.com/udc/1.0/types/">
 <SOAP-ENV:Body>
     <ns2:notify>
       <notificationEvent>provisioningEvent</notificationEvent>
       <modificationInformation ns2:dN="serv=PCRF,mscId=111115202550,ou=multiSCs,dc=o,dc=com">
	       <affectedLdapAttribute ns2:ldapAttributeName="WlServ" ns2:modification="replace" ns2:binary="false">
	           <oldLdapAttributeValue>Internet</oldLdapAttributeValue>
	           <newLdapAttributeValue>Chat</newLdapAttributeValue>
	        </affectedLdapAttribute>
	      </modificationInformation>
     </ns2:notify>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example of Successful SOAP Response returned by the SAPC

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
  xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns1="http://schemas.ericsson.com/udc/1.0/" 
  xmlns:ns2="http://schemas.ericsson.com/udc/1.0/types/">
<SOAP-ENV:Header></SOAP-ENV:Header>
<SOAP-ENV:Body>
   <ns2:notifyResponse></ns2:notifyResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example of Erroneous SOAP Response returned by the SAPC

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
  xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns1="http://schemas.ericsson.com/udc/1.0/" 
  xmlns:ns2="http://schemas.ericsson.com/udc/1.0/types/">
<SOAP-ENV:Body>
   <SOAP-ENV:Fault xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
     <faultcode>soap:Server</faultcode>
     <faultstring>Error from server</faultstring>
     <detail>Notification request is received, but reauthorizations are disabled.</detail>
   <SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP HTTP Answer Example

HTTP/1.1 200 OK
Server: gSOAP/2.8
Content-Type: text/xml; charset=utf-8
Content-Length: 508
Connection: keep-alive

Glossary

Reference List