Web Service Notifications

Notification: generation in a service interface

Related to issue #67 in Mantis Notification: generation in a service interface

This covers the use case of an explicit Notification present in the project and how it is generated in a given service interface.

Mapping Rule

An entity type is called notification enabled if it is OC enabled, or ODisc enabled, or ODel enabled, or AVC enabled, or SC enabled. The same concept can apply to association classes, or even other artifacts.

Given a service interface (i.e. session facade artifact), we say it is notification enabled if there exists an operation, at least one of its arguments (in, inout, out) is of notification enabled type.

For a notification enabled session facade, when the generator maps it to TIP WSDL, it will 'inject' WS-N capability into WSDL, this means, in TIP WSDL, we import OASIS WS Notification Specification v1.3 (=the latest stable version at 2010 March) web services, and add corresponding bindings and services. We'll give the details in following examples.

Example (notification enabled service facade)

In TIP SPM model, the session facade org.tmforum.tip.service.problem.ServiceProblemInterface is notification enabled because it operates on notification enabled ServiceProblem. The whole picture of its corresponding WSDL is:

Now we analyze some important parts.

First, the WS-Notification WSDL wsn_binding_http.wsdl is generated and imported into TIP WSDL:

<wsdl:definitions 
    xmlns:tns="http://www.tmforum.org/xml/tip/service/problem" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:wsn_bindings_http="http://www.tmforum.org/xml/tip/wsnbindings/http" 
    name="ServiceProblemInterface" 
    targetNamespace="http://www.tmforum.org/xml/tip/service/problem">
	
    <wsdl:import namespace="http://www.tmforum.org/xml/tip/wsnbindings/http" location="wsn_bindings_http.wsdl"/>

    <other part are omitted here>
</wsdl:definitions>

where the wsn_bindings_http.wsdl provides SOAP/HTTP binding for 2 main WSN ports - NotificationProducer and PausableSubscriptionManager. Note that their namespace is http://docs.oasis-open.org/wsn/bw-2.

binding of wsnt:NotificationProducer:

	<wsdl:binding name="NotificationProducerSoapHttpBinding" type="wsnt:NotificationProducer">
		<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
		<!-- =========== NotificationProducer Specific ============== -->
		<wsdl:operation name="Subscribe">
			<soap:operation soapAction="Subscribe" style="document"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
			<wsdl:fault name="ResourceUnknownFault">
				<soap:fault name="ResourceUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="SubscribeCreationFailedFault">
				<soap:fault name="SubscribeCreationFailedFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="TopicExpressionDialectUnknownFault">
				<soap:fault name="TopicExpressionDialectUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="InvalidFilterFault">
				<soap:fault name="InvalidFilterFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="InvalidTopicExpressionFault">
				<soap:fault name="InvalidTopicExpressionFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="TopicNotSupportedFault">
				<soap:fault name="TopicNotSupportedFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="InvalidProducerPropertiesExpressionFault">
				<soap:fault name="InvalidProducerPropertiesExpressionFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="InvalidMessageContentExpressionFault">
				<soap:fault name="InvalidMessageContentExpressionFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="UnacceptableInitialTerminationTimeFault">
				<soap:fault name="UnacceptableInitialTerminationTimeFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="UnrecognizedPolicyRequestFault">
				<soap:fault name="UnrecognizedPolicyRequestFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="UnsupportedPolicyRequestFault">
				<soap:fault name="UnsupportedPolicyRequestFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="NotifyMessageNotSupportedFault">
				<soap:fault name="NotifyMessageNotSupportedFault" use="literal"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="GetCurrentMessage">
			<soap:operation soapAction="GetCurrentMessage" style="document"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
			<wsdl:fault name="ResourceUnknownFault">
				<soap:fault name="ResourceUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="TopicExpressionDialectUnknownFault">
				<soap:fault name="TopicExpressionDialectUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="InvalidTopicExpressionFault">
				<soap:fault name="InvalidTopicExpressionFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="TopicNotSupportedFault">
				<soap:fault name="TopicNotSupportedFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="NoCurrentMessageOnTopicFault">
				<soap:fault name="NoCurrentMessageOnTopicFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="MultipleTopicsSpecifiedFault">
				<soap:fault name="MultipleTopicsSpecifiedFault" use="literal"/>
			</wsdl:fault>
		</wsdl:operation>
	</wsdl:binding>

binding of wsnt:PausableSubscriptionManager:

	<wsdl:binding name="SubscriptionManagerSoapHttpBinding" type="wsnt:PausableSubscriptionManager">
		<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
		<!-- ========= SubscriptionManager specific operations ====== -->
		<wsdl:operation name="PauseSubscription">
			<soap:operation soapAction="PauseSubscription" style="document"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
			<wsdl:fault name="ResourceUnknownFault">
				<soap:fault name="ResourceUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="PauseFailedFault">
				<soap:fault name="PauseFailedFault" use="literal"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="Renew">
			<soap:operation soapAction="Renew" style="document"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
			<wsdl:fault name="ResourceUnknownFault">
				<soap:fault name="ResourceUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="UnacceptableTerminationTimeFault">
				<soap:fault name="UnacceptableTerminationTimeFault" use="literal"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="Unsubscribe">
			<soap:operation soapAction="Unsubscribe" style="document"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
			<wsdl:fault name="ResourceUnknownFault">
				<soap:fault name="ResourceUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="UnableToDestroySubscriptionFault">
				<soap:fault name="UnableToDestroySubscriptionFault" use="literal"/>
			</wsdl:fault>
		</wsdl:operation>
		<wsdl:operation name="ResumeSubscription">
			<soap:operation soapAction="ResumeSubscription" style="document"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
			<wsdl:fault name="ResourceUnknownFault">
				<soap:fault name="ResourceUnknownFault" use="literal"/>
			</wsdl:fault>
			<wsdl:fault name="ResumeFailedFault">
				<soap:fault name="ResumeFailedFault" use="literal"/>
			</wsdl:fault>
		</wsdl:operation>
	</wsdl:binding>

In TIP WSDL, we can see these WSN ports under the wsd:services element:

	<wsdl:service name="ServiceProblemInterfaceWs">
		<wsdl:port name="ServiceProblemInterfaceHttpPort" binding="tns:ServiceProblemInterfaceSoapHttpBinding">
			<soap:address location="http://localhost/ServiceProblemInterface"/>
		</wsdl:port>
		<wsdl:port name="NotificationProducerHttpPort" binding="wsn_bindings_http:NotificationProducerSoapHttpBinding">
			<soap:address location="http://localhost/ServiceProblemInterface/NotificationProducer"/>
		</wsdl:port>
		<wsdl:port name="SubscriptionManagerHttpPort" binding="wsn_bindings_http:SubscriptionManagerSoapHttpBinding">
			<soap:address location="http://localhost/ServiceProblemInterface/SubscriptionManager"/>
		</wsdl:port>
	</wsdl:service>

Example (a web service notification sample)

a WSN notification is an instance of 'Notify' element in the namespace http://docs.oasis-open.org/wsn/b-2, its main body will be TIP notifications, e.g. an instance of serviceProblemObjectCreationNotification.

<?xml version="1.0" encoding="UTF-8"?>
<wsnt:Notify xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:notifications="http://www.tmforum.org/xml/tip/internal/notifications" xmlns:problem="http://www.tmforum.org/xml/tip/cbe/problem" xmlns:entity="http://www.tmforum.org/xml/tip/internal/entity" xmlns:serviceProblem="http://www.tmforum.org/xml/tip/service/problem">
	<wsnt:NotificationMessage>
		<wsnt:SubscriptionReference>
			<wsa:Address>http://localhost:8080/wsn-producer/services/SubscriptionManager</wsa:Address>
			<wsa:ReferenceParameters/>
			<wsa:Metadata/>
		</wsnt:SubscriptionReference>
		<wsnt:Topic Dialect="http://www.tmforum.org/wsn/t-1/TopicExpression/Simple">topicName</wsnt:Topic>
		<wsnt:ProducerReference>
			<wsa:Address>http://localhost:8080/wsn-producer/services/NotificationProducer</wsa:Address>
			<wsa:ReferenceParameters/>
			<wsa:Metadata/>
		</wsnt:ProducerReference>
		<wsnt:Message>
                        <!--an instance of serviceProblemOCN-->
			<serviceProblem:serviceProblemOCN>
					<notifications:sourceTime>14:20:00.0Z</notifications:sourceTime>
					<notifications:objectType>String</notifications:objectType>
					<notifications:objectId>
						<entity:scheme>1</entity:scheme>
						<entity:value>text</entity:value>
						<entity:context>text</entity:context>
						<entity:encoding>String</entity:encoding>
					</notifications:objectId>
					<notifications:extensionInfo/>
					<serviceProblem:object>
						<entity:identifier>
							<entity:scheme>1</entity:scheme>
							<entity:value>text</entity:value>
							<entity:context>text</entity:context>
							<entity:encoding>String</entity:encoding>
						</entity:identifier>
						<entity:extensionInfo/>
						<problem:originatingSytem>String</problem:originatingSytem>
						<problem:affectedServiceNumber>0</problem:affectedServiceNumber>
						<problem:impactImportanceFactor>0</problem:impactImportanceFactor>
						<problem:priority>0</problem:priority>
						<problem:description>String</problem:description>
						<problem:firstAlert>String</problem:firstAlert>
						<problem:category>String</problem:category>
						<problem:responsibleParty>String</problem:responsibleParty>
						<problem:problemEscalation>0</problem:problemEscalation>
						<problem:comments>
							<problem:item>
								<problem:userId>String</problem:userId>
								<problem:time>1967-08-13</problem:time>
								<problem:systemId>String</problem:systemId>
								<problem:comment>String</problem:comment>
							</problem:item>
						</problem:comments>
						<problem:timeRaised>1967-08-13</problem:timeRaised>
						<problem:timeChanged>1967-08-13</problem:timeChanged>
						<problem:reason>String</problem:reason>
						<problem:ackStatus>2</problem:ackStatus>
						<problem:clearStatus>2</problem:clearStatus>
						<problem:activityStatus>1</problem:activityStatus>
						<problem:impactPattterns>
							<problem:description>String</problem:description>
							<problem:extensionInfo/>
						</problem:impactPattterns>
						<problem:affectedLocations>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:affectedLocations>
						<problem:affectedResources>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:affectedResources>
						<problem:affectedServices>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:affectedServices>
						<problem:associatedTroubleTicket>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:associatedTroubleTicket>
						<problem:rootCauseResource>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:rootCauseResource>
						<problem:rootCauseService>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:rootCauseService>
						<problem:trackingRecords>
							<problem:item>
								<entity:identifier>
									<entity:scheme>1</entity:scheme>
									<entity:value>text</entity:value>
									<entity:context>text</entity:context>
									<entity:encoding>String</entity:encoding>
								</entity:identifier>
								<entity:extensionInfo/>
								<problem:description>String</problem:description>
								<problem:systemId>String</problem:systemId>
								<problem:time>1967-08-13</problem:time>
								<problem:userId>String</problem:userId>
							</problem:item>
						</problem:trackingRecords>
						<problem:underlyingProblems>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:underlyingProblems>
						<problem:parentProblems>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</problem:parentProblems>
						<serviceProblem:underlyingAlarms>
							<entity:item>
								<entity:scheme>1</entity:scheme>
								<entity:value>text</entity:value>
								<entity:context>text</entity:context>
								<entity:encoding>String</entity:encoding>
							</entity:item>
						</serviceProblem:underlyingAlarms>
					</serviceProblem:object>
			</serviceProblem:serviceProblemOCN>
		</wsnt:Message>
	</wsnt:NotificationMessage>
</wsnt:Notify>

TIP Soap Generator Mapping Rules - Part V

Web Service Notifications

Notification: generation in a service interface

Mapping Rule

Example (notification enabled service facade)

Example (a web service notification sample)