Handling Events

Eventing support is provided by WS-Eventing Web services standard. When a data service request or response triggers an event, the subscribers listening to those events receive notifications. For a data service, the event-trigger sections define the criteria to trigger the event, and also the destination topic the event notifications are 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.

Click the Manage Events link to open the Add Events window.

The fields of the window are described below:

• Event Id: The id used to identify the event-trigger used in data services queries.
• Xpath: Represents an XPath expression that is run against the XML message presented. That is, request/response message. When this evaluation returns true, it triggers the event.
• Target Topic: The topic to which the event notifications are published.
• Event Sink URL (Subscriptions): A subscription can be any WS-Eventing complaint endpoint. For example, you can use an SMTP transport 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.

Executing an event trigger

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

Input event trigger

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

For example, take 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>

 Assuming that the values of increment and employeeNumber are value1 and value2 respectively, the XML element to be evaluated with the XPath expression is as follows. Also note that this XML element doesn't not have any namespaces associated with it.

<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 isn't a specific creation of an XML element that is used with the XPath expression like in the input event trigger. But the full result XML is used to evaluate it. The result will be namespace qualified. Therefore, you must write the XPath expressions 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 code demonstrates 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 that triggered the event
• $TIME : The date/time when the event occurred
• $CONTENT : The XML element generated in case of an input event trigger. 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 sample demonstration on how to use eventing, see Eventing Sample.