Samples > Rule Studio Authoring Extensions > How to Generate and Use a Custom Business Rule Language

How to Generate and Use a Custom Business Rule Language

PREVIOUS NEXT

This sample shows you how to extend Rule Studio with a new rule language and make it available for rule authoring. It also shows how to extend the default BAL to meet more advanced or specific needs.

Key Features

Key features include:

Installing 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 this sample.

To install the plug-in samples extension site:

  1. Click Help > Software Updates > Manage Configuration.
  2. In the Product Configuration dialog, click the Add an Extension Location link.
  3. In the Browse dialog, select the following folder: <InstallDir>/studio/samples/eclipse.
  4. If prompted to restart the Eclipse Workbench, click Yes.
    5. Eclipse shuts down and restarts.

To check that the Custom Business Rule Language Sample feature is enabled:

  1. Click Help > Software Updates > Manage Configuration.
  2. In the left pane of the Product Configuration page, expand C:\ILOG\JRules\studio\samples\eclipse and check that Custom Business Rule Language Sample 1.0.0. is listed.

You can now import the sample project files. However, as this sample installs a custom rule model that replaces the default rule model, it is strongly recommended that you install and run it in a separate workspace to avoid any unwanted impact on other rule projects in your default workspace.

To install the custombrl sample:

  1. Click File > Switch Workspace and specify a new workspace directory.
    2. Eclipse automatically shuts down and restarts with a blank workspace.
  2. Click File > Import.
  3. In the Import Wizard, select ILOG Rule Studio Samples and Tutorials.
  4. Click Next.
  5. On the Sample or Tutorial page, select the sample: samples > authoring > custombrl.
  6. Click Finish.
    7. The sample project files are imported and are displayed in the Rule Explorer.
  7. Click Window > Preferences.
  8. In the Preferences dialog, select ILOG Rule Studio > Rule Model Extension.
  9. Select Model: Default extension, click Change from Workspace and navigate to the file: custombrl-rules > data > custombrl.brmx.
  10. Click OK.
    11. A dialog reminds you that you must restart Eclipse to see the changes.
  11. Click File > Switch Workspace and click OK without changing the workspace location.
    12. Eclipse shuts down and restarts. The rule model extension is now taken into account by Rule Studio. You may have to rebuild the rule project for the extension to be taken into account in the rules.

Running this Sample

Before running the sample, you may want to examine the changes made to the rule model.

To examine the changes made to the rule model:

  1. In the custombrl-rules project, open the rule eventDisplay_useKindOf.
    2. The rule is defined as follows: 
definitions

  set event to a financial event ;

if 

  event is a kind of cash event 

then

  display "Start processing of a new CASH event: " + the description of event ;

else

  display "Start processing of a new FINANCIAL event: " + the description of event ;
The is kind of operator was added by the extended BAL to enable the creation of expressions that test whether a given value is an instance of a given class.
  1. Switch to the IRL view. Note how the expression is a kind of has generated an instanceOf test between the value and the BOM class corresponding to the term.
  2. Open the rule processDebitEventAmount_useNestedIfThenElse.
    3. The rule is defined as follows: 
definitions

    set 'debitevent' to a cash event

         where the type of this cash event is DEBIT ;

    set 'account' to an account

         where the account ID of debitevent is the ID of this account ;

    set 'amount' to ( - the amount of debitevent ) in the currency of
        debitevent converted to USD on the date of debitevent ;

    set 'balance' to the balance of account in the currency of account
        converted to USD on the current date ;

if

    balance is more than amount

then

    display "the following debit event is accepted " + the description of debitevent ;

else

    if amount - balance is more than 10000

    then :

        - report exception about debitevent 

            with text "Debit of more than $10000 over account balance: the

 debit event is refused"

        - retract debitevent

        - declare 'denial' as a financial event

        - set 'denial' to a new financial event with 

            type set to DENIAL , 

            account ID set to the ID of account , 

            parent ID set to the ID of debitevent , 

            date set to the date of debitevent

        - insert denial

    else :

        - if amount - balance is more than 2000

        then :

            - report exception about debitevent 

                with text "Debit of more than $2000 over account balance: an
                operator should watch all transactions on account"

            - if the currency of debitevent is not the currency of account

            then :

                - report exception about debitevent 

                    with text "Debit in foreign currency : double-check with
                   the customer" ,

        else :

            - report exception about debitevent 

                with text "Debit of less than $2000 over account balance:
                the debit event is accepted, but recorded" ;
The nested if/then/else constructs are supported in the actions of this extended BAL to enable the creation of complex text-based rules without the need to create several separate rules or a decision tree.
Note how a colon (:) is used to start the enumeration of actions after the then and else parts, a hyphen (-) is used to start each enumerated action, and a comma (,) is used to avoid any ambiguity in the nested constructs. This is the same syntax as that used in the standard foreach construct of the BAL.
  1. Switch to the IRL view and note how the corresponding if {} ... else {} blocks are generated in the actions.
  2. Open the rule processDenialEvent_useLocalVariables.
    3. The rule is defined as follows: 
definitions 

     set 'sourceEvent' to a financial event where the type of this
        financial event is DENIAL;

     set 'account' to an account where the account ID of sourceEvent
        is the ID of this account;

then

  declare 'acknowledge event' as a financial event ;

  set 'acknowledge event' to a new financial event with 

      type set to ACKNOWLEDGEMENT , 

      account ID set to the ID of account , 

      parent ID set to the ID of sourceEvent;

  set the date of 'acknowledge event' to the current date ; 

  insert 'acknowledge event' ;
The construction declare 'variable' as was added in this extended BAL to support the creation of local variables in actions. After such a declaration, the actions can initialize this variable and refer to it within the same lexical scope.
  1. Switch to the IRL view and note how a variable declaration is included in the actions: 
 sample.financial.FinancialEvent acknowledge_event;
  1. Rebuild the custombrl-rules project.

To run the sample:

  1. Click Run > Open Run Dialog.
  2. Select the custombrl-rules launch configuration, then click Run.
    3. The execution combines rules from the patternmatching-rules project, and the ones in the custombrl-rules project, because the latter references the first.
  3. Notice in the Console trace that instances of the three rules are executed:
    4. - the eventDisplay_useKindOf rule displays lines starting with Start processing of a new CASH event or Start processing of a new FINANCIAL event for each financial event inserted.
    - the processDebitEventAmount_useNestedIfThenElse rule generates DENIAL events and displays lines such as: 
###> Processing Exception : event DEBIT Event #ID2 Debit of more than $10000
 over account balance: the debit event is refused <###

###> Processing Exception : event DEBIT Event #ID5 Debit of more than $2000
 over account balance: an operator should watch all transactions on account <###

###> Processing Exception : event DEBIT Event #ID5 Debit in foreign currency :
 double-check with the customer <###
- the processDenialEvent_useLocalVariables rule generates ACKNOWLEDGEMENT events for DENIAL events.

Source Files

Source files for this sample are provided in the custombrl-rules project and in the custombrl Eclipse plug-in.

The following file is provided in the custombrl-rules project:

To display the source code of the custombrl sample plug-in:

  1. Click File > Import.
  2. In the Import Wizard, select Plug-ins and Fragments and click Next.
  3. In the Import As section, select the Projects with source folders option and click Next.
  4. In the Plug-ins and Fragments Found list, scroll down and select the ilog.rules.studio.samples.custombrl plug-in (be careful not to select ilog.rules.studio.samples.custombrl.source), then click Add.
  5. Click Finish.
    6. The source code of the plug-in is imported and appears in the Rule Explorer.
  6. Switch to the Plug-in Development perspective.
  7. In the Package Explorer, navigate to the Java source files:
    8. src/ilog/rules/studio/samples/custombrl:
    - ExtendedBAL.java The semantic context extension for the Extended BAL language
    - ExtendedBALCodeGeneratorExtender.java and ExtendedBALNodeTranslators.java The classes that manage the translation to IRL of the Extended BAL language
    src/ilog/rules/studio/samples/custombrl/resources/language:
    - extendedBAL.xsd, extendedBAL.properties The files that describe the new Extended BAL language: they include some description files of the standard BAL plus the following ones:
    - extendedExpr.xsd, extendedExpr.properties, extendedActions.xsd, extendedActions.properties

Highlights

In order to integrate a new language in Rule Studio, we must associate that new language (Extended BAL) to a new Business Rule type.

To declare that new Business Rule type we have to declare a rule model extension, which we named ExtendedActionRule

We associate the language to this new type using an annotation with id set to language and value set to language/extendedBAL, which is the language ID.

In order to declare the new language, we have to declare and implement an extension in the custombrl plug-in.

This extension implements the ilog.rules.studio.model.brl.languages extension point.

With this extension we declare a new language with its:

Related Concepts

Rule Model Extension Schema
Business Rule Language Definition Framework

Related Tasks

Defining Rule Model Extensions

Related Reference

Business Action Language
Rule Model Extension Editor

Related Samples and Tutorials

Import Samples and Tutorials Wizard
Copyright © 1987-2008 ILOG S.A. All rights reserved. Legal terms. Documentation homepage. PREVIOUS NEXT