One-NDSVersion 8.0SOAP Notification Interface SpecificationA50016-E4103-D851-2-7618 Nokia Siemens Networks is continually striving to reduce the adverse environmental effects of its products and services. We would like to encourage you as our customers and users to join us in working towards a cleaner, safer environment. Please recycle product packaging and follow the recommendations for power use and proper disposal of our products and their compo-nents.If you should have questions regarding our Environmental Policy or any of the environmental services we offer, please contact us at Nokia Siemens Networks for any additional information.2 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a28e73The information in this document is subject to change without notice and describes only the product defined in the introduction of this documentation. This documentation is intended for the use of Nokia Siemens Networks customers only for the purposes of the agreement under which the document is submitted, and no part of it may be used, reproduced, modified or transmitted in any form or means without the prior written permission of Nokia Siemens Networks. The documentation has been prepared to be used by professional and properly trained personnel, and the customer assumes full responsibility when using it. Nokia Siemens Networks welcomes customer comments as part of the process of continuous development and improvement of the documentation.The information or statements given in this documentation concerning the suitability, capacity, or performance of the mentioned hardware or software products are given "as is" and all liability arising in connection with such hardware or software products shall be defined conclusively and finally in a separate agreement between Nokia Siemens Networks and the customer. However, Nokia Siemens Networks has made all reasonable efforts to ensure that the instructions contained in the document are adequate and free of material errors and omissions. Nokia Siemens Networks will, if deemed necessary by Nokia Siemens Networks, explain issues which may not be covered by the document.Nokia Siemens Networks will correct errors in this documentation as soon as possible. IN NO EVENT WILL Nokia Siemens Networks BE LIABLE FOR ERRORS IN THIS DOCUMENTA-TION OR FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO SPECIAL, DIRECT, INDI-RECT, INCIDENTAL OR CONSEQUENTIAL OR ANY LOSSES, SUCH AS BUT NOT LIMITED TO LOSS OF PROFIT, REVENUE, BUSINESS INTERRUPTION, BUSINESS OPPORTUNITY OR DATA,THAT MAY ARISE FROM THE USE OF THIS DOCUMENT OR THE INFORMATION IN IT.This documentation and the product it describes are considered protected by copyrights and other intellectual property rights according to the applicable laws.The wave logo is a trademark of Nokia Siemens Networks Oy. Nokia is a registered trademark of Nokia Corporation. Siemens is a registered trademark of Siemens AG.Other product names mentioned in this document may be trademarks of their respective owners, and they are mentioned for identification purposes only.Copyright Nokia Siemens Networks 2013. All rights reservedf Important Notice on Product SafetyThis product may present safety risks due to laser, electricity, heat, and other sources of danger.Only trained and qualified personnel may install, operate, maintain or otherwise handle this product and only after having carefully read the safety information applicable to this product.The safety information is provided in the Safety Information section in the Legal, Safety and Environmental Information part of this document or documentation set.The same text in German:f Wichtiger Hinweis zur Produktsicherheit Von diesem Produkt knnen Gefahren durch Laser, Elektrizitt, Hitzeentwicklung oder andere Gefahrenquellen ausgehen.Installation, Betrieb, Wartung und sonstige Handhabung des Produktes darf nur durch geschultes und qualifiziertes Personal unter Beachtung der anwendbaren Sicherheits-anforderungen erfolgen.Die Sicherheitsanforderungen finden Sie unter Sicherheitshinweise im Teil Legal, Safety and Environmental Information dieses Dokuments oder dieses Dokumentations-satzes.A50016-E4103-D851-2-7618 3SOAP Notification Interface SpecificationId:0900d80580a28e73Table of ContentsThis document has 33 pages.Change History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92 One-NDS SOAP Notification Architecture . . . . . . . . . . . . . . . . . . . . . . .102.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102.2 Notification Processing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102.3 SOAP Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112.3.1 NDS SOAP Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122.3.2 NTF SOAP Limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 Trigger Configuration Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143.1 NDS SOAP Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143.1.1 Required Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163.2 Trigger Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 Notification Manager Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184.1 Inbound Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184.1.1 Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184.1.2 NTF SOAP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184.1.3 NTF SOAP Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184.1.4 Request Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194.2 NTF SOAP Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194.2.1 Message Dispatch Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194.2.2 Response Delivery Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194.2.3 Request Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204.3 Reliability and Availability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204.3.1 Reliability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204.3.2 Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204.4 Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214.5 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214.5.1 Application Receiver (AR) Response. . . . . . . . . . . . . . . . . . . . . . . . . . .214.5.2 NTF SOAP Server Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224.5.3 Overload Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224.5.3.1 NTF Overload. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224.5.3.2 SOAP Server Overload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224.5.4 Fault Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235 Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245.1 DN Case Trigger Transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245.2 V7 Trigger Object Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245.3 V7 Trigger Attribute Transformation. . . . . . . . . . . . . . . . . . . . . . . . . . . .25Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27SOAP Notification Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27SOAP Notification Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a28e73Alarms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29NDS Alarms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29NTF Alarms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29NTF Performance Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Terms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33A50016-E4103-D851-2-7618 5SOAP Notification Interface SpecificationId:0900d80580a28e73List of FiguresFigure 1 Processing of NDS triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Figure 2 NTF Watchdog SOAP message flow. . . . . . . . . . . . . . . . . . . . . . . . . . .216 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a28e73List of TablesTable 1 Recommended attribute values for NDS SOAP client . . . . . . . . . . . . . . 16A50016-E4103-D851-2-7618 7SOAP Notification Interface Specification Change HistoryId:0900d80580a28e35Change HistoryIssue 2 (09/2013)Updated section SOAP Server OverloadIssue 1 (04/2013)New Release8 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc115ReferencesReferences[NDS-OMG] One-NDS Directory: Operations and Maintenance GuideA50016-E4103-Q300-*-7619[NTF-GD] Notification Manager DescriptionA50016-E4103-D17-*-7618[Trig-DG] NTF Trigger Configuration GuideA50016-E4103-Q602-*-7619A50016-E4103-D851-2-7618 9SOAP Notification Interface Specification IntroductionId:0900d805809bc1551 IntroductionThis document contains or references all the information required by application devel-opers about the external One-NDS SOAP Notification interface, such as SOAP protocol details (versions, schema, limits), configuration options, alarms related to database trigger, and SOAP notification delivery. Examples for the configuration options and an example of a SOAP notification are also included.SOAP notification is the message generated as a result of trigger condition being satis-fied. Trigger is the condition defined in database against the data update.10 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc156One-NDS SOAP Notification Architecture2 One-NDS SOAP Notification Architecture2.1 OverviewOne-NDS system has built in notification mechanism which is used to notify its compo-nents about data updates in Network Directory Server (NDS). One-NDS components involved in SOAP notification besides the NDS are Notification Manager (NTF), Appli-cation Receivers, and One-NDS Administrator (ADM). SOAP notifications are delivered between the components by using SOAP protocol, which is the core protocol in One-NDS used for the notification.NDS generates a SOAP notification based on the updated data and sends it to the NTF. NTF component helps routing the SOAP notifications and a reliable delivery to applica-tions. Based on the configuration, NTF routes all the SOAP notifications to the config-ured application receivers. There are multiple NTF hosts in One-NDS system.Application receivers (ARs) are the targets for the notifications. ARs use the notifications and execute an action based on its contents. Each application has its own set of receiv-ers, which receive and process them. ADM is used for managing and configuration of One-NDS components. It is not involved directly in the notification flow. It uses LDAP and SOAP protocols for communication with the components.2.2 Notification Processing FlowNDS trigger process actively monitors the in-memory journal and for any updates that result during the execution of triggers, requesting SOAP notifications by using the NDS SOAP client (assuming the trigger action is a SOAP notification rather than an alarm).The SOAP notification is sent to the listening host-level HTTP load balancer on the external TCP port at the NTF host (NDS SOAP client distributes individual SOAP notifi-cations between the multiple NTF hosts in a round-robin manner).NTF Load Balancer distributes the load of notifications between the locally deployed service instances. The notifications, which belong to the specific SOAP services are accepted by the NTF inbound modules and persist it in the corresponding JMS Destina-tion inside the internal JMS Broker (Queue for Round Robin notifications, Topic for Mul-ticast notifications). After that, a SOAP response is generated for the NDS SOAP client accepting the received notification; from this point forward NTF is responsible for its reliable delivery to the AR(s).Depending on the configured delivery and re-delivery options, the JMS Broker performs the initial and, if needed, repeated delivery attempts of the persisted message to the configured AR(s).Configuration of the NDS SOAP client, NDS triggering conditions, and NTF registration data for the notification delivery is done by ADM based on the trigger templates coming from activated One-NDS Extension Packages (ExPs).Figure 1 illustrates the complete chain of NDS notification processing.A50016-E4103-D851-2-7618 11SOAP Notification Interface Specification One-NDS SOAP Notification ArchitectureId:0900d805809bc156Figure 1 Processing of NDS triggersTo avoid AR overload, NTF implements the mechanism to control flow of messages towards ARs (outbound rate) (refer to SOAP Server Overload). Message rate from DSA to a single NTF host (inbound rate) is limited by configuration to 100 messages per second. If the outbound rate to the NTF is lower than the inbound rate, the notifications are buffered in internal buffers. NTF must be configured to avoid buffering, since this may lead to error scenario in case of delivery. The performance is lower and if the buffers are filled up, NTF is overloaded and stops accepting new notifi-cations from NDS and an alarm is sent (refer to NTF Overload).NDS SOAP client also implements its internal buffering mechanism on the file system. If NTF can not process SOAP messages as fast as they are delivered, the messages are accumulated in the buffers. The previous notifications are overwritten with new ones, if the buffer fills up.2.3 SOAP ProtocolThis section describes the details of the SOAP protocol supported by NTF service when delivering notifications to the application frontends.SOAP schema for NDS notifications is described in the section SOAP Notification Schema and an example of a SOAP notification is explained in the section SOAP Noti-fication Example.Communication with NTF is based on HTTP v1.1 for transmitting SOAP messages. Supported SOAP versions and their namespaces are specified in following table.12 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc156One-NDS SOAP Notification ArchitectureNTF maintains a limited number of SOAP connections towards each configured appli-cation SOAP server; this limit is configurable.NTF communicates in synchronous mode on all connections. HTTP pipelining is not supported, that is, NTF sends the next message on each connection only after receiving a response to the previously sent message.NTF expects the Application Receivers SOAP server to respond with the HTTP_OK (200) status code, if it accepted the message. Delivery attempt fails if the response bears a different HTTP status code or if it contains a SOAP fault element. Unsuccess-fully delivered notifications are subject to redelivery by NTF. The numbers of delivery attempts are configurable.NTF controls the rate of notifications sent towards each application receiver. The maximum number of notifications sent per second is configurable separately for each SOAP service. If a single application receiver URL is registered in more number of SOAP services, minimal value of configured rate from all the relevant SOAP services is applied. Default value is set to 100 messages per second for all the SOAP services.2.3.1 NDS SOAP LimitsNDS SOAP client has the following limits for the: Total number of established connectionsThe maximum number of connections that the SOAP client establishes per service is 500. The actual number made is the number of connections made per port multi-plied by the number of distinct host and port combinations. Total size of SOAP messageThe maximum size of a SOAP message is 10K bytes including the header, which is approximately 316 bytes in addition to the size of the URL. Size of the XML tags and tag names in responses returned by the SOAP serviceThe maximum characters for the names of the XML tag attributes and attribute values can be 600. XML tags contain maximum number of 100 attributes.2.3.2 NTF SOAP LimitsNTF must support NDS limits regarding size of the SOAP message and its content. Additional limits specific for NTF: NTF cluster can support up to 150 Application Receivers for each SOAP service.SOAP VersionSOAP Version as Labeled by NDSSOAP Schema Namespace URIv1.1 v1.1 http://schemas.xmlsoap.org/soap/envelope/v1.2 n/a http://www.w3.org/2001/06/soap-envelopen/a http://www.w3.org/2001/09/soap-envelopen/a http://www.w3.org/2001/12/soap-envelopen/a http://www.w3.org/2002/06/soap-envelopev1.2a http://www.w3.org/2002/12/soap-envelopev1.2b http://www.w3.org/2003/05/soap-envelopeA50016-E4103-D851-2-7618 13SOAP Notification Interface Specification One-NDS SOAP Notification ArchitectureId:0900d805809bc156 Maximum 765 of total registrations is supported (SOAP Service/Application receiver pair). NTF server processes minimum number of 500 SOAP notifications of 5 KB size per second. NTF SOAP server can serve maximum number of 1000 parallel connections. NTF SOAP client supports maximum number of 1000 parallel connections towards single Application Frontend, provided the system limit does not exceed. It is recom-mended to use low connections to transport the notifications without accumulation. The system resources can be affected by using a lot of connections.14 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a28e39Trigger Configuration Interface3 Trigger Configuration InterfaceNDS database triggers are defined by using two elements: A set of conditions that determine the application of trigger to update. A set of actions that specify an action for updates that match the conditions.The action is generated either by raising an alarm or generating a SOAP message. This SOAP message may contain complete or filtered details about the update performed and the data affected and may be presented to the recipient through an appropriately adapted view.Database trigger conditions are specified in dsTrigEntry instances (see [Trig-DG]). Trigger actions are specified in dsTrigAction instances (see [Trig-DG]).For SOAP triggers, a soapClientService instance specifies the attributes of the remote SOAP service (see NDS SOAP Client).Trigger conditions are evaluated on the actual object and attributes updated and not on the adapted view of the data (including access through variants), which is supplied by the client. The actions are defined such that the notification is adapted, presenting the information in a expected manner by the client. This includes grouping together updates to multiple entries that may be performed by a variant object.3.1 NDS SOAP ClientSOAP clients in NDS buffer all trigger requests and generate appropriate SOAP messages for remote SOAP services. These SOAP services are registered by creating instances of the soapClientService object in the NDS configuration data hierarchy (see [Trig-DG]).The same soapClientService data must be maintained on all the DSAs in the system.The configuration attributes of this object class are:soapServiceThe name of the service. The string contains maximum of 20 characters.gThe same string is used for the particular SOAP service in the NTF Registration data. The associated NTF Registration data entry is created automatically by ADM during trigger package activation.soapUrlListThe URL(s) for the remote SOAP servers.gADM automatically inserts the list of all NTF URL addresses used for trigger processing in the system to this attribute during the trigger package activation. This list is also auto-matically updated when a new NTF host is added to the system. Configuration of the Application Frontend URL addresses to which the notifications are delivered is done in the NTF Registration data instead. (see [Trig-DG]).soapUrlUpdIntTime interval in seconds, during which the SOAP client checks changes to its configu-ration data.soapMaxRateA50016-E4103-D851-2-7618 15SOAP Notification Interface Specification Trigger Configuration InterfaceId:0900d80580a28e39The maximum number of SOAP requests that the SOAP client sends to a single service per second. The permitted range of values is from 0 to 500, with 0 disabling the SOAP service. It has a relation to the NTF parameter nsNinMaxMessageRate, which limits the SOAP notifications towards receivers.ADM sets value of soapMaxRate to 100 during application trigger activation as it is part of the interface between NDS and NTF. Application developers are not allowed to modify the value.soapRespTimeoutThe response timeout, in milliseconds for a SOAP request.ADM sets value of soapRespTimeout to 40000 (40s) during trigger activation as it is part of the interface between NDS and NTF.soapSendAttemptsThe number of times the SOAP client attempts to send a SOAP requests to each service. The request is discarded in case of failure. It has a relation to the NTF attribute nsNinDeliveryAttempts.Value of soapSendAttempts is changed during trigger activation to ignore the value defined in trigger package. The defined value is configured in the NTF attribute nsNinDeliveryAttempts.soapLoadShareThe method is used to deal with multiple servers. If set to roundRobin, the requests are sent to each of the servers in turn. If set to broadcast, each request is sent to every server.gNotifications are sent to NTF in roundRobin mode. For broadcast notifications, ADM changes the value of this attribute to roundRobin during trigger package activation and sets the Multicast request delivery policy for the associated SOAP Service in NTF reg-istration data. If this rule is not followed in case of manual definition then BC notification is sent to each NTF host with the consequence that BC notification is sent from each NTF (refer to the section Message Dispatch Policy).soapMepThis must be set to requestOnly for SOAP services notified by the trigger process.soapConnModeThis may be either synchronous or asynchronous. The normal mode of operation is syn-chronous and in this mode a SOAP client must wait for an acknowledgement from the server before sending any further requests. Asynchronous mode means HTTP pipelin-ing, there is no callback endpoint configured.soapConnsPerPortThe number of simultaneous connections that the SOAP client establishes to each of the servers identified in soapUrlList. The attribute is part of the interface towards NTF.soapVersionThe version of the SOAP protocol is used to communicate with the SOAP servers.For more information regarding individual attributes, refer to the [NDS-OMG], section Registering SOAP Services.16 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a28e39Trigger Configuration Interface3.1.1 Required Attribute ValuesgThe ExP trigger definition of SOAP client contains the following attributes values (refer to Table 1). Table 1 lists the required configuration for the selected SOAP client attri-butes. To use a different value, the project must announce this change and its reason to One-NDS NTF support and test its project specific configuration.3.2 Trigger ConfigurationThis section describes the configuration data, which is used to define triggers and their associated actions. It outlines the configuration objects involved and provides a detailed description of their attributes.gTriggers are fired, if the trigger configuration data, which is stored on the same DSA as the object(s) are updated. Therefore, it is easy to maintain the same triggering configu-ration data on all the DSAs in the system. There is no performance overhead, if there are no instances of the monitored objectClass on a DSA.Attributes Recommended ValuesRecommendationsoapUrlUpdInt 10 Set value 10gThe value 10 must be requested.soapMaxRate 100 Set a value that is supported by your application receivers. SOAP services with shared receivers must have the same value of soapMaxRate.soapRespTimeout 40000 Set value to 40000gIn case a different value than 40000 as configured, One-NDS sets the value to 40000.soapSendAttempts 3 Set value to 3. A higher value is used in case of requirement.gHigh number of attempts can decrease the performance of noti-fication delivery.soapLoadShare roundRobin Set value to roundRobinAlternative: When all receivers must get the notification, set value to broadcast, which has a lower performance due to notification delivery to each receiver of this SOAP service.soapMep requestOnly Set value to requestOnlygThe value requestOnly must be requested.soapConnMode asynchronous Set value to asynchronousgThe value asynchronous must be requested.soapConnsPerPort 1 Set value to 1gThe value 1 must be requested.Table 1 Recommended attribute values for NDS SOAP clientA50016-E4103-D851-2-7618 17SOAP Notification Interface Specification Trigger Configuration InterfaceId:0900d80580a28e39Trigger configuration consists of configuring three types of objects in NDS configuration: Trigger EntryIt represents the set of conditions that must be satisfied before generating the SOAP notification. Trigger ObjectIt consists of a list of actions that are performed after the trigger conditions are sat-isfied. The actions affect content of the SOAP message. Trigger View ExtensionIt affects content of the SOAP message, which modifies object and attribute names according to the requirement of the application view.For more information regarding triggering configuration, refer to the [Trig-DG].18 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a2c195Notification Manager Interface4 Notification Manager InterfaceFigure 1 illustrates the role of an NTF in an NTF cluster and its cooperation with NDS SOAP client and Application Receivers.4.1 Inbound Transport4.1.1 Load BalancingLoad balancer distributes incoming notification messages across all local NTF service instances (by default, 2 service instances are deployed on an NTF host). One instance of Apache HTTP Server with Proxy Balancer module does the job while listening at one external TCP port for incoming traffic.4.1.2 NTF SOAP ServerNTF creates its notification receiving inbound endpoints by using following template:http://:/NotificationService/services/where, is the IP address from where the NTF service is accessible. is the TCP port from where the NTF service is accessible. is the endpoint name, default name is Common.Notifications related to multiple SOAP Services may be received at one inbound end-point. However, only SOAP Services with the same response delivery policy (Request/Response or Remote Request/Response, see Response Delivery Policy) may share one endpoint. NDS always sends notifications (Round robin and Multicast as well) to Common endpoint that is created by default in NTF, no extra configuration is required. Message identification of all SOAP Services sharing one endpoint must be unambiguous. For more information on message identification, refer to [NTF-GD].4.1.3 NTF SOAP ResponsesNTF responses are built from three items: HTTP Status Code SOAP Envelope SOAP FaultEvery request accepted by NTF is followed by an NTF response bearing HTTP_OK (200) status code. Every NTF response to a SOAP request contains SOAP Envelope copy from the original request.If the NTF Service Instance cannot accept the message for processing, it responds with corresponding HTTP Error status code and the message body also contains SOAP Fault element with corresponding error description. For error response details and example, refer to NTF SOAP Server Response. Only exception is the case when error response originates from the Host HTTP Load Balancer where the SOAP content is missing. The load balancer may respond by an error from various reasons, for example, A50016-E4103-D851-2-7618 19SOAP Notification Interface Specification Notification Manager InterfaceId:0900d80580a2c195the request URL is invalid or it can not forward the request to the selected NTF service instance.4.1.4 Request LoggingAll HTTP requests received by the NTF service are logged by using Request log. It serves as a tracking tool and is switched off by default. For more information, refer to [NTF-GD].4.2 NTF SOAP ClientThe outbound transport consists of HTTP connections and SOAP messages sent by NTF. gSending an outbound message is forwarding an inbound message. NTF receives an inbound message and forwards or sends it as an outbound message. That is, NTF does not produce outbound traffic on its own.NTF expects the SOAP Server to respond with the HTTP_OK (200) status code, if it accepts the message. Responses bearing different HTTP status code cause the delivery attempt to fail. Delivery attempt is also considered as unsuccessful, if the response contains SOAP fault element.4.2.1 Message Dispatch PolicyNTF allows message distribution in one of following dispatch policies or distribution pat-terns: Multicast (MC)Message is distributed to a specified list of ARs. Each AR receives all published messages. Round Robin (RR)Messages are distributed in a multiplexed way. According to specified ordered list of SOAP Servers, messages are sent to the next notification SOAP Server in a circular way. For more information regarding individual message dispatch policies, refer to [NTF-GD]. 4.2.2 Response Delivery PolicyNTF offers following response delivery policies: Request/Response (2R)Asynchronous mode, in which NTF receives the given message, stores it persis-tently in its message storage on the file system (for example, queue), and generates a response to the message sender after the message is persisted. This approach makes it sure that no NDS notification is lost. The delivery to the AR takes place, once the response to the message sender is already sent, and no other response concerning this message follows.This response delivery policy is used for SOAP notifications sent by NDS.20 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a2c195Notification Manager Interface Remote Request/Response (3R)Synchronous mode, in which the message sender receives the response from the end SOAP Server of the message. This approach is available only for the RR message dispatch policy.For more information regarding individual message response delivery policies, refer to [NTF-GD].4.2.3 Request LoggingEvery SOAP message that NTF fails to deliver to its intended SOAP Server according to configured Dispatch policy and Redelivery algorithm properties is stored in Dead Letter Log. For more information, refer to [NTF-GD].Every SOAP message of a known type, which NTF fails to perform any delivery attempt is stored in Discarded Letter Log. This may be the case of NTF being in the JMS Overload situation (for more information, refer to the section NTF Overload) or the case when no SOAP Servers are registered for the given SOAP service. For more informa-tion, refer to [NTF-GD].NTF provides other logging services: Request logIt logs all the messages which are accepted by the NTF service instance. It is switched off by default, because it has impact on performance. Failed delivery attempt logIf an attempt to deliver notification to an AR fails for any reason, the reason is written in the log. Debug logs, configuration logIf NTF does not work as per expectation, it helps to identify the problem.4.3 Reliability and Availability4.3.1 ReliabilityNTF provides reliable delivery for notifications, that is, it shifts the responsibility for their delivery from NDS SOAP clients to its internal reliable messaging framework.NTF generates the message accepting response to NDS only after it stores the notifica-tion in a persistent storage, safe against service crash or energy supply failures. Notifi-cations are subject to redelivery in case of failed delivery attempts (that is, network connection failures or inability of AR to accept the delivered message).For more information regarding persistency and redelivery provided by NTF, refer to [NTF-GD].4.3.2 AvailabilityTo provide high availability, the NTF uses redundancy and its processes are secured by Watchdog.NTF service redundancy is provided by multiple NTF hosts. NTF clients such as NDS are configured to distribute notifications equally among the NTF hosts (for example, in a round robin manner). Clients are also expected to use other NTF hosts in case their primary one is not available.A50016-E4103-D851-2-7618 21SOAP Notification Interface Specification Notification Manager InterfaceId:0900d80580a2c195Watchdog is a process running on each NTF host that checks condition of the local Apache load balancer and local NTF service instances and restarts them if they are not in a healthy state.Figure 2 NTF Watchdog SOAP message flowFor more information on availability and redundancy, refer to [NTF-GD].4.4 PerformanceNTF collects performance data (number of requests received, delivered, failed, and so on) in the form of counters. Counter values are written to the host-specific LDAP nodes in PGW-DSA, from where they are read out by agents specific for the OAM solution of the customer.For more details on performance monitoring and detailed list of counters, refer to [NTF-GD].4.5 Error Handling4.5.1 Application Receiver (AR) ResponseNTF expects the AR to respond with the HTTP_OK (200) status code if it accepts the message. Responses bearing different HTTP status code cause the delivery attempt to fail. Delivery attempt is taken as unsuccessful also if the response contains a SOAP fault element.Each unsuccessful attempt to deliver a notification from NTF (either indicated by the AR or caused by the inability of NTF to deliver the message to the AR) is logged in the failed delivery attempt log on NTF.NTF does not distinguish between different reasons of delivery failures, neither client (NTF) or server (AR) specific HTTP, nor SOAP error responses. Depending on the con-figured redelivery options, NTF attempts to re-deliver failed messages, see section Reli-ability.For more information, refer to [NTF-GD].22 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d80580a2c195Notification Manager Interface4.5.2 NTF SOAP Server ResponseIf the NTF service interface fails to process the received notification, it responds with an HTTP error response specific for the particular error situation.Complete list of the error response codes and an example of a SOAP/HTTP error response can be found in [NTF-GD].4.5.3 Overload Situations4.5.3.1 NTF OverloadNTF overload is a situation in which NTF fails to provide the service anymore. The fol-lowing NTF overload types may arise: JMS OverloadIt is caused by a message queue which is full to accept more messages. Partition OverloadIt is caused when the file system partitions used by the service are used completely and NTF fails to provide space necessary for storing message data and/or log files. Inbound Endpoint OverloadIt is caused when multiple parallel requests are handled at a time.In the JMS Overload situation, NTF attempts to accept all incoming messages with HTTP OK (200) to avoid overload on the DSA side. However, all the newly received messages are automatically discarded and written in the Discarded Letter Log. In other overload cases, NTF fails to receive any more messages and it responds with HTTP 503 error code. In such a case, DSA SOAP client must either contact another NTF host or wait and try again after some time. For more information on NTF error responses, refer to [NTF-GD].NTF tries to prevent the overload situations by monitoring the reachability states of every AR or registration (that is, particular SOAP service with a particular AR association).In every overload case or if any SOAP Server/registration becomes unreachable, NTF raises the corresponding alarm. NTF also clears the alarm after the overload/unreach-ability situation is cleared. For alarm details refer to the section NTF Alarms.For more details on individual NTF overload situations and mechanisms for their preven-tion, refer to [NTF-GD].4.5.3.2 SOAP Server OverloadNTF can be configured to control the outbound traffic, so that the AR endpoints are not overloaded either by high inbound notification rate or by large number of notifications received in parallel.NTF applies a maximum message rate for individual Application Receivers (ARs), which is calculated from the configured maximum message rate parameters of the SOAP services where the AR is registered.NTF does not raise any SOAP Server overload alarms, but helps prevent the overload by following the configured limits. The SOAP Servers handle their real overload status themselves and raise corresponding alarms.For more information, refer to [NTF-GD].A50016-E4103-D851-2-7618 23SOAP Notification Interface Specification Notification Manager InterfaceId:0900d80580a2c1954.5.4 Fault ManagementFor situations requiring operator notification, NTF raises alarms. The alarms from the NTF are received by FM Agent running at the same host forwarding the alarm to its server for further processing. The type of the agent used depends on the variant of the OAM solution.For more information, refer to [NTF-GD].For the list of NTF alarms, refer to the section NTF Alarms.24 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc159Backward Compatibility5 Backward CompatibilityNTF provides optional transformations of notification messages to provide backward compatibility of the notifications generated by One-NDS with certain applications expecting older format. Transformations are configured on the basis of SOAP service. The following message transformation options are available: DN Case Trigger Transformation V7 Trigger Object Transformation V7 Trigger Attribute Transformation5.1 DN Case Trigger TransformationCase of LDAP attributes contained in the trigger object element DN attribute value may be different in the One-NDS 8.0. Some applications cannot process such notification.DN Case trigger transformation changes the attribute names to lower case. The trans-formation is switched on automatically for each Message Type (MT) with name starting trigger. For other MTs it can be switched on by configuration on the basis of SOAP Service.ExampleBefore transformation...

TRUE

...After transformation...

TRUE

...5.2 V7 Trigger Object TransformationThe previous version of One-NDS generates notifications where the same trigger object element (with the same DN attribute) can be repeated. Some applications are not able to process such notifications.A50016-E4103-D851-2-7618 25SOAP Notification Interface Specification Backward CompatibilityId:0900d805809bc159V7 Trigger Object transformation merges the trigger object elements with the same DN attribute value to one. The grouped object element uses the operation attribute from the first object element.ExampleBefore transformation...

TRUE

TRUE

TRUE

...After transformation...

TRUE

TRUE

TRUE

...5.3 V7 Trigger Attribute TransformationNDS v7.1 uses the delete/add operation in case of an attribute modification. NDS v8.0 uses the replace modification instead. Some applications are not able to process such notification.V7 Trigger Attribute transformation replaces the replace operation of the attributes by a sequence of delete/add operations. As a result, the transformed notification reports deleting all values, which existed before the operation, and adding all values, which exist after the operation.ExampleBefore transformation... FALSE TRUE

...26 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc159Backward CompatibilityAfter transformation:... FALSE

TRUE

...A50016-E4103-D851-2-7618 27SOAP Notification Interface Specification AppendixId:0900d805809bc114AppendixSOAP Notification Schema

28 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc114Appendix

SOAP Notification ExamplePOST HLR HTTP/1.1Host: hlrURLContent-Type: text/xmlContent-Length: nnnn

10

1020

102020

20

20

A50016-E4103-D851-2-7618 29SOAP Notification Interface Specification AppendixId:0900d805809bc114

AlarmsNDS AlarmsThe following is the list of NDS alarms and the alarm numbers related to trigger process-ing. More details can be found in [NDS-OMG]. Invalid SOAP URL (0005:0264) No free SOAP Port Entries (0005:0265) No free SOAP Resource Location Entries (0005:0266) SOAP Name Too Long (0005:0267) No SOAP Connection (0005:0268) SOAP HTTP Error Response (0005:0270) SOAP Fault Response (0005:0271) SOAP Invalid Maximum Rate (0005:0272) SOAP Payload Exceeded (0005:0276) SOAP Overload (0005:0284) SOAP Service Unavailable (0005:0288) Triggering Threshold (0005:0295) Trigger Data Overloaded (0005:0301) Missing Trigger Action (0005:0303) Missing Trigger View Extension (0005:0304) Trigger Syntax Error (0005:0305) Trigger Action Syntax Error (0005:0306) Trigger View Extension Syntax Error (0005:0307) Trigger References Unknown Schema Item (0005:0308) Trigger Processing Medium Overload (0005:0309) Trigger Processing High Overload (0005:0310) Trigger Action Generated Alarm (0005:0311)gFor more information regarding NDS alarms, refer to the Alarm Repair Manual (A50016-E4103-M580-*-7620).NTF AlarmsThe list of alarms that can be raised by NTF can be found in [NTF-GD].The following alarms indicate a serious startup error that causes malfunctioning of the entire NTF service instance. Notifications must be delivered by other NTF service instances in the cluster: InvalidConfigurationGlobalPropertyData (02) InvalidGlobalPropertyFile (4) InvalidLoggerConfiguration (10) InvalidInstallation (26)gThe probability of alarm 10 and 26 occurrence is low as they are related to the configu-ration files that are not externally modified.30 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc114AppendixThe following alarm indicates that the given NTF service instance is stopped intention-ally (by operator or some automatic logic) or automatically in case the NTF service instance free memory gets low: ServiceShutdownInvoked (33)The following alarms indicate an invalid entry in the NTF configuration or registration data or other problem while reading the configuration. This makes NTF use either default value (on startup) or old value (on configuration/registration update). Notifica-tions may be delivered in other way than intended or not delivered at all: InvalidConfigurationLdapData (3) ConfigurationDataUpdateFailed (6) InvalidSubscriptionData (7) SubscriptionDataUpdateFailed (8) UsingDefaultConfigurationValue (24) ConfigurationDataLoadFailedAlarm (30) SubscriptionDataLoadFailedAlarm (31)The following alarms indicate exhaustion of important system resources, which may negatively affect acceptance of new notifications or delivery of already accepted ones: JmsStorageOverload (22) MaxNumberOfParallelRequestsReached (23) FileSystemStorageFull (25) NotificationBufferOverloadAlarm (29)The following alarms are directly related to problems in the delivery of a particular SOAP message: UnknownSoapMessageReceived (20) InvalidSoapMessageReceived (21) SoapReceiverUnreachable (28) RegistrationUnreachable (40)gOther types of alarms indicate problems indirectly related to notification delivery, such as errors while updating performance counters, logging, and so on. For more information regarding NTF alarms, refer to the Alarm Repair Manual (A50016-E4103-M580-*-7620).NTF Performance CountersNotification Manager provides an interface to the One-NDS Performance Management by using Performance counters stored in the configuration DSA. Each NTF host has its own set of counters.There are following categories of NTF counters: Request receivedNumber of Notification requests received. Request deliveredNumber of delivered Notification requests. Request storedNumber of Notification requests stored for processing.A50016-E4103-D851-2-7618 31SOAP Notification Interface Specification AppendixId:0900d805809bc114 Request undeliverableNumber of undeliverable Notification requests. Request delivery attempt failedNumber of failed attempts to deliver Notification requests. Request failedNumber of failed authentication attempts of Notification requests. Invalid requestNumber of invalid Notification requests received.Within the categories, there are also separate counters for Message dispatch policies and Response delivery policies.Extra counter categories that are related to the NTF administration: Admin-AuthenticationFailedNumber of failed authentication attempts of Administration requests. Admin-InvalidRequestNumber of invalid Administration requests received. Admin-RequestFailedNumber of Administration requests with errors during their processing. Admin-RequestProcessedNumber of successfully processed Administration requests. Admin-RequestReceivedNumber of Administration requests received.The complete list of NTF counters are: Admin-AuthenticationFailed Admin-InvalidRequest Admin-RequestFailed Admin-RequestProcessed Admin-RequestReceived Notification-AuthenticationFailed Notification-InvalidRequest Notification-RequestDelivered Notification-RequestFailed Notification-RequestReceived Notification-RequestUndeliverable MC-2R-Policy-DeliveryAttemptFailed MC-2R-Policy-RequestDelivered MC-2R-Policy-RequestFailed MC-2R-Policy-RequestReceived MC-2R-Policy-RequestStored MC-2R-Policy-RequestUndeliverable RR-2R-Policy-DeliveryAttemptFailed RR-2R-Policy-RequestDelivered RR-2R-Policy-RequestFailed RR-2R-Policy-RequestReceived RR-2R-Policy-RequestStored RR-2R-Policy-RequestUndeliverable RR-3R-Policy-DeliveryAttemptFailed32 A50016-E4103-D851-2-7618SOAP Notification Interface SpecificationId:0900d805809bc114Appendix RR-3R-Policy-RequestDelivered RR-3R-Policy-RequestFailed RR-3R-Policy-RequestReceived RR-3R-Policy-RequestUndeliverableFor more information on NTF performance counters, refer to User Manual (@Com variant) (A50016-E4103-Q700-*-7619), User Manual (NetAct/SM variant) (A50016-E4103-Q701-*-7619).A50016-E4103-D851-2-7618 33SOAP Notification Interface Specification Terms and AbbreviationsId:0900d805809bc113Terms and AbbreviationsADM One-NDS AdministratorDN distinguished nameDSA directory server agentLDAP lightweight directory access protocolLDIF LDAP data interchange format(One) NDS (One) Network Directory ServerNE network elementNTF notification managerSOAP simple object access protocol