Understanding Event Streams

Events are the lifeline of WSO2 CEP/DAS. They not only process data as events, but also interact with external systems using events. Event is a unit of data, and an event stream is a sequence of events of a particular type. The type of events can be defined as an event stream definition. The following sections explain how to work with events in WSO2 CEP.

Event streams

You can manage event streams through event stream definitions.

Event stream definition

Definitions of the event streams are stored in the filesystem as deployable artifacts in the <PRODUCT _HOME>/repository/deployment/server/eventstreams/ directory as .json files. These are hot deployable files and can be added/removed when the server is up and running. A sample event stream definition is as follows.

{
  "streamId": "org.wso2.test:1.0.0",
  "name": "org.wso2.test",
  "version": "1.0.0",
  "nickName": "TestStream",
  "description": "Test Stream",
  "metaData": [
    {
      "name": "ip",
      "type": "STRING"
    }
  ],
  "correlationData": [
    {
      "name": "id",
      "type": "LONG"
    }
  ],
  "payloadData": [
    {
      "name": "testMessage",
      "type": "STRING"
    }
  ]
}

The properties of the above event stream definition are described below.

Property	Description
Event Stream Name	Name of the event stream.
Event Stream Version	Version of the event stream. (Default value is 1.0.0.)
Event Stream Description	Description of the events stream. (This is optional.)
Event Stream Nick-Name	Nick-names of an event streams separated by commas. (This is optional.)
Stream Attributes	Stream Attributes contains the data of the event. These are divided into three logical separations to give more usability and maintenance to the user. It is not mandatory to have attributes in all three sections, but there should be at least one section with at least one attribute defined. Also attribute names should be unique within each section. Meta Data: Contains the meta information of the events. (Referred to as `meta_<attribute name>`.) Correlation Data: Contains the correlation information of the events. (Referred to as `correlation_<attribute name>`.). Payload Data: Contains the actual data that the event intends to have. (Referred to as `<attribute name>`.) It is recommended to have logistic separation but the internal system does not differentiate or give privilege based on above separations. Also Please note if you edit and add another attribute to existing stream definition, other artifacts which are associated with the stream will be inactive. So that it is recommended to create a new definition and a version with the additional attribute. For example consider following attributes which exist in a single event. event_timestamp, request_IP_address, correlation_Id, price, symbol with there corresponding data types. We can logically separate the above attributes as following. Meta Data :- event_timestamp, request_IP_address (These describes the events itself) Correlation Data :- correlation_Id (These correlates events with other events from other streams. These will be useful when you perform a join operations on a stream) Payload Data :- price,symbol( These are actual information/details of the event)

Adding an event stream

You can create an event stream by creating a new event stream definition using the design view or the source view.

Using the design view

Follow the steps below to add an event stream using the design view.

Log in to the management console, and click Main.
Click Event Streams in the Event Processor menu, and then click Add Event Stream.
Enter details of the stream definition that you want to create as shown in the below example.
Click Add Event Stream, to create the Event Stream in the system. When you click OK in the pop-up message on successful addition of the stream definition, you view it in the Available Event Streams list as shown below.

Using the source view

Follow the steps below to add an event stream using the source view.

Log in to the management console, and click Main .
Click Event Streams in the Event Processor menu, and then click Add Event Stream.
Click switch to source view.

Click switch to design view to add the event stream using the design view.
Enter details of the stream definition that you want to create as shown in the below example.
Click Add Event Stream , to create the Event Stream in the system. Y ou view the new event stream in the Available Event Streams list as shown below.

Deleting an event stream

Follow the steps below to delete an event stream by deleting the corresponding event stream definition.

Log in to the management console, and click Main .
Click Event Streams in the Event Processor menu. You view the Available Event Streams list.
Click the Delete button of the corresponding event stream to delete it.

Editing an event stream

Follow the steps below to edit an event stream by editing the corresponding event stream definition.

Log in to the management console, and click Main.
Click Event Streams in the Event Processor menu. You view the Available Event Streams list.
Click the Edit button of the corresponding event stream to edit it.

Click the switch to source view link to edit an event stream using the source view.

Creating sample events

Follow the steps below to create sample events for a defined event stream.

Log in to the management console, and click Main.
Click Event Streams in the Event Processor menu. You view the Available Event Streams list.
Click the Event Stream Id of the corresponding event stream for which you want to create the sample event.
Select the event format type (i.e. xml, json, or text) from the drop down list, which you want to create the sample event in.
You view details of the event stream as shown below.
Click Generate Event to create the sample event.

Event formats

WSO2 CEP/DAS facilitates the following default and custom event formats.

Default event formats

By default, WSO2 CEP/DAS represents an event as a WSO2Event object. Furthermore, WSO2 CEP/DAS supports events in XML, JSON, Text and Map formats. The default event formats of the XML, JSON, Text and Map representations for the following sample event stream definition are as follows.

Sample event stream definition

{
  "streamId": "org.wso2.test:1.0.0",
  "name": "org.wso2.test",
  "version": "1.0.0",
  "nickName": "TestStream",
  "description": "Test Stream",
  "metaData": [
    {
      "name": "ip",
      "type": "STRING"
    }
  ],
  "correlationData": [
    {
      "name": "id",
      "type": "LONG"
    }
  ],
  "payloadData": [
    {
      "name": "testMessage",
      "type": "STRING"
    }
  ]
}

Custom event formats

If you receive and publish events with a different format than the default format, you need to provide appropriate mappings for the system to interpret the events.

Custom formats for receiving events

For information on the custom event receiver mappings, see Input Mapping Types.

Custom formats for publishing events

For information on the custom event publisher mappings, see Output Mapping Types.

Event Flow

Event flow visualizes the stream flow in WSO2 CEP/DAS to easily navigate to different WSO2 CEP/DAS components.

Follow the steps below to view the event flow.

Log in to the management console.
Click Main, and then click Event Flow in the Event Processor menu.

This demonstrates how all the active event receivers, event streams, event publishers, and execution plans are connected.