Configuring Event Receivers

Events are received by WSO2 CEP/DAS server using event receivers, which manage the event retrieval process. Event receiver configurations are stored in the file system as deployable artifacts. WSO2 CEP/DAS receives events via multiple transports in JSON, XML, Map, Text, and WSO2Event formats, and converts them into streams of canonical WSO2Events to be processed by the server. 

Event receiver types

WSO2 CEP/DAS has the capability of receiving events from event receivers via various transport protocols. Following are the event receivers that come with WSO2 CEP/DAS by default. You can write extensions to support other transport.

In addition to the above, the SQS extension allows you to receive events via SQS.

For instructions to download and install an extension, see Downloading and Installing Extensions from the Store.

Event receiver configuration

An event receiver configuration has four main sections as shown in the example below. 

Event receiver configurations are stored in the file system as hot deployable artifacts in the <PRODUCT _HOME>/repository/deployment/server/eventreceivers/  directory as shown in the example below. 

<eventReceiver name="WSO2EventEventReceiver" statistics="disable"
    trace="disable" xmlns="http://wso2.org/carbon/eventreceiver">
    <from eventAdapterType="wso2event">
        <property name="events.duplicated.in.cluster">false</property>
    </from>
    <mapping customMapping="disable" type="wso2event"/>
    <to streamName="testEventStream" version="1.0.0"/>
</eventReceiver>

The above sections of an event receiver configuration are described below.

Creating event receivers

You can create event receivers either using the management console or using a configuration file as explained below.

Creating receivers using the management console 

Follow the steps below to create an event receiver using the management console of WOS2 CEP/DAS.

1. Log in to the management console, and click Main.
2. Click Receivers in the Event menu, and then click Add Event Receiver.

3. Enter a name for Event Receiver Name. (Do not use spaces between the words in the name of the event receiver.)

4. Select the input transport from which you want to receive events for the  Input Event Adapter Type, and enter the Adapter Properties accordingly. For instructions on the adapter properties of input transport types, see Event Receiver Types.

5. Select the Event Stream, to which you want to map the received events.

6. Select the Message Format which you want to apply on the receiving events. WSO2 servers allow users to configure events in XML, JSON, Text, Map, and WSO2Event event formats.

7. Click Advanced to define custom input mappings based on the message format you selected, if you are sending events that do not adhere to the default event formats. For more information on custom input mapping types, see Input Mapping Types.
8. Click Add Event Receiver, to create the event receiver in the system. When you click  OK  in the pop-up message on successful addition of the event receiver, you view it in the  Available Event Receivers  list as shown below.
   

Creating receivers using a configuration file

Follow the steps below to create an event receiver using a configuration file.

1. Create an XML file with the following event receiver configurations. An event receiver implementation must start with  <eventReceiver>  as the root element.

   In the following configuration, specify the respective adapter properties based on the transport type of the receiver within the <from> element. For the respective adapter properties of the event receiver configuration based on the transport type, see Event Receiver Types .

   <eventReceiver name="EVENT-RECEIVER-NAME" statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventreceiver">
       <from eventAdapterType="EVENT-ADAPTER-TYPE">
          .................................
       </from>
       <mapping customMapping="disable" type="xml"/>
       <to streamName="Test Stream" version="1.0.0"/>
   </eventReceiver>

   The properties of the above configuration are described below.

   Adapter property	Description
   name	Name of the event receiver
   statistics	Whether monitoring event statistics is enabled for the receiver
   trace	Whether tracing events is enabled for the receiver
   xmlns	XML namespace for event receivers
   eventAdapterType	Type of the event adapter.
   customMapping	Whether a custom mapping is enabled on the receiver.
   type	Type of the enabled custom mapping.
   streamName	Name of the event stream to which the receiver is mapped.

2.   Add the XML file to the <PRODUCT_HOME>/repository/deployment/server/eventreceivers/ directory. Since hot deployment is supported in the product, you can simply add/remove event receiver configuration files to deploy/undeploy event receivers to/from the server.

After a receiver is successfully added, it gets added to the list of receivers displayed under  Event   in the  Main   menu of the product's management console. Click Edit    to change its configuration and redeploy it. This opens an XML-based editor allowing you to edit the event receiverr configurations from the UI. Do your modifications and click  Update . You can also delete it, enable/disable statistics or enable/disable tracing on it using the provided options in the UI as described below.

Enabling statistics for event receivers

Follow the steps below to enable monitoring statistics of events received by an existing event receiver.

1. Log in to the management console, and click Main.
2. Click Receivers in the Event menu. You view the Available Event Receivers list.
3. Click the Enable Statistics button of the corresponding event receiver to enable monitoring event statistics for it.

Enabling tracing for event receivers

Follow the steps below to enable tracing on events received by an existing event receiver.

1. Log in to the management console, and click Main.
2. Click Receivers in the Event menu. You view the Available Event Receivers list.
3. Click the Enable Tracing button of the corresponding event receiver to enable event tracing for it.
   

Deleting event receivers

Follow the steps below to delete an existing event receiver.

1. Log in to the management console, and click Main.
2. Click Receivers in the Event menu. You view the Available Event Receivers list.
3. Click the  Delete button of the corresponding event receiver to delete it.

Editing event receivers

Follow the steps below to edit an existing event receiver.

1. Log in to the management console, and click Main.
2. Click Receivers in the Event menu. You view the Available Event Receivers list.
3. Click the  Edit button of the corresponding event receiver to edit it. This opens Edit Event Receiver Configurations XML editor.  
4. After editing, click Update, to save the configuration, or click Reset to reset the configuration to its original state.