Handling Events

Eventing support is provided using the WS-Eventing web services standard. When a specific event is triggered from a data service request or response, a notification is sent to the subscribers listening to those events. For a data service, the event-trigger sections define the criteria for the event to be triggered, and also the destination topic the event notifications will be sent to. An event-trigger contains the subscriptions representing the subscribers interested in receiving the notifications sent to a given topic. Effectively, if a certain data service event-trigger is activated, it's respective subscribers will be notified.

Follow the instructions below to create an event-trigger for your data service.

1. Log on to the product's management console and select   "Data Service -> Create" under the "Main" menu.

2. The Create Data Service page appears. Fill in the fields and click Next . The Data Service name is mandatory.

3. The Data Sources page appears. Click on the Add New Data Source link to add your Data Source details.

4. After saving, the added data source page appears.  To proceed, click Next .

5. The Queries page appears. Add in your query details.

An event-trigger can be created in the Events section of the Add/Edit Query window. Click the Manage Events link.

6. The Add Events window opens.

The following fields are given to the user to define an event-trigger.

• Event Id: The id used to identify the event-trigger, used in data services queries.
• Xpath: Represents an XPath expression that will be run against the XML message that is being presented, i.e. request/response message. When this evaluation returns "true", it will trigger the event.
• Target Topic: The topic, to which the event notifications will be published.
• Event Sink URL (Subscriptions): A subscription can be any WS-Eventing complient endpoint. For example, an SMTP transport can be used to send a message to a mail inbox, where an email address is given as the subscription. Here many subscriptions can be defined for the given topic.

7. Once done, click Save . To return to the query page, click the Main Configuration button.

You have added an event-trigger to your data service.

How to Execute an Event-Trigger

An event-trigger can be set as an input or an ouput event trigger in a data service query. Let's look at the use of the two approaches.

input-event-trigger

When an input-event-trigger is applied to a query, the event-trigger will be evaluated when the parameters are received to the query. An event-trigger executs an XPath expression against an XML element. This XML element is built from the input parameters which are simply represented by the element of the parameters wrapped by an element with the name of the query.

For example, consider the following query:

<query id="incrementEmployeeSalaryQuery" useConfig="default">
   <sql>update Employees set salary=salary+? where employeeNumber=?</sql>
   <param name="increment" paramType="SCALAR" sqlType="DOUBLE" type="IN" ordinal="1" />
   <param name="employeeNumber" paramType="SCALAR" sqlType="INTEGER" type="IN" ordinal="2" />
</query>

<incrementEmployeeSalaryQuery>
   <increment>value1</increment>
   <employeeNumber>value2</employeeNumber>
</incrementEmployeeSalaryQuery>

output-event-trigger

In this case, the event-trigger is evaluated when a specific query is returning its result. There will not be any specific creation of an XML element like in the input-event-trigger, that is used with the XPath expression. But the full result XML is used to evaluate it. The result will be namespace-qualified. Therefore, the XPath expressions must be written accordingly.

Contents of Event Notification

In the event notification messages, additional information about the event is added to the SOAP Envelope/Body element. The following section illustrates this.

<data-services-event>
    <service-name>$SERVICE_NAME</service-name>
    <query-id>$QUERY_ID</query-id>
    <time>$TIME</time>
    <content>
      $CONTENT
    </content>
</data-services-event>

• $SERVICE_NAME : Name of the service from which the event originated.
• $QUERY_ID : The id of the query which triggered the event.
• $TIME : The date/time when the event occured.
• $CONTENT : In the case of an input-event-trigger, this will be the XML element generated. It is used when executing the XPath expression. It contains the input parameters wrapped with the query id value. In the case of an output-event-trigger, it contains the full result XML.

For a demonstration on the usage of eventing, refer to the Eventing Sample in the Data Services Server 3.0.0 Documentation..