Configuring a Template for Template Manager
This section illustrates how to configure templates for WSO2 DAS 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 <DAS_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 DAS 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 and Event Tables.
To add required event streams for this use case, add the following configuration under the <template type="event stream">
element in the <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file you created, and save.
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 DAS 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 DAS Management Console and define the required event stream. For detailed instructions, see Understanding Event Streams and Event Tables.
- 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 event sinks
This step involves adding event sinks to be included in the template. An event sink configuration contains information relating to what attributes need to be persisted in a WSO2 DAS event stream. An event sink configuration is created in the <DAS_HOME>/repository/deployment/server/eventsink
directory when you persist an event stream. For more information about persisting dreams, see Persisting Data for Batch Analytics.
To add the event sink required for this use case, add the following configuration under the <template type="event sink">
element in the <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file you created, and save.
The following procedure is an easy approach to create the configuration for an event sink to be added to the Template Manager.
- Log into the WSO2 DAS Management Console and define the required event stream. For detailed instructions, see Understanding Event Streams and Event Tables.
- Persist the event stream you created. For detailed instructions, see Persisting Data for Batch Analytics.
- Open the
<DAS_HOME>/repository/deployment/server/eventsink/<Event_Stream_Name>.xml
file. Copy the configuration in this file and add it to your template under the<template type="eventsink">
element. - Add the required configurable parameters and save.
Step 4: 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 <DAS_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.
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 DAS 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 DAS 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<DAS_HOME>/repository/conf/template-manager/domain-template
directory. - Add the required configurable parameters and save.
Step 5: Configure batch analytics
This step involves adding the Spark scripts required for this use case to the template. The Batch Analytics functionality of DAS is powered by Apache Spark. Therefore, Spark scripts are run in order to perform the required queries on persisted data. For more information about Spark scripts,see Scheduling Batch Analytics Scripts.
To add the batch analytics configuration required for this use case, add the following configuration under the <template type="batch">
element in the <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
An Batch Analytics configuration should always be added inside a CDATA element.
Step 6: Configure an event publisher
This step involves adding an event publisher to the template. Event publishers publish events from WSO2 DAS to external consumers. For more information about event publishers, see Creating Alerts - Creating Event Publishers.
To add the event publisher configuration required for this use case, add the following configuration under the <template type="eventPublisher">
element in the <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
An event receiver configuration should always be added inside a CDATA element.
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 DAS Management Console and create the required event publisher. For detailed instructions to create an event publisher, see Creating 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<DAS_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 7: Configure a gadget
This step involves adding a gadget configuration to the template. For more information about gadgets, see /wiki/spaces/TESB/pages/32604660.
To add the gadget configuration required for this use case, add the following configuration under the <
template
type
=
"gadget"
>
element in the <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
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 <DAS_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/32604660.
- The artifacts mentioned above are located in the
<DAS_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<DAS_HOME>/repository/conf/template-manager/domain-template
directory. - Add the required configurable parameters and save.
Step 8: 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.
To add the dashboard configuration required for this use case, add the following configuration under the <
template
type
=
"dashboard"
>
element in the <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
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 Adding a Dashboard.
The dashboard configuration is saved in the/_system/config/ues/dashboards/<Dashboard_Name>
registry path. To access the registry, log into the WSO2 DAS 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<DAS_HOME>/repository/conf/template-manager/domain-template
directory.
Step 9: 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 DAS 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 <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
<streamMappings> <streamMapping to="org.wso2.event.$sensorType.stream:1.0.0" /> </streamMappings>
Step 10: 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 <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
Step 11: 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 <DAS_HOME>/repository/conf/template-manager/domain-template/Sensor-Analytics.xml
file.
Step 12: Configure Scripts
A script can be included either using an external file that is stored in the <DAS_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.
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.
The SensorAnalyticsDomain.xml
file with all the required configurationsis available by default in the <DAS_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.