Creating a Standalone Execution Plan

WSO2 CEP uses Execution Plans to store event processing logic. An Execution Plan is bound to an instance of the Siddhi complex event processing runtime, which is responsible for the actual processing of the events. The event processor allows users to configure multiple Execution Plans where by providing multiple isolated event processing environments per Execution Plan. A typical Execution Plan consists of a set of queries and related input and output Event Streams.

WSO2 CEP 3.x.x versions and above, only support Siddhi runtime and they no longer support Esper / Drools fusion.

Writing an execution plan

To write an execution plan, start the CEP, log in to its management console, go to Main --> Manage --> Event Processor --> Execution Plans and click Add Execution Plan.

You will get an execution plan template as shown below.

You can edit this template to create a new execution plan. Follow the steps below to edit the template and create a new execution plan.

The execution plan editor supports auto completion.

To view the suggestions made by the editor, press control+space keys together.

The suggestions contain two sets.

Siddhi keywords, in alphabetical order
All the other words which are already inserted into the editor. For example, stream names which are defined in step 2 will be suggested when writing the queries in step 3. These will appear in alphabetical order after the keyword list.

In addition to the above, press shift+2 keys together to view suggestions on annotations.

Supported annotations

The annotations supported for execution plans are as follows.

Annotation	Description	Example
`@plan:name (<name for execution plan>)`	The name of the execution plan.	`@Plan:name('ExecutionPlan')`
`@plan:description (<description about execution plan>)`	This provides a description about the execution plan. Details such as the business requirement of the execution plan can be mentioned here.	`@Plan:description('This is the description for my NewExecutionPlan')`
`@plan:async (bufferSize=<event queue size>)`	WSO2 CEP has a disruptor based implementation to handle streams that are disabled by default. This annotation can be used to enable the disruptor at execution plan level that affects all the streams in the execution plan. The buffer size is an optional parameter. The default buffer size is `1024`.	`@plan:async(bufferSize=2)`
`@async(bufferSize=<event queue size>)`	Using this you can enable the disruptor only for a specific event stream. The event flow of the specified stream passes through the disruptor when enabled.	`@async(bufferSize='2')` `define stream sensor_stream (meta_sensorId int, humidity float, sensorValue double);`
`@import (<CEP stream definition>)`	This is used to import a CEP event stream definition and map it to a Siddhi stream definition. For more information about event stream definitions, see Understanding Event Streams.	`@Import('org.wso2.event.sensor.stream:1.0.0')` `define stream sensor_stream (meta_sensorId int, humidity float, sensorValue double);`
`@export (<CEP stream definition>)`	This is used to export a Siddhi event stream definition and map it to a CEP event stream definition.	`@Export('org.wso2.sensor.value.projected.stream:1.0.0')` `define stream sensor_value_projected_stream (meta_sensorId int, humidity float, value double);`

Step 1. Add execution plan info

Add Execution Plan Name:

Give a meaningful name to the execution plan by replacing 'ExecutionPlan' in @Plan:name('ExecutionPlan') with the new name.

For example, if the new name should be 'NewExecutionPlan', then replace @Plan:name('ExecutionPlan') with @Plan:name('NewExecutionPlan').

Description:

This is the description of the execution plan. Giving a description is optional.

To give a description to the execution plan,

- - Uncomment the line "-- @Plan:description('ExecutionPlan')".
  - Replace 'ExecutionPlan' with the description

For example, @Plan:description('This is the description for my NewExecutionPlan')

Step 2. Import Streams

An execution plan processes one or more streams. Therefore it is mandatory to import streams into an execution plan.

Importing a stream means mapping an available Event Stream to another internal stream. This internal stream is then used in query expressions, which will be written in step 3: Add query expressions. In fact, this internal stream is meant to be used by the Siddhi runtime.

To import a stream:

In the Import Stream field, select an existing stream from the list.
In the As field, enter a a meaningful name by which this stream should be referred.
Select the Include Arbitrary check box if you want to append arbitrary configurations to the stream definition when performing the import.

This imports an available event stream as a new stream.

The form inputs are described as follows:

- Import Stream: The name of the CEP Event Stream that should feed its events to the execution plan.
- As: The name to be used when feeding the stream to the Siddhi engine. This can contain only alphanumeric characters and underscore (_).
- Include Arbitrary: If this check box is selected for an import stream, the arbitrary.data='true'setting is added to the import stream definition in the execution plan. In addition, an attribute named arbitraryDataMap Object is added to the attribute list of the input stream definition in the execution plan. The keys and values on this attribute of the object type can be accessed via the map extension in Siddhi. This allows arbitrary data of the import stream to be copied to the export stream. Arbitrary data are events that are received without the meta_ or a correlation_ prefix, and at the same time do not match the payload attributes defined in an event stream.

Step 3. Add query expressions

Contains the event processing logic written in Siddhi query language. When defining more than one query, each query should end with a semi colon.

Step 4. Export streams

Defines the mappings between the exported (output) stream of the Siddhi runtime to one of the available Event Streams (defined inside query expressions). The parameters are as follows:

Value Of: The name of the stream exposed by the Siddhi runtime. This can contain only alphanumeric characters and underscore (_).
StreamId: The CEP Event Stream's ID to which the output events are sent from the execution plan.
Include Arbitrary: If this check box is selected, the arbitrary.data='true'setting is added to the export stream definition in the execution plan. This allows you to publish arbitrary data from that stream.

It is not mandatory to define export streams in an execution plan.
Siddhi Event tables cannot be exposed as streams. Event tables are only considered as streams within Siddhi.

Step 5. Add execution plan

Before adding the execution plan to the Siddhi runtime, it can be validated by clicking Validate Query Expressions.

Finally click the Add Execution Plan button to deploy the Execution plan.

Once an execution plan is created as saved, its configuration in WSO2 Siddhi Query Language format is saved in the <CEP_HOME>/repository/deployment/server/executionplans directory.

Editing a deployed execution plan

After an execution plan is successfully created, you can change it and redeploy it as follows.
Go to Main --> Manage --> Event Processor --> Execution Plans and select the execution plan needs to be edited by clicking on Edit button link associated with it. You can also click other associated links to delete it, enable/disable statistics or enable/disable tracing.
Edit the execution plan as required, and click Update.
Alternatively, you can write your execution plan in a text file and save it with the extension '.siddhiql' (which stands for Siddhi Query Language) and drop it in the deployment directory <PRODUCT_HOME>/repository/deployment/server/executionplans. Since hot deployment is supported you can simply add/remove Execution Plan files to deploy/undeploy Execution Plans from the server.

Deleting a deployed execution plan

Follow the procedure below to delete an execution plan.

Start the CEP, and log in to its management console. Click Main and then click Execution Plans to open the Available Execution Plans page. The available execution plans are listed in this page.
Click Delete in the row of the execution plan you want to delete. Click Yes in the message which appears to confirm whether the execution plan should be deleted.