

Working with Business Rules¶

In streaming integration, there are common use cases for analyzing statistics that involve operations such as calculating the average, minimum, maximum etc., for different endpoints. The Business Rules Manager allows you to define templates and generate business rules from them for different scenarios with common requirements.

Creating Business Rules¶

This section explains how to create a business rule. A business rule can be created from a template or from scratch.

Creating Business Rules from a Template¶

Creating business rules from an existing template allows you to use sources, sinks and filters that have been already defined, and assign variable values to process events.

Before you begin:

The business rule template must be already configured in the <SI_TOOLING_HOME>/conf/server/deployment.yaml file. For detailed instructions, see Business Rules Templates.
If you want to deploy the business rule after creating it, you need to start the SI server by navigating to the <SI_HOME>/bin directory and issuing one of the following commands:
- On Windows: server.bat --run
- On Linux/Mac OS: ./server.sh

To create a business rule from a template, follow the procedure below:

Navigate to the <SI_TOOLING_HOME> directory from the terminal and start the Streaming Integrator Tooling by issuing one of the following commands:
- On Windows: tooling.bat --run
- On Linux/Mac OS: ./tooling.sh
Access the Business Rule Manager via the URL that appears in the terminal for Business Rules in the https://<SI_TOOLING_HOST>:<HTTPS_PORT>/business-rules format.

Tip

The default URL is https://0.0.0.0:9743/business-rules. If required, you can change the host name (i.e., 0.0.0.0) or the web UI application name (i.e., business-rules). For instructions, see Changing the Host Name and Context Path of SI Tooling.

This opens the following:
Click Create to open the following page.
Then click From Template to open the Select a Template Group page, where the available templates are displayed.
Click on the template group that contains the required template to create a business rule from it. In this example, the business rule is created based on a template in the Sweet Factory template group that is packed with the Streaming Integrator by default. Therefore, click Sweet Factory to open this template group.
In the template group, expand the Rule Template list as shown below, and click on the required template. For this example, click Identify Continuous Production Decrease.
If you want to change the rule template from which you want to create the business rule, select the required value for the Rule Template field.
Enter a name for the business rule in the Business Rule Name field.
Enter values for the rest of the fields following the instructions in the UI.

Info

The fields displayed for the business rule differ based on the selected template.
If you want to save the business rule and deploy it later, click Save. If you want to deploy the business rule immediately, click Save and Deploy.

Creating a business rule from scratch¶

Creating a business rule from scratch allows you to define the filter logic for the rule at the time of creating, instead of using the filter logic that has been already defined in a template. However, you can select the required source and sink configurations from an existing template.

Before you begin:

If you want to deploy the business rule after creating it, you need to start the SI server by navigating to the <SI_HOME>/bin directory and issuing one of the following commands:

- On Windows: server.bat --run
- On Linux/Mac OS: ./server.sh

To create a business rule from scratch, follow the procedure below:

Navigate to the <SI_TOOLING_HOME> directory from the terminal and start the Streaming Integrator Tooling by issuing one of the following commands:
- On Windows: tooling.bat --run
- On Linux/Mac OS: ./tooling.sh

Access the Business Rule Manager via one of the following URLs.

Protocol	URL Format	Example
HTTP	`http://<SI_TOOLING_HOST>:<HTTP_PORT>/business-rules`	`http://0.0.0.0:9090/business-rules`
HTTPS	`https://<SI_TOOLING_HOST>:<HTTPS_PORT>/business-rules`	`https://0.0.0.0:9443/business-rules`

Tip

The URLs given above are the defaul URLs. If required, you can change the host name (i.e., 0.0.0.0) or the web UI application name (i.e., business-rules). For instructions, see Changing the Host Name and Context Path of SI Tooling.

This opens the following:

No Business Rule Exists

Click Create to open the following page, and then click From Scratch.

This opens the Select a Template Group page where the available template groups are displayed as shown in the example below.
Click on the template group from which you want to select the required sources and sinks for your business rule. For this example, click Stock Exchange to open that template group as shown below.
Click Input to expand the Input section. Then select the rule template from which the source and input configurations for the business rule must be selected.

This displays the list of available sources and the exposed attributes of the selected template as shown below.
Click Filters to expand the Filters section, and click + to add a new filter. A table is displayed as shown below.
To define a filter, follow the steps below:
1. In the Attribute field, select the attribute based on which you want to define the filter condition.
2. In the Operator field, select an operator.
3. In the Value/Attribute field, enter the value or another attribute based on which, the Operator is applied to the Attribute.
e.g.,
If you want to filter events where the price is less than 100 (which is a value), select values for the fields as follows:

Field Value

Attribute price

Operator <

Value/Attribute (Value) 100

If you want to filter events where the price is equal to the volume (which is another attribute), select values for the fields as follows:

Field Value

Attribute price

Operator ==

Value/Attribute (Attribute) volume

Once you have defined two or more filters, enter the rule logic in the Rule Logic field using OR, AND, and NOT conditions. The examples of how you can use these keywords are explained in the table below.

Keyword Example

OR 1 OR 2 returns events that match either filter 1 or 2.

AND 1 AND 2 returns events that match both filters 1 and 2.

NOT NOT 1 returns events that do not match filter 1.
Click Output to expand the Output section. Then select the rule template from which the sink and output configurations for the business rule must be selected.

This displays the section for mapping configurations as shown in the example below.
Select the relevant attribute names for the Input column. When publishing the events to which the rule is applied via the selected predefined sink, each input event you select is published with the corresponding name in the Output column.

Info

The output mappings displayed differ based on the output rule template you select.
If you want to save the rule and deploy it later, click Save. If you want to deploy the rule immediately, click Save and Deploy.

Managing Business Rules¶

Once you have created one or more business rules, you can manage them by viewing, editing, deploying, undeploying, and deleting them as required.

Viewing business rules¶

Once you start and access the Business Rules Manager, the available business rules are displayed as shown in the example below.

View Business Rules

To view a business rule, click the icon for viewing (marked in the above image) for the relevant row. This opens the rule as shown in the example below.

Business Rules Information

Editing business rules¶

Once you start and access the Business Rules Manager, the available business rules are displayed as shown in the example below.

Edit Business Rule

To edit a business rule, click the icon for editing (marked in the above image) for the relevant row. This opens the rule as shown in the example below.

Edit Business Rule Details

Modify values for the parameters displayed as required and click Save.

Deploying business rules¶

Before you begin:

Start the Streaming Integrator server by navigating to the <SI_HOME>/bin directory from the CLI, and issuing one of the following commands:

- On Windows: server.bat --run
- On Linux/Mac OS: ./server.sh

To deploy a business rule that you have previously saved, click the icon for deploying (marked in the image below) for the relevant row. As a result, a message appears to inform you that the rule is successfully deployed. Deploy Business Rule

Undeploying business rules¶

To undeploy a business rule, click the icon for undeploying (marked in the image below) for the relevant row. As a result, a message appears to inform you that the rule is successfully undeployed.

Undeploy Business Rule

Viewing deployment information¶

If you want to view information relating to the deployment of a business rule, click the icon for viewing deployment information (marked in the image below) for the relevant row.

View Deployment Information

As a result, the deployment information including the host and port of the nodes in which the rule is deployed and the deployment status are displayed as shown in the image below.

Possible deployment statuses are as follows:

Saved: The business rule is created, but not yet deployed in any Streaming Integrator node.
Deployed: The business rule is created and deployed in all the required nodes in the Streaming Integrator cluster.
Partially Deployed: The business rule is created and deployed only in some of the required nodes in the Streaming Integrator cluster.
Partially Undeployed: The business rule has been previously deployed, and then undeployed only in some of the nodes in the Streaming Integrator cluster.

Info

Required nodes are configured with respect to a rule template. For detailed instructions, see Deploying business rules in SI server.

Deleting business rules¶

To delete a business rule, click the icon for deleting (marked in the image below) for the relevant row. A message appears to confirm whether you want to proceed with the deletion. Click Delete in the message. As a result, another message appears to inform you that the rule is successfully deleted.

Delete Business Rules

Creating a Business Rules Template¶

To create a business template using the Business Rules Template editor, follow the procedure below:

If you have not already started the Streaming Integrator tooling, navigate to the <SI_TOOLING_HOME>/bin directory from the terminal and start the Streaming Integrator Tooling as mentioned below.
- On Windows: tooling.bat --run
- On Linux/Mac OS: ./ tooling.sh
Access the Business Rules Template Editor via the URL that appears for it in the start up logs as shown in the example below.

Info

The default URL is http://localhost:9390/template-editor. If required, you can change the host name (i.e., localhost) or the web UI application name (i.e., template-editor). For instructions, see Changing the Host Name and Context Path of SI Tooling.
The Template Editor opens as shown below. There are two views from which you can interact and create a template group. Design view allows you to visualize a template group and interact with it. Code view allows you to interact with a template group by typing content. (For more information about template group structure, see Business Rules Templates.)

Warning

Do not template sensitive information such as passwords in a Siddhi application or expose them directly in a Siddhi application. For detailed instructions to protect sensitive data by obfuscating them, see Protecting Sensitive Data via the Secure Vault.

Business Rules Editor

You can create a template group using the design view or the code view as explained in the following sections.

Create from Design View¶

To create a business rules template group from the design view, follow the procedure below:

Enter a UUID (Universally Unique Identifier), name and a description for the template group as follows.

Field Name

UUID sweet-factory

Name Sweet Factory

Description Analyzes Sweet Factory scenarios

Expand the first rule template that exists by default, and enter the following details.

Field Name	Value
UUID	identifying-continuous-production-decrease
Name	Identify Continuous Production Decrease
Description	Alert factory managers if the rate of production continuously decreases for a specified time period
Type	Template
Instance Count	One

Rule Template Details

To include a Siddhi application template, expand the first template that is displayed by default, and enter the following Siddhi application template.

Siddhi Application Template

    @App:name('SweetFactory-TrendAnalysis')

    @source(type='http', @map(type='json'))
    define stream SweetProductionStream (name string, amount double, factoryId int);

    @sink(type='log', @map(type='text', @payload("""
    Hi ${username},
    Production at Factory  has gone
    from  to  in ${timeInterval} seconds!""")))
    define stream ContinousProdReductionStream (factoryId int, initaltime long, finalTime long, initalamout double, finalAmount double);

    from SweetProductionStream#window.timeBatch(${timeInterval} sec)
    select factoryId, sum(amount) as amount, currentTimeMillis() as ts
    insert into ProdRateStream;

    partition with ( factoryId of ProdRateStream )
    begin
      from every e1=ProdRateStream,
      e2=ProdRateStream[ts - e1.ts <= ${timeRange} and e1.amount > amount ]*,
      e3=ProdRateStream[ts - e1.ts >= ${timeRange} and e1.amount > amount ]
      select e1.factoryId, e1.ts as initaltime, e3.ts as finalTime, e1.amount as initalamout, e3.amount as finalAmount
      insert into ContinousProdReductionStream;
    end;

To add variable attributes to the script, click Add Variables.

Info

A script is a javascript that can be applied when the inputs provided by the business user who uses the template need to be processed before replacing the values for the template variables. e.g., If the average value is not provided, a function within the script can derive it by calculating it from the minimum value and the maximum value provided by the business user.
To specify the attributes that need to be considered as variables, select the relevant check boxes under Select templated elements. In this example, you can select the username and timeRange check boxes to to select the attributes with those names as the variables.

Then click Add To Script to update the script with the selected variables with auto-generated function bodies as shown below.

Edit the script to add the required functions. In this example, let's rename myFunction1(input) to getUsername(email), and myFunction2(input) to validateTimeRange(number).

Edit Script

    var username = getUsername('${userInputForusername}');
    var timeRange = validateTimeRange('${userInputFortimeRange}');
    /**
    * Extracts the username from given email
    * @returns Extracted username
    * @param email Provided email
    */
    function getUsername(email) {
        if (email.match(/\S+@\S+/g)) {
            if (email.match(/\S+@\S+/g)[0] === email) {
                return email.split('@')[0];
            }
            throw 'Invalid email address provided';
        }
        throw 'Invalid email address provided';
    }


    /**
    * Validates the given value for time range
    * @returns Processed input
    * @param input User given value
    */
    function validateTimeRange(number) {
        if (!isNaN(number) && (number > 0)) {
            return number;
        } else {
            throw 'A positive number expected for time range';
        }
    }

To generate properties, click Generate against Properties.

This expands the Properties section as follows.

Enter values for the available properties as follows. For this example, let's enter values as shown in the following table.

Info

A property is defined for each templated attribute (defined in the ${templatedElement} format), so that it is self descriptive for the business user who uses the template. The values configured for each property are as follows:

Field Name: The name with which the templated attribute is displayed to the business user.
Field Description: A description of the property for the business user to understand its purpose.
Default Value: The value assigned to the property by default. The business user can change this value if required.
Options: this is an optional configuration that allows you to define a set of values for a property so that the business user can select the required value from a list. This is useful when the possible value for the property is limited to a set of options.

Property	Field Name	Field Description	Default Value
`timeInterval`	`Time interval (in seconds)`	`Production amounts are considered per time interval`	`6`
`userInputForusername`	`Manager Email ID`	`Email address to show in greeting`	`example@email.com`
`userInputFortimeRange`	`Time Range (in milliseconds)`	`Time period in which, product amounts are analyzed for decrease`	`5`

Configure Properties

To save the template, click the save icon at the top of the page.

Create from code view¶

When you use the code view, the same parameters for which you enter values in the design view are represented as JSON keys. For each parameter, you can specify a value against the relevant JSON key as shown in the extract below.

Source View Extract

When you update the code view with a valid template group definition, the design view is updated simultaneously as shown below.

Side-by-side View

However, if the content you enter in the code view is an invalid template group, the design view is not updated, and an error is displayed as follows.

Error Code

When an error is detected in the entered template group structure, the Recover button is displayed with the error message.

When you click Recover, the code view is reset to the latest detected valid template group definition. At any given time, the design view displays information based on the latest detected valid template group definition.

Info

It is not recommended to add Siddhi application templates and scripts using the code view because they need to be provided as a single line, and the possible escape characters should be handled carefully.

Editing a Business Rules Template¶

ESB SI allows you to make edits to a business rules template that you have already created and saved. To edit a template via the Template Editor tool, follow the steps below.

Start the ESB SI Tooling profile by issuing one of the following commands.
- For Windows: tooling.bat
- For Linux: ./tooling.sh
Access the Template Editor via the URL that appears for it in the start up logs as shown in the example below.

Info

The default URL is http://localhost:9390/template-editor. If required, you can change the host name (i.e., localhost) or the web UI application name (i.e., template-editor). For instructions, see Changing the Host Name and Context Path of SI Tooling.
The Template Editor opens as follows.

To open an existing template, click the Open icon in the top panel (marked in the image above). In the Open Template File dialog box, click Choose File and browse for the required template. Once you have selected the template, click Load to open it in the Template Editor.
Edit the template as required. You can update it in the Design View or the Source View as you prefer. For more information, see Creating a Business Rule Template.
Save your edits by clicking the Save icon in the top panel.

Business Rules Templates¶

Rule Templates are used as specifications to gain inputs from users, through dynamically generated fields for the purpose of creating business rules. A template group is a business domain level grouping. The definition of a template looks as follows.

    {
      "templateGroup" : {
        "name" : "<Name of the template group>",
        "uuid":"<UUID for the template group>",
        "description" : "<(Optional) description for the template group>",
        "ruleTemplates" : [
          {
            "name" : "<Name of the rule template>" ,
            "uuid" : "<UUID for the rule template>",
            "type" : "template",
            "instanceCount" : "one <or> many",
            "description" : "<(Optional) description for the rule template>",
            "script" : "<(Optional) Javascript with reference to the properties>",
            "templates" : [
              { "type" : "siddhiApp",
                "content" : "<SiddhiApp_1 with ${templatedProperty_x}>"
              },
              { "type" : "siddhiApp",
                "content" : "<SiddhiApp_n with ${templatedProperty_y}>"
              }
            ],
            "properties" : {
                "templatedProperty_x" : {"fieldName" : "<Field name for the property>", "description" : "<Description for the property>", "defaultValue" : "<Default value for the property>"},
                "templatedProperty_y" : {"fieldName" : "<Field name for the property>", "description" : "<Description for the property>", "defaultValue" : "<Default value for the property>", "options" : ["<option_1>", "<option_n>"]}
            }
          },
          {
            "name" : "<Name of the rule template>",
            "uuid" : "<UUID for the rule template>",
            "type" : "input",
            "instanceCount" : "one <or> many",
            "description" : "<(Optional) description for the rule template>",
            "script" : "<(Optional) Javascript with reference to the properties>",
            "templates" : [
              { "type" : "siddhiApp",
                "content" : "<SiddhiApp with ${templatedProperty_x}>",
                "exposedStreamDefinition" :"<Exposed stream definition>"
              }
            ],
            "properties" : {
              "templatedProperty_x" : {"fieldName" : "<Field name for the property>", "description" : "<Description for the property>", "defaultValue" : "<Default value for the property>", "options" : ["<option_1>", "<option_n>"]}
            }
          },
          {
            "name" : "<Name of the rule template>",
            "uuid" : "<UUID for the rule template>",
            "type" : "output",
            "instanceCount" : "one <or> many",
            "description" : "<(Optional) description for the rule template>",
            "script" : "<(Optional) Javascript with reference to the properties>",
            "templates" : [
              { "type" : "siddhiApp",
                "content" : "<SiddhiApp with ${templatedProperty_x}>",
                "exposedStreamDefinition" :"<Exposed stream definition>"
              }
            ],
            "properties" : {
              "templatedProperty_x" : {"fieldName" : "<Field name for the property>", "description" : "<Description for the property>", "defaultValue" : "<Default value for the property>", "options" : ["<option_1>", "<option_n>"]}
            }
          }
        ]
      }
    }

The following parameters are configured:

Template Group basic data¶

The following parameters are configured under templateGroup.

Parameter	Description	Required/Optional
`name`	A name for the template group	Required
`uuid`	A uniquely identifiable id for the template group	Required
`description`	A description for the template.	Optional

Rule Template details¶

Multiple rule templates can be defined under a templateGroup. For each ruleTemplate, the following set of parameters need to be configured:

Parameter	Description	Required/Optional
`name`	A name for the rule template	Required
`uuid`	A uniquely identifiable id for the rule template	Required
`type`	The type of the rule template. Possible values are as follows: `template:` Used only to create an entire business rule from template `input :` Used only in creating a business rule from scratch `output :` Used only in creating a business rule from scratch	Required
`instanceCount`	This specifies whether the business rules derived from the template can be deployed only on one node, or whether they can be deployed on many nodes. Possible values are as follows: one many	Required
`script`	The Java script to be executed on the templated fields. Developers can use this script for: validating purposes. deriving values for a templated parameter by combining some other entered parameters You need to mention each templated element that needs to be derived from entered parameters as a variable in the global scope of the JavaScript. You also need to template the entered parameters in the script itself. These values are later replaced with their respective entered values. Consider the following script `/* * Validates a number and returns after adding 10 to it * @throws Error when a non number is entered */ function deriveValue(value){ if( !isNan(value) ) { return value + 10; } throw "A number is required"; } var derivedValue = deriveValue(${enteredValue});` `enteredValue` should be defined as a property under `properties` in order to be filled by the user and replaced later. The derived value stored in `derivedValue` is then used to replace `${derivedValue}` in the SiddhiApp template.	Optional
`description`	A brief description of the rule template.	Optional
`templates`	These are the artifacts (i.e SiddhiApps) with templated parameters that are instantiated with replaced values when a business rule is created.	Required
`properties`	You can add a field name, description, default value and possible values (optional) for the templated parameters.	Required

Deploying business rules in SI server¶

To deploy a business rule in the Streaming Integrator server, follow the procedure below.

Before you begin:

Both the Streaming Integrator server(s) and Streaming Integrator tooling must be up and running.

Save the template group you created as a .json file in the <SI_TOOLING_HOME>/wso2/server/resources/businessRules/templates directory.
In the BusinessRules section of the <SI_TOOLING_HOME>/conf/server/deployment.yaml file, add a configuration for the template you created as shown below.
```
        wso2.business.rules.manager:

          datasource: <datasourceName>
            - nodeURL1:
               - ruleTemplateUUID1
               - ruleTemplateUUID2
              nodeURL2:
               - ruleTemplateUUID1
               - ruleTemplateUUID2
```
Info

Specify the value for nodeURL1 in the IP:Port format. If you add this configuration, a business rule which is derived from this rule template (when you run the Streaming Integrator Tooling and the Streaming Integrator servers of your SI setup) is deployed only in the nodes under which - this rule template has been specified. If you do not specifically add business rule template IDs in the configuration, business rules are deployed in all the available Streaming Integrator servers.

Configuring Business Rules Manager Permissions¶

There are two permission levels for a business rules application:

Manager: User roles with this permission level have administrative privileges over business rules. They are allowed to create, view, edit, deploy or delete business rules.
Viewer: User roles with this permission level are only allowed to view business rules.

This section covers how to configure Business Rules Manager permissions.

Before you begin:

Before configuring Business Rules Manager permissions, the user roles to be assigned permissions must be already defined in the user store with the required user IDs. For detailed instructions, see User Management.

You need to define the roles related to the Business Rules Manager under the wso2.business.rules.manager component namespace in the <SI_TOOLING_HOME>/conf/server/deployment.yaml file.

The following is a sample configuration of user roles for the Business Rules Manager.

    wso2.business.rules.manager:
      roles:
        manager:
          - name: role1
            id: 1
        viewer:
          - name: role2
            id: 2

Top

Field	Value
Attribute	`price`
Operator	`<`
Value/Attribute (Value)	`100`

Keyword	Example
`OR`	`1 OR 2` returns events that match either filter 1 or 2.
`AND`	`1 AND 2` returns events that match both filters 1 and 2.
`NOT`	`NOT 1` returns events that do not match filter 1.

Field	Name
UUID	sweet-factory
Name	Sweet Factory
Description	Analyzes Sweet Factory scenarios