How to Extract a Ruleset from a Rule Project

Samples > Rule Studio Business Rule Management Extensions > How to Extract a Ruleset from a Rule Project

How to Extract a Ruleset from a Rule Project

This sample shows how to use and create extractors and how to filter rule project elements with extractors using queries, validators or both. It also shows how to generate a ruleset archive using an extractor and execute it once it has been generated.

It can be useful to define a custom extractor when:

you want to have a single rule project and deploy rules (and other artefacts) at different locations.

In our example, we can imagine that the data is hosted in each region and we want to deploy distinct Human Resources rules on each region's application server, but at the same time we want to keep these rules in a single repository for ease of maintenance.

you want to select only a subset of rules that would be unwanted at runtime.

For example, you want to be sure that no "test" rules or any rule matching a defined pattern will be executed. In addition, you may want to discard expired rules or rules with an incorrect status. The filtering can be applied to any rule properties and you are limited only by the queries' Rule Studio API scope or by what can defined using the Rule Studio API inside validators.

Key Features

Key features include:

Development of an Eclipse plug-in using the exposed Rule Studio API
Use of existing extractors or creation of new ones
Ability to automate Rule Studio tasks through Ant tasks
Setting a query and/or a validator on an extractor
Checking if a query is defined in a rule project using Rule Studio API
Creating a validator by extending an Eclipse plug-in extension point
Checking if the validator is extending the Rule Studio's validator extension point using Eclipse API
Creating a query using its text definition
Generating a ruleset archive using an extractor
Forcing the build of a rule project using the Eclipse API
Running the generated ruleset archive using basic Java code

Importing this Sample

This sample extends the Rule Studio API. The required sample plug-ins are delivered as pre-deployed. If you have not already done so, you must install the samples extension site in Eclipse before running the sample.

To install the plug-in samples extension site:

Click Help > Software Updates > Manage Configuration.
In the Product Configuration dialog, click the Add an Extension Location link.
In the Browse dialog, select the folder <InstallDir>/studio/samples/eclipse.
If prompted to restart the Eclipse Workbench, click Yes.

Eclipse shuts down and restarts.

To check that the Ruleset Extraction Sample feature is enabled:

In the Rule Explorer, select the loanvalidation-rules project.
Click Help > Software Updates > Manage Configuration.
In the left pane of the Product Configuration page, expand C:\ILOG\JRules\studio\samples\eclipse and check that Ruleset Extraction Sample 1.0.0. is listed.

To import the rulesetextraction sample:

Click File > Import.
In the Import Wizard, select ILOG Rule Studio Samples and Tutorials then click Next.
Select the sample brmanagement > rulesetextraction.
Click Finish.
If one or more files already exist in your workspace, a warning message is displayed indicating the file(s) were not re-imported. Close the message window.

The imported sample project files are displayed in the Rule Explorer. You should see three new projects:

- rulesetextraction_rules. The sample rule project.

- rulesetextraction_xom. A Java project containing the execution model of rulesetextraction_rules.

rulesetextraction_application. A Java project containing the code to demonstrate how to execute a ruleset archive.

This project also includes an Ant build file (build.xml) which contains different Ant tasks that will be used in order to demonstrate different extraction scenarios.

Note

The target init.runtime was added in the build.xml file to help Eclipse set the runtime properties: os (operating system), ws (window system) and arch (architecture) before extracting the ruleset archive. This should work for most common configurations. If it does not match your runtime environment, you can modify the Ant target to force the values of these properties.

Running the Sample

To run this sample:

In the Rule perspective, on the Run menu, click Run.
Select the Rule Project > rulesextraction-rules-execution launch configuration.
Click Run.

Output is displayed in the Console view:

** Error ** Bill Jona's competence interview is before his hire date.

> Mike Levy works in Africa

> Billy Edouards works in Africa

> Naomie Parker works in America

> John Smith works in America

> Dick Roberts works in Asia

> Nate Arris works in Asia

> Paul Ellis works in Asia

> Ed Matthews works in Europe

> Kim Fisher works in Europe

> Tracy Cooper works in Europe

> Bill Jona works in Europe

> Patrick Doe works in Europe

> Vanessa Arisson works in Oceania

> Bob Arthur works in Oceania

$ Dick Roberts hire date is: 01/01/1992

$ Ed Matthews hire date is: 02/01/1992

$ Mike Levy hire date is: 12/01/2002

$ Naomie Parker hire date is: 08/01/2004

$ Kim Fisher hire date is: 03/01/1997

$ Vanessa Arisson hire date is: 06/01/1991

$ Nate Arris hire date is: 05/01/1995

$ Paul Ellis hire date is: 09/01/1984

$ Billy Edouards hire date is: 11/01/1988

$ Tracy Cooper hire date is: 05/01/2003

$ Bob Arthur hire date is: 04/01/1985

$ Bill Jona hire date is: 12/01/1995

$ John Smith hire date is: 10/01/1980

$ Patrick Doe hire date is: 05/01/2000

+ ASIA: Dick Roberts needs to have a competence evaluation

+ EUROPE: Ed Matthews needs to have a competence evaluation

+ EUROPE: Kim Fisher needs to have a competence evaluation

+ EUROPE: Tracy Cooper needs to have a competence evaluation

+ EUROPE: Bill Jona needs to have a competence evaluation

+ EUROPE: Patrick Doe needs to have a competence evaluation

+ OCEANIA: Vanessa Arisson needs to have a competence evaluation

+ OCEANIA: Bob Arthur needs to have a competence evaluation

+ AMERICA: John Smith needs to have a competence evaluation

++ We need to adjust Bill Jona's position

Generate a ruleset archive and execute it. This can be done from within Eclipse by executing Ant default task or by executing ant all or just ant from the command line inside rulesetextraction_application.
Select the rulesetextraction_application project and click Run > External Tools > Run As > 1 Ant Build.

This will generate, parse, and execute the ruleset archive under output/extractionsample.jar in the same project. The Default Extractor is used as the extractor. Our build file will first generate a ruleset archive (extraction target) then execute it (execute target). The execution task calls RulesetExecution with the ruleset archive as a parameter. This class is defined in the rulesetextraction_application project.

You can have a look at the extractor defined in the project inside the Ruleset Extractors section of the project properties.

Try the different Ant tasks detailed below and see how the results differ depending on how the extractor is defined.

To run each example:

Click Run > Run > External Tools > Run As > 2 Ant Build
Select the Targets tab.
Click the check the box next to the appropriate target and clear all other target check boxes.
Click Run.

Only Extractor (target: extraction1):

This target uses a Custom Extractor (inside the rule project). No validator is used. The query returns only Europe rules.

Rules execution output:

> Ed Matthews works in Europe
> Kim Fisher works in Europe
> Tracy Cooper works in Europe
> Bill Jona works in Europe
> Patrick Doe works in Europe
+ EUROPE: Ed Matthews needs to have a competence evaluation
+ EUROPE: Kim Fisher needs to have a competence evaluation
+ EUROPE: Tracy Cooper needs to have a competence evaluation
+ EUROPE: Bill Jona needs to have a competence evaluation
+ EUROPE: Patrick Doe needs to have a competence evaluation

Only Validator (target: extraction2):

This target does not use an extractor, but one is generated in the code. No query is used. The validator Test Validator is used to discard the following rules from the generated ruleset archive:

rules with "test" in their names (Other HR Rules > Competence eval and Other HR Rules > hire test)
expired rules: where the value of the rule property expirationDate is before current date. (America HR Rules > employee)
rules containing the word "Oceania" in their definitions: (Oceania HR Rules > employee)
rules whose status property is set to defined or rejected.

(Asia HR Rules > employee: defined, Europe HR Rules > employee: inactive, Other HR Rules > Display hire dates: rejected)

Rules execution output:

> Mike Levy works in Africa

> Billy Edouards works in Africa

+ ASIA: Dick Roberts needs to have a competence evaluation

+ EUROPE: Ed Matthews needs to have a competence evaluation

+ EUROPE: Kim Fisher needs to have a competence evaluation

+ EUROPE: Tracy Cooper needs to have a competence evaluation

+ EUROPE: Bill Jona needs to have a competence evaluation

+ EUROPE: Patrick Doe needs to have a competence evaluation

+ OCEANIA: Vanessa Arisson needs to have a competence evaluation

+ OCEANIA: Bob Arthur needs to have a competence evaluation

+ AMERICA: John Smith needs to have a competence evaluation

++ We need to adjust Bill Jona's position

Existing Extractor + Redefine Extractor (target: extraction3):

This target uses a Custom Extractor defined inside the rule project and we set another query for the extractor. We do not use a validator. We replaced "Keep Europe rules only" by "Keep America rules only" in the extractor "Custom Extractor". Only rules in America HR Rules were executed. In this target, the build is forced before the ruleset archive is generated.

Note

Forcing the build is useful when the rule project is not built before the ruleset is extracted, or if the source of the rule project has changed and the build did not occur before ruleset extraction.

Rules execution output:

> Naomie Parker works in America
> John Smith works in America
+ AMERICA: John Smith needs to have a competence evaluation

Source Files

To display the source code of the rulesetextraction Eclipse plug-in:

Click File > Import.
In the Import Wizard, select External Plug-ins and Fragments then click Next.
In the Import As section, select the Projects with source folders option then click Next.
In the Plug-ins and Fragments Found list, scroll down and select the ilog.rules.studio.samples.rulesetextraction plug-in.

Warning

Be careful not to select ilog.rules.studio.samples.rulesetextraction.source.
Click Add, then click Finish.

The plug-in source code is imported and appears in the Rule Explorer.

Switch to the Plug-in Development perspective.
In the Package Explorer, navigate to the Java source files in the folder ilog.rules.studio.samples.rulesetextraction > src-rulesetextraction.

The following source files are of interest and are described below in the Highlights section of this sample:

ilog.rules.studio.samples.rulesetextraction.RulesetExtractor

ilog.rules.studio.samples.rulesetextraction.extractor.MyExtractorValidator

Highlights

The ruleset is extracted using the class ilog.rules.studio.samples.rulesetextraction.RulesetExtractor. This class is defined in the eclipse plug-in description file as an extension for org.eclipse.core.runtime.applications and implements org.eclipse.core.runtime.IPlatformRunnable.

It is executed as an Eclipse headless application using: ilog.rules.studio.samples.rulesetextraction.headless.application

This application expects the following mandatory parameters: