SOAP Notification Interface Description

Ericsson Service-Aware Policy Controller

1 SOAP Notification Interface Overview

The SOAP interface offered by the SAPC to other network elements (such as an external database) is used to receive notifications about data changes when the SAPC subscriber data is stored only in an external database.

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.

Figure 1 The SAPC SOAP Notification from External Database

The notification interface offered by the SAPC is based on Simple Object Access Protocol (SOAP).

The transport protocol used to carry the SOAP notification messages is the Hypertext Transfer Protocol (HTTP).

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

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

3 Notification WSDL Data Structures

This section describes the XML data structures used.

Note:

XML elements and attributes are case-sensitive.

3.1 Envelope XML Elements

There is no specific information to be included in the SOAP Envelope but the specified in Simple Object Access Protocol (SOAP) 1.1 - W3C SOAP/1.1 Note.

3.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 Simple Object Access Protocol (SOAP) 1.1 - W3C SOAP/1.1 Note.

3.3 Body XML Elements

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

Figure 2 NotificationService Data Elements

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

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

Table 1 additionalInformation XML Attributes
XMLAttributes	Type	Required	Description
dN	String	Mandatory	It contains the provisioned Distinguished Name of the LDAP entry

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

Table 2 ldapAttribute XML Attributes
XMLAttributes	Type	Required	Description
ldapAttributeName	String	Mandatory	It contains the name of the LDAP attribute.
binary	Boolean	Optional	For binary LDAP attributes (the attribute contains binary values coded in base64), its value is "true" or "yes" Default value (when it is not present) is "false" or "no"

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.

3.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 (SOAP Notification Error Handling), 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:

Table 3 modificationInformation XML Attributes
XML Attributes	Type	Required	Description
dN	String	Mandatory	It stores the Distinguished Name of the LDAP object If the DN is not associated to a subscriber, the SAPC returns an error (see SOAP Notification Error Handling).
operation	String	Optional	It identifies the LDAP operation triggering the notification. Values: create modify delete If this attribute is not present, the SAPC assumes modify value. In Ericsson UDC solution, the SAPC decides the value for this attribute using the procedure explained in Integration in User Data Consolidation.

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

Table 4 affectedLdapAttribute XML Attributes
XML Attributes	Type	Required	Description
ldapAttributeName	String	Mandatory	It stores the name of the LDAP attribute
modification	String	Optional	It identifies the type of modification. Values: add remove replace

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.

Table 5 affectedLdapAttribute XML Elements
XML Element	Description
oldLdapAttributeValue	XML string storing the attribute value before the modification took place. It is only applicable for an LDAP modify or an LDAP delete.
newLdapAttributeValue	XML string storing the attribute value after the modification took place. It is only applicable for an LDAP modify or an LDAP add.

3.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 Simple Object Access Protocol (SOAP) 1.1 - W3C SOAP/1.1 Note.

4 SOAP 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 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 Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616 for communicating status information in HTTP.

4.1 SOAP HTTP Request

The general format of the HTTP request is the following:

Request=

Request-Method= POST

Request URI: requested-web-service

Request Version: HTTP/1.1

Content-Length: <length>

Content-Type: text/xml

< message-body>

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 Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616.

The information to include in the different HTTP headers to carry a SOAP message in the HTTP request is specified in Simple Object Access Protocol (SOAP) 1.1, 2000–08, W3C SOAP/1.1 Note. The SOAPAction HTTP request header field (specific for SOAP) is defined as mandatory in Simple Object Access Protocol (SOAP) 1.1, 2000–08, W3C SOAP/1.1 Note, however the SAPC ignores its value.

4.2 SOAP HTTP Answer

The general format of the HTTP answer is the following:

<Response>::=

HTTP/1.1

Response Code: <Result>

Content-Type: text/xml

< message-body >

For more information about the possible HTTP headers to be defined in the request, see Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616.

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 Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616 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 SOAP Notification Error Handling.

Other Status Codes related to HTTP protocol errors could be also sent by the SAPC, for more information see Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616. In these cases, no SOAP message is included in the response.

5 SOAP Notification Error Handling

The SAPC can return the following errors within SOAP Responses:

Table 6 Application Errors
SOAP faultcode	SOAP faultstring	SOAP detail	Description
soap:Client	Error from client	-	An invalid SOAP Request is received.
soap:Client	Error from client	NotificationEventType '<event>' not supported	The value received in notificationEvent is not supported.
soap:Client	Error from client	Unknown Object in dN='<dn>'	Unknown object received within dN.
soap:Server	Error from server	Notification request is received, but reauthorizations are disabled.	The sending of subscriber reauthorizations to the traffic gateway is disabled in the SAPC.
soap:Server	Error from server	Server overloaded	The SAPC is overloaded. The SOAP notification request does not proceed.

6 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

7 SOAP Notification Message Examples

7.1 Example of Notification SOAP Request

Example 1

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

7.2 Example of Successful SOAP Response returned by the SAPC

Example 2

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

7.3 Example of Erroneous SOAP Response returned by the SAPC

Example 3

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

7.4 SOAP HTTP Answer Example

Example 4

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

8 Reference List

Standards

Simple Object Access Protocol (SOAP) 1.1 - W3C SOAP/1.1 Note
Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616
UTF-8, a transformation format of ISO 10646 - RFC 2279
Lightweight Directory Access Protocol (LDAP): Directory Information Models - RFC 4512
The Base16, Base32, and Base64 Data Encodings - RFC 4648
W3C XML Schema Definition Language (XSDL) 1.1 Part 1: Structures- W3C Working Draft

Copyright	© Ericsson AB 2018. All rights reserved. No part of this document may be reproduced in any form without the written permission of the copyright owner.
Disclaimer	The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. Ericsson shall have no liability for any error or damage of any kind resulting from the use of this document.
Trademarks	All trademarks mentioned herein are the property of their respective owners. These are shown in the document Trademark Information.