Configuring a Template for Template Manager

This section illustrates how to configure templates for WSO2 CEP template manager. We will be utilizing a single use case throughout this documentation based on which we will provide sample configurations.

Use case

In this use case we will develop a template representing a scenario where you can monitor a configurable sensor type (temperature, pressure, etc) throughout a configurable time period and calculate the number of sensor data items received, the number of sensors engaged and the sum, average, maximum and minimum values for the data-set. After configuring the template manager, you can generate artifacts for different scenarios using the user interface of template manager.

Step 1: Create template

To create the template, enter the following configuration in an XML file, and save this file in the <CEP_HOME>/repository/conf/template-manager/domain-template directory as Sensor-Analytics.xml.

<domain name="SensorDataAnalysis">
   <description>Domain for sensor data analysis</description>
   <scenarios>
      <scenario type="SensorAnalytics">
         <description>Configure a sensor analytics scenario to display statistics for a given stream of your choice</description>
         <templates>
            <!--Note: These will be deployed in the order they appear here-->
            <template type="eventstream">
               <!--A Stream Definition Template here-->
            </template>
            <template type="realtime">
               <!--An Execution Plan Template here-->
            </template>
            <template type="eventreceiver">
               <!--An Event Receiver Template here-->
            </template>
            <template type="eventpublisher">
               <!--An Event Publisher Template here-->
            </template>
            <template type="gadget">
               <!--A Gadget Template  here-->
            </template>
            <template type="dashboard">
               <!--A Dashboard Template  here-->
            </template>
         </templates>
         <streamMappings>
            <!--Define stream mappings here-->
         </streamMappings>
         <parameters>
            <!--Define parameters here-->
         </parameters>
      </scenario>
   </scenarios>
   <commonArtifacts>
      <!--Define common artifacts here-->
   </commonArtifacts>
   <scripts>
		<!--Define JavaScript files and/or content here-->
		<script src=””/>
   </scripts>
</domain>

This is the basic template. Each section of the xml configuration is explained below. Instructions to configure each section in this template are explained in the subsequent steps. File name, domain name and scenario type attributes can have custom names based on the use-case.

Configuration Type	Purpose	Sub Element
Domain	This is a logical collection of Scenarios. One domain can be used to group related scenarios together for better organization.	`<domain name="SensorDataAnalysis">`
Scenario	A description of the scenario to be analyzed. e.g., Analyzing average and maximum temperature.	`<scenario type="SensorAnalytics">`
Template	A templated artifact.	`<template type="type">`
Event Stream	This defines the event stream definitions associated with the scenario.	`<template type="eventstream">`
Execution Plan	This defines the Siddhi execution plan based on which the events are processed.	`<template` `type="realtime">`
Gadget	This defines the gadgets required to view the information processed by the event flows created via the template in a specific format.	`<template` `type="gadget">`
Dashboard	This defines the dashboards to display the gadgets with the information processed by the event flow.	`<template` `type="dashboard">`
Stream mapping	This maps an existing input stream in your WSO2 CEP installation with the event stream defined in the template manager.	`<streamMappings>`
Parameters	This defines configurable variables. The $ sign is used to indicate configurable fields.	`<parameters>`
Common artifacts	This allows you to include artifacts that are common to all the scenarios using the templates in the template manager.	`<commonArtifacts>`
Scripts	To include java script functions that can be used as parameters.	`<scripts>`

Step 2: Add an event stream to the template

This step involves adding event stream definitions to be included in the template. For detailed information about event streams, see Understanding Event Streams.

To add required event streams for this use case, add the following configuration under the <template type="event stream"> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file you created, and save.

Event Stream Template

<template type="eventstream">
	{
       "name":"org.wso2.event.$sensorType.stream",
       "version":"1.0.0",
       "nickName":"",
       "description":"",
       "payloadData":[
          {
         "name":"sensor_id",
         "type":"STRING"
          },
          {
         "name":"sensor_value",
         "type":"DOUBLE"
          }
       ]
    }
</template>

The configuration you are providing here is a JSON representation of the event stream definition. The $ sign is used for configurable fields. The name of the event stream defined in this example is org.wso2.event.$sensorType.stream.

This step introduces the $sensorType parameter included in the event stream template given above. This is a configurable parameter that can be configured in the Template Manager UI to create different CEP event stream artifacts as required for the use case.

The following procedure is an easy approach to create the configuration for an event stream to be added to the Template Manager.

Log into the WSO2 CEP Management Console and define the required event stream. For detailed instructions, see Understanding Event Streams.
In the Available Event Streams page, click Edit for the stream you created and click switch to source view where configuration is available in the form of text.
Copy this configuration in the source view and add it to your template under the <template type="event stream"> element. Add the required configurable parameters and save.

Step 3: Configure real time analytics

This step involves adding an execution plan to the template. For more information about execution plans, see Creating a Standalone Execution Plan.

To add required event streams for this use case, add the following configuration under the <template type="realtime"> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file you created, and save.

An execution plan configuration should always be added inside a CDATA element.

Real-time Element

<template type="realtime">
<![CDATA[/* Enter a unique ExecutionPlan */
	@Plan:name('SensorAnalyticsPlan')

	/* Enter a unique description for ExecutionPlan */
	-- @Plan:description('ExecutionPlan')

	/* define streams/tables and write queries here ... */

	@Import('org.wso2.event.$sensorType.stream:1.0.0')
	define stream InputStream (sensor_id string, sensor_value double);

	@Export('org.wso2.event.$sensorType.statistics.stream:1.0.0')
	define stream OutputStream (sensor_type string, sensor_id_distinct_count long, count long, sum double, average double, max double, min double);

	from InputStream#window.time($timeInMins min)
	select '$sensorType' as sensor_type, distinctcount(sensor_id) as sensor_id_distinct_count, count() as count, sum(sensor_value) as sum, avg(sensor_value) as average, max(sensor_value) as max, min(sensor_value) as min
	insert into OutputStream;]]>
</template>

In this example, the execution plan consumes the org.wso2.event.$sensorType.stream stream and calculates values for the count, sum, avg, max and etc. attributes over a time period specified for the $timeInMins configurable parameter. The results are published to another stream named org.wso2.event.$sensorType.statistics.stream.

This step introduces the $timeInMins parameter included in the execution plan template given above. This is a configurable parameter that can be configured in the Template Manager UI to create different CEP event stream artifacts as required for the use case.

The following procedure is an easy approach to create the configuration for an execution plan to be added to the Template Manager.

Log into the WSO2 CEP Management Console and create the required execution plan. For detailed instructions to create an execution plan, see Creating a Standalone Execution Plan.
Once you have completed and validated the execution plan, copy it and paste it under the <template type="realtime"> element of your template file in the <CEP_HOME>/repository/conf/template-manager/domain-template directory.
Add the required configurable parameters and save.

Step 4: Configure an event receiver

This step involves adding an event receiver to the template. Event receivers accept events to WSO2 CEP from external sources. For more information about event receivers, see Configuring Event Receivers.

To add the event receiver configuration required for this use case, add the following configuration under the <template type="eventReceiver"> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

An event receiver configuration should always be added inside a CDATA element.

Event Receiver Element

<template type="event receiver">
<![CDATA[<eventReceiver name="$sensorType.statistics.stream.receiver"
    statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventreceiver">
    <from eventAdapterType="http">
        <property name="basicAuthEnabled">true</property>
        <property name="transports">all</property>
    </from>
    <mapping customMapping="disable" type="xml"/>
    <to streamName="org.wso2.event.$sensorType.stream" version="1.0.0"/>
</eventReceiver>]]>
</template>

In this example, an HTTP event receiver is added, and the events received are mapped to the org.wso2.event.$sensorType.stream stream.

The following procedure is an easy approach to create the configuration for an event receiver to be added to the Template Manager.

Log into the WSO2 CEP Management Console and create the required event receiver. For detailed instructions to create an event receiver, see Configuring Event Receivers - Creating event receivers.
In the Available Event Receivers page, click Edit for the event receiver you created. The source view for the event receiver configuration is displayed.
Copy the source view and paste it under the <template type="eventreceiver"> element of your template file in the <CEP_HOME>/repository/conf/template-manager/domain-template directory. Make sure you include this configuration within a CDATA block.
Add the required configurable parameters and save.

Step 5: Configure an event publisher

This step involves adding an event publisher to the template. Event publishers publish events from WSO2 CEP to external consumers. For more information about event publishers, see Configuring CEP to Create Alerts.

To add the event publisher configuration required for this use case, add the following configuration under the <template type="eventPublisher"> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

An event receiver configuration should always be added inside a CDATA element.

Event Publisher Element

<template type="event publisher">
<![CDATA[<eventPublisher name="$sensorType.statistics.stream.publisher"
     statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
   <from streamName="org.wso2.event.$sensorType.statistics.stream" version="1.0.0"/>
   <mapping customMapping="disable" type="wso2event"/>
   <to eventAdapterType="ui"/>
</eventPublisher>]]>
</template>

In this example, a UI event publisher consumes the org.wso2.event.$sensorType.statistics.stream stream, and publishes the events from this stream to an internal UI adapter so that the processed events are displayed as statistics in the gadgets created for this scenario.

The following procedure is an easy approach to create the configuration for an event publisher to be added to the Template Manager.

Log into the WSO2 CEP Management Console and create the required event publisher. For detailed instructions to create an event publisher, see Configuring CEP to Create Alerts - Creating event publishers.
In the Available Event Publishers page, click Edit for the event receiver you created. The source view for the event publisherr configuration is displayed.
Copy the source view and paste it under the <template type="eventPublisher"> element of your template file in the <CEP_HOME>/repository/conf/template-manager/domain-template directory. Make sure you include this configuration within a CDATA block.
Add the required configurable parameters and save.

Step 6: Configure a gadget

This step involves adding a gadget configuration to the template. For more information about gadgets, see /wiki/spaces/TESB/pages/32604756.

To add the gadget configuration required for this use case, add the following configuration under the <template type="gadget"> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

Gadget Element

<template type="gadget">
   <config>
      <properties>
         <property name="directoryName">$sensorType-count-chart</property>
         <property name="templateDirectory">numberchart</property>
      </properties>
      <artifacts>
         <artifact file="gadget.json"><![CDATA[{
                       "id": "$sensorType-count-chart",
                       "title": "$sensorType-count-chart",
                       "type": "gadget",
                       "thumbnail": "gadget/$sensorType-count-chart/thumbnail.png",
                       "data": {
                           "url": "gadget/$sensorType-count-chart/gadget.xml"
                       }
                   }]]></artifact>
         <artifact file="conf.json"><![CDATA[{"provider-conf" : {"streamName" : "org.wso2.event.$sensorType.statistics.stream:1.0.0", "provider-name" : "realtime"}, "chart-conf" : {"x" : "count", "title" : "Count $sensorType", "gadget-name" : "$sensorType-count-chart", "chart-name" : "number-chart"}}]]></artifact>
         <artifact file="js/core/gadget-util.js"><![CDATA[var getGadgetLocation = function(){
                   return '/portal/store/carbon.super/fs/gadget/$sensorType-count-chart';
               }]]></artifact>
      </artifacts>
   </config>
</template>

The above configuration represents a chart in which the count attribute of the org.wso2.event.$sensorType.statistics.stream stream is mapped.

The directoryName property element in the configuration specifies the name of the directory to which the gadget configurations are copied when the template is used at runtime. The templateDirectory property element is the directory from which the static gadget configurations are copied. There are many files associated with the gadget, and most of the time, you only need to template the few files that you add to the template. The other files are static. Therefore, you need to add all the static files (i.e. files that are not templates) to the templateDirectory directory and place it inside the <CEP_HOME>/repository/conf/template-manager/gadget-templates directory.

e.g., If you add a gadget template configuration in the domain template file as given above together with a directory named numberchart including all the gadget related configurations (all the non-templated files), then all the gadget related configurations (templated files as well as non-templated files) are copied to the $sensorType-count-chart directory, replacing the input values passed by the user.

Note that there are 3 artifacts added under this template type: gadget.json, conf.json and js/core/gadget-util.js. Follow the steps below to to generate this content.

Create a new gadget as required for the scenario. For detailed instructions, see /wiki/spaces/TESB/pages/32604756.
The artifacts mentioned above are located in the <CEP_HOME>/repository/deployment/server/jaggeryapps/portal/store/<Tenant_Name>/fs/gadget directory. Copy the content of the relevant files (where the file name is the same as the required gadget name) and insert them within CDATA blocks under the <template type="gadget"> element of your template file in the <CEP_HOME>/repository/conf/template-manager/domain-template directory.
Add the required configurable parameters and save.

Step 7: Configure a dashboard

This step involves adding a dashboard configuration to the template. This dashboard serves as a container for the gadgets that were added in step 6. For more information about dashboards, see Visualizing Results in the Analytics Dashboard.

To add the dashboard configuration required for this use case, add the following configuration under the <template type="dashboard"> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

Dashboard element

<template type="dashboard">
   <config>
      <properties>
         <property name="dashboardId">analytics-$sensorType-dashboard</property>
      </properties>
      <content><![CDATA[{
                    	"accessTokenUrl": "",
                    	"apiKey": "",
                    	"apiSecret": "",
                    	"banner": {
                        	"customBannerExists": false,
                        	"globalBannerExists": false
                    	},
                    	"defaultPriority": "5",
                    	"description": "",
                    	"hideAllMenuItems": false,
                    	"id": "analytics-$sensorType-dashboard",
                    	"identityServerUrl": "",
                    	"isEditorEnable": true,
                    	"isUserCustom": false,
                    	"isanon": false,
                    	"landing": "landing",
                    	"menu": [
                        	{
                            	"id": "landing",
                            	"isanon": false,
                            	"ishidden": false,
                            	"subordinates": [],
                            	"title": "Home"
                        	}
                    	],
                    	"pages": [
                        	{
                            	"content": {
                                	"anon": {},
                                	"default": {
                                    	"a": [
                                        	{
                                            	"content": {
                                                	"data": {
                                                    	"url": "fs://gadget/$sensorType-count-chart/index.xml"
                                                	},
                                                	"id": "$sensorType-count-chart",
                                                	"locale_titles": {},
                                                	"options": {
                                                    	"dataSource": {
                                                        	"options": [],
                                                        	"required": false,
                                                        	"title": "Data Source",
                                                        	"type": "STRING",
                                                        	"value": "/portal/gadgets/bar-chart/datasource/dataFile4.jag"
                                                    	},
                                                    	"updateGraph": {
                                                        	"options": [],
                                                        	"required": false,
                                                        	"title": "Update Interval (s)",
                                                        	"type": "STRING",
                                                        	"value": "No"
                                                    	}
                                                	},
                                                	"styles": {
                                                    	"borders": true,
                                                    	"title": "Count $sensorType"
                                                	},
                                                	"thumbnail": "fs://gadget/$sensorType-average-chart/gadgetIcon.png",
                                                	"title": "Count $sensorType",
                                                	"type": "gadget"
                                            	},
                                            	"id": "$sensorType-count-chart-0"
                                        	}
                                    	]
                                	}
                            	},
                            	"id": "landing",
                            	"isanon": false,
                            	"layout": {
                                	"content": {
                                    	"loggedIn": {
                                        	"blocks": [
                                            	{
                                                	"height": 3,
                                                	"id": "a",
                                                	"width": 4,
                                                	"x": 0,
                                                	"y": 0
                                            	}
                                        	]
                                    	}
                                	},
                                	"fluidLayout": false
                            	},
                            	"title": "Home"
                        	}
                    	],
                    	"permissions": {
                        	"editors": [
                            	"Internal/everyone"
                        	],
                        	"viewers": [
                            	"Internal/everyone"
                        	]
                    	},
                    	"theme": "Default Theme",
                    	"title": "Analytics $sensorType Dashboard"
                	}]]></content>
   </config>
</template>

In the above configuration, a new page is created to add the previously created gadgets. Fields such as id are provided so that the created gadgets are added to the dashboard when generating artifacts using this template.

The content of the above dashboard template can be generated by following the procedure below.

Create a sample dashboard as required for your scenario. For detailed instructions, see Visualising Results in the Analytics Dashboard - Adding a new dashboard.
The dashboard configuration is saved in the /_system/config/ues/dashboards/<Dashboard_Name> registry path. To access the registry, log into the WSO2 CEP Management Console, and click Main => Registry => Browse. For more information about the registry, see Registry.
Copy the dashboard configuration, and add it within a CDATA block under the <template type="dashboard"> element of your template file in the <CEP_HOME>/repository/conf/template-manager/domain-template directory.

Step 8: Configure stream mapping

This step involves configuring the stream mapping required for this scenario. The stream mapping maps an existing input stream in your WSO2 CEP installation with the event stream defined in the template manager.

For example, if you have a single event stream named org.wso2.event.aggregate.stream that carries all of your sensor data, you need to break it down at runtime to make use of the template you created. This is achieved via stream mapping. The stream mapping configuration given below allows you to map the org.wso2.event.aggregate.stream stream to the org.wso2.event.$sensorType.stream stream you added to this template in step 2. This mapping is done in the Template Manager UI as further explained in Using Templates.

Add the following configuration under the <streamMappings> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

<streamMappings>
   <streamMapping to="org.wso2.event.$sensorType.stream:1.0.0" />
</streamMappings>

Step 9: Configure parameters

This step involves configuring the parameters required for this scenario. Two configurable parameters named $sensorType and $timeInMins were introduced to the template in this scenario in the previous steps. In this section, the following are configured for these parameters.

Type
The name and the description to be displayed in the Template Manager UI.
The default value and the options that you can select as the value of the parameter in the Template Manager UI.

Using these parameters to differentiate scenarios in the Template Manager is explained under Using Templates.

To add parameters to the template, add the following configuration under the <parameters> element in the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

Parameters

<parameters>
   <parameter name="timeInMins" type="int">
      <displayName>Time(Mins)</displayName>
      <description>The sliding time period for which the window should hold events</description>
      <defaultValue>1</defaultValue>
   </parameter>
   <parameter name="sensorType" type="string">
      <displayName>Sensor Type Name</displayName>
      <description>The name of the sensor type</description>
      <defaultValue>temperature</defaultValue>
      <options>temperature,humidity,pressure</options>
   </parameter>
</parameters>

Step 10: Configure common artifacts

This step involves configuring the artifacts common to all scenarios. The Template Manager allows you to add multiple scenarios within a single base template file. This section explains how to share these artifacts across scenarios without creating conflicts. To configure common artifacts, add the following configuration under the <commonArtifacts> element to the <CEP_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml file.

Common Artifacts

<commonArtifacts>
   <artifact type="eventstream">
      <!--This Stream can be used across the whole Domain.-->
      {
            "name": "commonStream",
            "version": "1.0.0",
            "nickName": "",
            "description": "",
            "payloadData": [
            {
            "name": "timestamp",
            "type": "LONG"
            },
            {
            "name": "value",
            "type": "DOUBLE"
            }
            ]
            }
   </artifact>
</commonArtifacts>

Step 11: Configure Scripts

A script can be included either using an external file that is stored in the <CEP_HOME>/repository/conf/template-manager/scripts directory as a source attribute, or the actual content can be provided as a value. Following example shows how to configure the script both ways respectively.

Scripts

<scripts>
	<!--This script points to the <CEP_HOME>/repository/conf/template-manager/scripts/wso2-commons.js file.-->
	<script src=”wso2-commons.js”/>
	<script>
		var toId = function (name) {
			return name.toLowerCase().replace(/ /g, '');
		}
	</script>
</scripts>

The JavaScript functions defined in the scripts as well as any default JavaScript functions can be used in any place where parameters can be used. The function calls should be placed in between ‘${‘ and ‘}’. An example is given below in declaration of event publisher.

Event Publisher Using Scripts

<template type="eventpublisher">
<![CDATA[
<eventPublisher name="${toId(‘$sensorType’)}.statistics.stream.publisher"
     statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
   <from streamName="org.wso2.event.${‘$sensorType’.toLowerCase()}.statistics.stream" version="1.0.0"/>
   <mapping customMapping="disable" type="wso2event"/>
   <to eventAdapterType="ui"/>
</eventPublisher>
]]>
</template>

The SensorAnalyticsDomain.xml file with all the required configurationsis available by default in the <CEP_HOME>/repository/conf/template-manager/domain-template directory. This template contains all the configurations given above except stream mapping, common artifacts and scripts. You can try out these templates as explained in Using Templates.