| Oracle® Communications Service Broker Online Mediation Controller Implementation Guide Release 6.0 Part Number E23527-02 |
|
|
View PDF |
| Oracle® Communications Service Broker Online Mediation Controller Implementation Guide Release 6.0 Part Number E23527-02 |
|
|
View PDF |
The Event Notification Framework provides a way for complementary applications to publish events to external Operational Support Systems (OSSs).
This chapter describes the Event Notification Framework, how to set it up and use it.
Complementary applications use the Event Notification Framework to publish events. The type of event and its timing are application-specific.
Events can be targeted to internal Service Broker components, or to external systems, such as your OSS.
Complementary applications fire events towards external system, to inform them of events that occur during application execution. For example, when a subscriber's state changes, or when a subscriber's monthly usage reaches a threshold.
Complementary applications fire events towards internal Service Broker components, to request them to perform an action. For example, request sending a text message to a subscriber using the Short Message Service (SMS), or to change the subscriber's state.
Firing events towards internal Service Broker components is necessary for optimization purposes; even though complementary applications can send requests to other Service Broker components internally, applications running on the session's setup path should optimally delegate requests, through the Event Notification Framework, to other entities which will asynchronous invoke execution of the requests, thus reducing the execution time of the complementary applications running on the session setup path.
When targeting events at internal Service Broker components you need to run a built-in Event Processor. See "About the Event Processor" for more information.
When targeting events to external systems, such as your OSS, you use an asynchronous web services Event Notification API to consume these events in your system. See "Using the Event Notification API" for more information.
You can target events at only one destination, that is either an external OSS application, or the Event Processor.
If you target events at an external OSS application, then you have to filter events published by built-in complementary applications and forward them to the Event Processor. Otherwise, you will harm the functionality of the built-in complementary applications. Forwarding events to the Event Processor is necessary only if you deploy one or more of the built-in complementary applications. The exact events that you need to filter and forward to the Event Processor depends on built-in application that you deploy. The documentation of each of the applications includes a section listing the events that the application fires.
Figure 6-1 shows how you can either target events at the internal Event Processor, or at external OSS application, in which case your OSS application should filter built-in application events and forward them to the Event Processor.
The Event Notification API is a SOAP-based API, in which Service Broker has to role of a SOAP client, and the application consuming the events acts as a SOAP server.
The methods and data types of the API are described using WSDL and XSD files. See "Using the Event Notification API" for more information.
The Event Notification Framework includes a built-in Event Processor that you use to handle events fired by built-in complementary applications. The Event Processor implements default handling for those events, that normally involves further activation of Service Broker components. For example, when receiving an event from the Threshold Notification application, the Event Processor triggers SMS sending to the subscriber.
The Event Processor can be extended by Oracle's consulting, to handle additional online events.
The Service Broker starts the Event Processor by default. The Event Processor itself does not require any specific configuration.
Using the Event Processor is optional. If you are not using the Event Processor, you can stop its execution by stopping its bundles. See "Stopping the Event Processor" for more information.
Complementary applications use their SAL API to fire events. Events are thereby published through the application's IM-ASF-SAL module.
Figure 6-2 shows how events path through the OE to IM-WS, which converts the event to a SOAP message, and send it out through the Web Service SSU. The Web Services SSU target events at either the Event Processor or an external OSS application. In either case, you configure the internal Service Broker Event Processor to receive incoming events.
Figure 6-2 also shows the Service Broker components required to set up the Event Notification Framework.
This section assumes that you have already deployed and configured the complementary application that publishes events and its related IM-ASF-SAL module.
To set up the Event Notification Framework:
In the Web Services SSU, configure Service Broker as web services client. See the discussion about SOAP client parameters in "Configuring SOAP Web Services Access" in Oracle Communications Signaling Domain Configuration Guide.
In the Web Services SSU, configure the target consuming events. See "Configuring Target Event Consumers".
Deploy and configure an IM-WS module. See "Deploying and Configuring IM-WS".
Route events to IM-WS. See "Routing Events to IM-WS".
Enable HTTP network access by opening an HTTP listening port. See "Enabling HTTP Network Access".
Route incoming SOAP events to the Event Processor. See "Routing Incoming Events to the Event Processor".
In the Web Services SSU, configure event consumers, as described in "Configuring Routing Rules for Outgoing Web Services Messages" in Oracle Communications Service Broker Signaling Domain Configuration Guide.
You can define two or more consumers having a different URL, that share the same alias, thereby adding a level of redundancy, treating all consumers as one logical destination, and balancing the load among consumers.
In the Administration Console:
In the navigation tree, expand the OCSB node.
Expand the Signaling Tier node.
Expand the SSU Web Services node.
Select the General node.
In the SSU WS tab, select the Outgoing Routing Rules tab.
Click the New button. The New dialog box appears.
In the Name field, enter a name for the target event consumer.
In the Alias field, enter an alias for the target event consumer.
If you target events at the Event Processor, enter sbeventprocess. Otherwise, enter an alias that represents the external OSS application that you are targeting. For example: esb.
In the Web Service URI, enter the Web URI of the target event consumer:
If you target events at the Event Processor, enter:
http://ip:port/soap/Events
Where:
ip: the address of the Signaling Servers in the Signaling Domain where the Web Services SSU is running. This should be the address of the Signaling Server or server cluster in your deployment.
port: the Signaling Servers' web services port.
Otherwise, enter the URI of the external OSS application that you are targeting, that is a web services server, in the format:
http://address:port/web-service-name.
For example, http://telmobil.esb.org:80/eventnotification.
Fill up the remaining fields as described in "Configuring Routing Rules for Outgoing Web Services Messages" in Oracle Communications Service Broker Signaling Domain Configuration Guide.
Click the OK button.
Deploy the IM-WS module as described in "Managing Interworking Modules" in Oracle Communications Service Broker Processing Domain Configuration Guide.
In the Administration Console:
In the navigation tree, expand the OCSB node.
Expand the Processing Tier node, and then the Interworking Modules node.
Click on IM Management.
In the IM Management tab, click New.
From the Type list, select IMWS.
In the Name field, enter a module instance name. For example, imws_instance.
Click the OK button.
Click the Commit button.
Configure the IM-WS module as described in "Configuring the IM-WS" in Oracle Communications Service Broker Processing Domain Configuration Guide.
Specifically, in the Web Service tab, set the following fields as described:
In the Web Service Alias field, enter the alias of the target event consumer that you configured in the Web Services SSU in step 2.
From the Web Service Type list box, select SOAP.
In the Web Service Body Type, enter eventnotification.
Create an appropriate orchestration logic that routes events arriving from IM-ASF-SAL towards IM-WS. Use the Orchestration Studio to create the orchestration logic. See Oracle Communications Service Broker Orchestration Studio User's Guide.
Specifically, you need to set a condition that identify SAL messages the Method set to MESSAGE and the To header containing the string events_service. For example:
To: sip:postEventRequest@events_service
You enable HTTP network access to let incoming events reach the Event Processor.
To configure HTTP connectivity for the incoming events:
In the navigation tree, expand OCSB.
Expand the Signaling Tier node.
Expand the SSU Web Services node.
Select the General node.
Select the HTTP tab.
In the Server subtab, select the Network Access subtab.
Click New.
In the dialog box, set the properties for the HTTP listener as follows:
Server Address: The local IP address or host name to which the port is bound. This should be the address of the Signaling Server or server cluster in your deployment.
Server Port: An available listening port on Service Broker serving API client requests, such as 8989. This is the port number on which the Signaling Servers will listen for incoming HTTP requests to the Event Processor.
Protocol: The protocol used by incoming events. Choose HTTPS for secure HTTP or HTTP for unsecured HTTP. Oracle recommends using HTTPS for production deployments.
SSL Client Auth: Whether SSL client certificate authentication is required for the connection. Enter false to disable SSL client certificate authentication, or true to require it. Enter true only if using HTTPS for the Protocol, in which case you will also need to set the key store and trust store identifiers.
Keystore Id: The key you used when loading the keystore in the Credential Store. Use only with HTTPS. If you are using HTTP, this field can be left blank. If you have not already, load the keystore associated with the ID into the credential store. See Oracle Communications Service Broker Administrator's Guide for more information about the credential store.
Truststore Id: The key you used when loading the trust store into the Credential Store. Use only with HTTPS. If using HTTP, this field can be left blank. See Service Broker Administration Guide for more information about the credential store.
Target: The Signaling Server to which this configuration applies. Leave blank to apply the configuration to all Signaling Servers in the deployment. Specify a Signaling Server name only if you want custom settings for individual Signaling Servers.
To route incoming events to the Event Processor, in the Web Services SSU, create a new incoming routing rule. See the discussion about incoming routing rules in "Configuring the Web Services SSU" in Oracle Communications Service Broker Signaling Domain Configuration Guide.
Specifically, in the new rule, set the following fields as described:
In the Service Name field, enter oosEventService.
In the Alias field, enter ssu:ocsb/outofsession.
To stop the Event Processor:
In the Administration Console, in the navigation tree, expand OCSB.
Expand Domain Management
Select Packages
In the Filter field, enter axia.oos. The Event Processor bundles will be listed:
com.convergin.wcs.axia.oos
com.convergin.wcs.axia.oos.ext
com.convergin.wcs.axia.oos.ooshash
Select a bundle that you want to stop and click the Stop button.
The event notification API is a SOAP-based API that you use to consume events, and run your specific business logic in the occurrence of these events.
The event notification API includes a single operation for receiving a notification. In general, any kind of event, triggered by any complementary application, is submitted through this API.
For most deployments, the primary consumer of the API notifications will be the customer's ESB (for example, Oracle Enterprise Service Bus), filtering the various notifications and distributing them to other OSS modules, based on the type of the event published. However, any other SOAP server that you implement can consume events.
To consume events, you develop a Web service with the WSDL files describing the event notification interface, and deploy the Web service on your SOAP server.
The interface of the Event Notification API and its data types are described in the following files:
events_service.wsdl
events_interface.wsdl
general.xsd
events.xsd
You obtain the files from the Signaling Server. To navigate to the WSDL, go to the following address:
http://host:port/soap/events
Where host is the host name or IP address and port is the server port number you specified as the server address. See "Enabling HTTP Network Access".
If the WSDL is accessible, you can start developing your API server application. Many Integrated Development Environments (IDEs) can generate client code you can use as a starting point for your application by importing the WSDL into the IDE.
The rest of this chapter is a reference of the event notification API, describing the operation of the API. It lists the parameters accepted and returned by the operation. It provides examples of HTTP requests and responses for the operation.
Note:
In the request and response message examples in this section, line breaks and spaces have been added to the data in the body of the message to improve readability.Notifies of the occurrence of an event.
The event can be of any kind. Its characteristic is defined by two fields: the event type and event category. The values of the event type and event category are not limited to a predefined set of values, and are extensible. The values depend on the complementary application initiating the event notification. Each application defines its own set of event types and categories. The events provided by each application is listed in the documentation of each application.
Request body parameters are:
externalCorrelationID: (xs:string) Optional. An event identifier, that you can use to correlate to the event.
senderIdentifier: (xs:string) Optional. The identifier of the complementary application submitting the event.
subscriberID: (SubscriberID) Optional. The identifier of the subscriber that owns the session for which the application sending the event was invoked. SubscriberID comprises:
code: (xs:int) The type of the subscriber identifier value. Possible values are:
0: Mobile Subscriber ISDN Number (MSISDN) or Directory Number (DN)
1: Mobile Identification Number (MIN) or International Mobile Subscriber Identity (IMSI)
2: SIP URI
value: (xs:string) The subscriber identifier.
type: (xs:string) The event type. Can be any number of characters, including any combination of letters, word characters and spaces.
category: (xs:string) The event category. Helps dividing the different types of events into sets of related events. A group of related events is assigned with the same category.
For example, events categorized as internal, are events consumed by internal Service Broker components and submitted by complementary applications to implement built in Service Broker features.
Complementary application developers can define categories as they need.
Can be any number of characters, including any combination of letters, word characters and spaces.
description: (xs:string) Optional. A free text description of the event. Can be any number of characters, including any combination of letters, word characters and spaces.
additionalParam: (NameValue) Optional. A recursive structure containing event specific parameters. Each parameter is a pair of:
code: (xs:string) A unique parameter identifier. Can be any number of characters, including any combination of letters, word characters and spaces.
A choice of:
value: (xs:string) The parameter value. Can be any number of characters, including any combination of letters, word characters and spaces.
nameValue (NameValue) more event specific parameters, related to each other, that you want to assemble in one set of parameters.
Response body parameters are:
result: (GenericOutput). The result of the operation. A data structure containing the following parameters:
fault: (Fault): Optional. A data structure containing the following:
faultcode: (xs:QName). A code identifying the fault.
faultstring: (xs:string). A human readable explanation of the fault.
faultactor: (xs:anyURI) Optional. Information about who caused the fault to happen.
detail (detail) Optional. Holds event specific error information. A data structure containing a sequence of xs:any and then xs:anyattribute
Built-in complementary applications ignore this parameter.
externalId (string). The event identifier. This must always be equal to the externalCorrelationID parameter in the request body.
additionalInformation (NameValue) Optional. A recursive structure containing event specific parameters. See the description of the additionalParam parameter, in the request body. The list of parameters depends on the specific event.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:even="http://xmlns.oracle.com/axia/events"
xmlns:gen="http://xmlns.oracle.com/ocsb/core/general">
<soapenv:Header/>
<soapenv:Body>
<even:postEventRequestParams>
<even:externalCorrelationID>71b42285</even:externalCorrelationID>
<even:senderID>FirstCallApplication</even:senderID>
<even:subscriberID>
<gen:code>0</gen:code>
<gen:value>+14081154970</gen:value>
</even:subscriberID>
<even:type>FirstCall</even:type>
<even:category>Charging</even:category>
even:description>account activation complete</even:description>
</even:postEventRequestParams>
</soapenv:Body>
</soapenv:Envelope>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<postEventResponseParams xmlns="http://xmlns.oracle.com/axia/events
xmlns:ns2="http://xmlns.oracle.com/ocsb/core/general">
<even:externalCorrelationID>71b42285</even:externalCorrelationID>
</postEventResponseParams>
</S:Body>
</S:Envelope>
|
 Copyright © 2010, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|