2013/05/07
7 May, 2013

Eclipse Plug-in for WSO2 Business Rules Server

  • Denuwanthi De Silva
  • Associate Tech Lead - WSO2

Introduction

Previously WSO2 BRS artifacts (aar/car) were created using the web UI rule wizard or creating the artifact by combining several artifacts. With the new WSO2 Developer Studio plug-in for rule services, one can easily create a complete deployable BRS artifact using the Eclipse IDE. Developers can easily create WSO2 BRS artifacts using this tool, and deploy it in the WSO2 Business Rules Server.

When creating WSO2 BRS artifacts using this tool, there are several approaches to insert the rule file(.drl). These approaches include creating a rule file using JBoss drools plug-in, adding a rule file that already exists in a registry or creating a rule file in the WSO2 Developer Studio Registry Resource Project and adding it.

This tutorial provides a guide on how to properly create a WSO2 BRS artifact using Eclipse IDE, and then deploying it to the WSO2 BRS.

Applies To

WSO2 BRS 2.0.0
WSO2 Developer Studio 2.2.0

Table of Contents

Creating a rule service project

In this section, we discuss how to create a rule service project in WSO2 Developer Studio. The rule service project created using this tool should contain POJO classes that describe the facts for the rule configuration and the rule configuration file (.rsl). It should also contain a rule file with the extension .drl, which can be created using JBoss Drools plug-in or imported from the file system.

Installing JBoss Drools plug-in

The JBoss Drools plug-in supports several functionalities, including the ability to write rule files with content assist support. The rule file is generated with basic syntax so that the developer only has to fill the conditions of the rule.

By using this Drools plug-in, we can easily create, edit, test and integrate rules to our application.

First, go to the 'Help' menu in Eclipse IDE and select the 'Install New Software' option. You will get the following window.

Help Window

Now, you have to add the url of the JBoss Drools plug-in's update site. To do this , click on the 'Add' button in the above window and you will get a dialog box that is similar to the following one.

Update Site

Give a name to the update site and enter the url for the update site in the 'Location' field. (update site link)

Update Site

Then, the Drools plug-in will be ready to be installed.

Help Window

After installing the JBoss Drools plug-in, it can be seen in the 'Resource' window. Using this resource, we can create Drools projects in the workspace.

Drools

Installing WSO2 Developer Studio

The WSO2 BRS plug-in is integrated to the WSO2 Developer Studio. Thus, we need to install WSO2 Developer Studio to the Eclipse IDE we are working on. A full guide to installing WSO2 Developer Studio can be found in this tutorial.

Creating a Maven Multi Module Project

Maven Multi Module Project is used to get the benefit of maven centric development supported by WSO2 Developer Studio. It contains a parent project with child modules that can be artifact projects, like the rule service project. Other than that, we need to have a distribution module as a child module to create deployable artifacts. In WSO2 Developer Studio, we use Carbon Application Project as the distribution module.

Using the Maven Multi Module Project, we can easily combine the necessary artifact projects and build them from the source using the command mvn clean install. When we build the Maven Multi Module Project, the deployable artifact will be created in the target folder of the Carbon Application Project.

The Maven Multi Module Project is also a plug-in provided by WSO2 Developer Studio. We can create a Maven Multi Module Project from the Developer Studio Dashboard, as shown below.

Maven Multi Module Project

A complete tutorial on creating a WSO2 Maven Multi Module Project can be found here.

For this tutorial, we created a WSO2 BRS project, WSO2 Registry Resource Project and a WSO2 Carbon Application Project as child modules within the Maven Multi Module Project.

Creating a Rule Service Project

WSO2 BRS Rule plug-in is integrated with WSO2 Developer Studio. Thus, one can easily find the BRS rule project in the WSO2 Developer Studio Dashboard.

BRS Project

The Project Creation Wizard for BRS Rule plug-in gives you the option of creating a new Rule Service from scratch or importing a rule configuration file (.rsl) and creating a deployable artifact out of it.

Project Creation Wizard

This tutorial will demonstrate creating a simple Greeting Service Project. The next page of the Project Creation Wizard asks for the Project name, Rule service name, and target name space.

Project Creation Wizard

After filling those fields and clicking the 'Finish' button on the wizard, a new Rule Service Project is created within the Maven Multi Module Project. The rule configuration file is displayed as a multi-page editor with Graphical view editor and source view editor as shown in the following image. The 'Service Name' and 'Target Namespace' fields get their values from the values entered to the Project Creation Wizard at the beginning.

BRS Project

Basic components of the project:

  • Java classes - included under the java subfolder
  • Rule configuration file – included in the META-INF folder, which is under the ruleservice subfolder
  • Rule file – included in the conf folder

Initially, only the rule configuration file is generated within the project hierarchy.

BRS Project Structure

Adding a Rule file

A Rule file contains the rules defined for the particular scenario. In this plug-in, we can enter Rule details to the 'Rules' table. When you click on the 'Add' button of the 'Rules' table, you get a Dialog where you can enter the Rule details. The 'Description' field is not mandatory. The user can select 'Resource Type' from the drop-down menu, where the default value is set to 'regular'. The 'Source Type' field is used to provide the Rule file(.drl). There are four options to enter the rule file in the 'Source Type' field: the first is to provide the rule file 'inline' - the user can easily copy the content of a rule file and paste it in the 'inline' section; the next way is to provide the url of the rule file in the 'URI' section; the next two methods are to enter the rule file from 'registry' and by browsing the rule file from the file system. In this tutorial, we discuss the last two methods, as they are the ones that are widely used.

Creating Rule File using drools plug-in

A user can create a rule file using JBoss drools plug-in and give that file as the rule definition for the rule configuration file. If you have already installed JBoss drools plug-in in eclipse, as mentioned at the beginning of this tutorial, you can now create a new rule file for the Rule Service Project.

The Rule files (.drl) are stored in the 'conf' folder. Thus, the rule file from the JBoss drools plug-in should be created inside the 'conf' folder. Select the 'Rule Resource' option to create the Rule file.

Rule File

Give any name to the Rule file name and give a package name too as shown below.

Rule File

The generated Rule file will look as follows. The essential structure of a general rule file is already created by the JBoss drools plug-in that makes it easier for a developer to work on the IDE. A developer only has to fill the conditions and actions for each rule.

Rule File

To write the rule file, we need to create Facts classes, which define the Facts and Results. Facts classes are normal java classes and added to the 'java' folder in the 'GreetingServiceProject'. For this project, we need two Facts classes; they are User.java and GreetingMessage.java.

Facts

Now, we can complete the rule file by importing the necessary Facts classes.

Facts

Now, to add this rule file to the rule configuration file, we can click on the 'Add' button of the 'Rules' table of the graphical editor and the below 'Dialog' will appear. In the 'file' tab, we have a drop-down menu to select the rule files added to the 'conf' folder. In this scenario, the 'greeting_rules.drl' file is displayed in the drop-down menu. We can select it and click on 'Finish' to send them to the table.

Rules

After adding the rule file, the table in the graphical editor will be updated as follows:

Rules

The source editor will be updated as follows:

Rules

Adding a Rule file that already exists in a registry

Instead of using the JBoss drools plug-in and creating the rule file and adding it, we can upload the rulefile to an existing WSO2 configuration or Governance registry and access that rule file from our Business Rules Service Project in eclipse and refer it in the rule configuration file.

In this scenario, the rule file will be uploaded to the Config registry. To do that, log in to the latest WSO2 Business Rules Server and in the 'Registry' section, select 'Browse' and select the 'config' option.

Rules

After uploading the rule file (.drl) to the config registry, it will be displayed as follows.

Rules

Now, to add that rule file as an entry in rule configuration file generated by the Business Rules Service plug-in, select the 'registry' tab of the 'Input Dialog' that appears when clicking on the 'Add' button of the 'Rules' table. Here, you can use the 'Registry Browser' button to navigate through the 'Config' or 'Governance' registry to get the rule file.

Registry Browser

When you click on the 'Registry Browser' button, a small window, as shown below, will be displayed. It is the default registry browser window used throughout many WSO2 Developer Studio products.

Registry Browser

When you select the 'registry' link on that window, the following window will appear.

Registry Connection Window

Since the rule file was uploaded to the configuration registry in the WSO2 Business Rules Server, we can add a new registry connection to the 'Config' registry as follows.

Registry Connection Window

Then a tree view of the 'config' registry will be visible, where we can see the rule file (greeting.drl) we uploaded to the configuration registry in an earlier step.

Configuration registry

After selecting the rule file from the 'config' registry, it is added to the 'Resource URI' field as follows:

Configuration registry

Adding Rule file as a Registry Resource

Unlike the earlier method, we can create a new WSO2 Registry Resource Project within the Maven Muli Module Project, and add the rule file as a resource in there. Thereafter, we should create a Carbon Application archive containing both the Registry Resource Project and Business Rules Service Project. Thus, we eliminate the need to upload a rule file to a registry in the WSO2 server. When the .car file is deployed, the rule file in the Registry Resource Project will be added to the registry.

Create a new Registry Resource Project within the Maven Multi Module Project.

Registry Resource Project

Once the Registry Resource Project is created, add a new Registry Resource to it.

Registry Resource

Add a rule file (greeting.drl) as a registry resource. Then an editor will be opened as in the following image. Here, the 'Resource Deploy Path' is set to default '/_system/custom', but it should be changed as '/_system/config' or '/_system/governance' .

Resource Editor

Thereafter, to add this rule file as an entry in the rule configuration file, select the 'workspace' link in the Registry Browser Dialog box. Then, it will show the rule file as a registry resource in the Registry Resource Project.

Registry Browser workspace

Adding Operations

To add 'Operations' to the rule configuration file via the graphical editor, another table is used. It is labeled the 'Operations' table. To add an operation, we can click on the 'Add' button near the table, and then a dialog box will appear as shown in the image below. We can add the necessary details to the fields in the dialog box.

Configuration registry

To enter 'Facts' details, another table is used inside the 'Operation' dialog box. It provides the facility to select the 'Fact Type' from a drop-down menu, which are the java classes created in an earlier step.

Facts

After entering data for input and output facts, those details will be updated to the 'Operations' table. This is the final view of the graphical editor after entering all the necessary details that should come in the rule configuration file.

Graphical editor

The source view of the rule configuration file generated by the input given by graphical editor is as follows:

Source editor

Deploying the BRS artifact

To create a deployable artifact that is, a .aar file of the Business Rules Service Project, we have to first create a Carbon Application Project, where we can include all the necessary projects we have created so far within the Maven Multi Module Project. Thereafter, we can build the Maven Multi Module Project using the mvn clean install command. Then, the .car file will be created inside the target folder of the Carbon Application Project. Finally, we can upload that file to the WSO2 Business Rules Server and invoke the intended service.

Deploying Business Rules Service projects, where rule file was created from drools plug-in or rule file was taken from a registry

Create a new Carbon Application Project within the Maven Multi Module Project.

Carbon Application project

Under 'Dependencies' select the Business Rules Service Project you created.

Dependencies

The Carbon Application Project will be created within the Maven Multi Module Project. Make sure to select the server role as 'Business Rules Server'. Then, create the .car archive by clicking on the 'Create Archive' button in the Capp project.

Dependencies

Next, go to the Maven Multi Module plug-in from the terminal, and build it using the 'mvn clean install' command. Thereafter, the .car file will be created in the target folder of Carbon Application Project.

Building the project

Now, go to the WSO2 Business Rules Server instance you are running, and go to 'Carbon Applications' and select 'Add'. Then, you will get a user interface where you can upload the .car file created earlier.

.car file upload

After uploading the .car file it will be displayed under the Carbon Application list.

car file list

Then in 'Services' go to the 'list'. The service you created will be displayed. Now, you can try the service.

services list

Deploying Business Rules Service projects where rule file is a Registry Resource

As in the earlier section, Create a Carbon Application Project. In dependencies, select the Business Rules Service project as well as the Registry Resource Project.

Dependencies

When the Carbon Application Project is created, make sure to make the server role as 'Business Rules Server' for both Business Rules Service Project and the Registry Resource (rule file) inside the Registry Resource Project.

Server Role

Conclusion

This article provides a step-by-step description on how to create a WSO2 Business Rules Service Project in the WSO2 Developer Studio and then describes how to deploy generated artifacts in different scenarios.

References/Resources

Author

Denuwanthi De Silva, Trainee Software Engineer, WSO2 Inc

 

About Author

  • Denuwanthi De Silva
  • Associate Tech Lead
  • WSO2 Lanka