Red Hat Training

A Red Hat training course is available for Red Hat Process Automation Manager

Chapter 4. Creating DRL rules in Business Central

You can create and manage DRL rules for your project in Business Central. In each DRL rule file, you define rule conditions, actions, and other components related to the rule, based on the data objects you create or import in the package.

Procedure

  1. In Business Central, go to Menu → Design → Projects and click the project name.
  2. Click Add Asset → DRL file.

  3. Enter an informative DRL file name and select the appropriate Package. The package that you specify must be the same package where the required data objects have been assigned or will be assigned.

    You can also select Show declared DSL sentences if any domain specific language (DSL) assets have been defined in your project. These DSL assets will then become usable objects for conditions and actions that you define in the DRL designer.

  4. Click Ok to create the rule asset.

    The new DRL file is now listed in the DRL panel of the Project Explorer, or in the DSLR panel if you selected the Show declared DSL sentences option. The package to which you assigned this DRL file is listed at the top of the file.

  5. In the Fact types list in the left panel of the DRL designer, confirm that all data objects and data object fields (expand each) required for your rules are listed. If not, you can either import relevant data objects from other packages by using import statements in the DRL file, or create data objects within your package.

  6. After all data objects are in place, return to the Model tab of the DRL designer and define the DRL file with any of the following components:

    Components of a DRL file

    package  //automatic

import

function  //optional

query  //optional

declare   //optional

rule

rule

...

    • package: (automatic) This was defined for you when you created the DRL file and selected the package.

    • import: Use this to identify the data objects from either this package or another package that you want to use in the DRL file. Specify the package and data object in the format package.name.object.name, one import per line.

      Importing data objects

      import mortgages.mortgages.LoanApplication;

    • function: (optional) Use this to include a function to be used by rules in the DRL file. Functions put semantic code in your rule source file. Functions are especially useful if an action (then) part of a rule is used repeatedly and only the parameters differ for each rule. Above the rules in the DRL file, you can declare the function or import a static method as a function, and then use the function by name in an action (then) part of the rule.

      Declaring and using a function with a rule (option 1)

      function String hello(String applicantName) {
    return "Hello " + applicantName + "!";
}

rule "Using a function"
  when
    eval( true )
  then
    System.out.println( hello( "James" ) );
end

      Importing and using the function with a rule (option 2)

      import function my.package.applicant.hello;

rule "Using a function"
  when
    eval( true )
  then
    System.out.println( hello( "James" ) );
end

    • query: (optional) Use this to search the process engine for facts related to the rules in the DRL file. Queries search for a set of defined conditions and do not require when or then specifications. Query names are global to the KIE base and therefore must be unique among all other rule queries in the project. To return the results of a query, construct a traditional QueryResults definition using ksession.getQueryResults("name"), where "name" is the query name. This returns a list of query results, which enable you to retrieve the objects that matched the query. Define the query and query results parameters above the rules in the DRL file.

      Query and query results for people under the age of 21, with a rule

      query "people under the age of 21"
    person : Person( age < 21 )
end

QueryResults results = ksession.getQueryResults( "people under the age of 21" );
System.out.println( "we have " + results.size() + " people under the age  of 21" );

rule "Underage"
  when
    application : LoanApplication( )
    Applicant( age < 21 )
  then
    application.setApproved( false );
    application.setExplanation( "Underage" );
end

    • declare: (optional) Use this to declare a new fact type to be used by rules in the DRL file. The default fact type in the java.lang package of Red Hat Process Automation Manager is Object, but you can declare other types in DRL files as needed. Declaring fact types in DRL files enables you to define a new fact model directly in the process engine, without creating models in a lower-level language like Java.

      Declaring and using a new fact type

      declare Person
  name : String
  dateOfBirth : java.util.Date
  address : Address
end

rule "Using a declared type"
  when
    $p : Person( name == "James" )
  then   // Insert Mark, who is a customer of James.
    Person mark = new Person();
    mark.setName( "Mark" );
    insert( mark );
end

    • rule: Use this to define each rule in the DRL file. Rules consist of a rule name in the format rule "name", followed by optional attributes that define rule behavior (such as salience or no-loop), followed by when and then definitions. The same rule name cannot be used more than once in the same package. The when part of the rule contains the conditions that must be met to execute an action. For example, if a bank requires loan applicants to have over 21 years of age, then the when condition for an Underage rule would be Applicant( age < 21 ). The then part of the rule contains the actions to be performed when the conditional part of the rule has been met. For example, when the loan applicant is under 21 years old, the then action would be setApproved( false ), declining the loan because the applicant is under age. Conditions (when) and actions (then) consist of a series of stated fact patterns with optional constraints, bindings, and other supported DRL elements, based on the available data objects in the package. These patterns determine how defined objects are affected by the rule.

      Rule for loan application age limit

      rule "Underage"
  salience 15
  dialect "mvel"
  when
    application : LoanApplication( )
    Applicant( age < 21 )
  then
    application.setApproved( false );
    application.setExplanation( "Underage" );
end

      At minimum, each DRL file must specify the package, import, and rule components. All other components are optional.

      Figure 4.1. Sample DRL file with required components and optional rule attributes

      Sample DRL file with required components
  7. After you define all components of the rule, click Validate in the upper-right toolbar of the DRL designer to validate the DRL file. If the file validation fails, address any problems described in the error message, review all syntax and components in the DRL file, and try again to validate the file until the file passes.
  8. Click Save in the DRL designer to save your work.

For more details about adding conditions to DRL rules, see Section 4.1, “Adding WHEN conditions in DRL rules”.

For more details about adding actions to DRL rules, see Section 4.2, “Adding THEN actions in DRL rules”.

4.1. Adding WHEN conditions in DRL rules

The when part of the rule contains the conditions that must be met to execute an action. For example, if a bank requires loan applicants to have over 21 years of age, then the when condition of an Underage rule would be Applicant( age < 21 ). Conditions consist of a series of stated patterns and constraints, with optional bindings and other supported DRL elements, based on the available data objects in the package.

Prerequisites

  • The package is defined at the top of the DRL file. This should have been done for you when you created the file.
  • The import list of data objects used in the rule is defined below the package line of the DRL file. Data objects can be from this package or from another package in Business Central.
  • The rule name is defined in the format rule "name" below the package, import, and other lines that apply to the entire DRL file. The same rule name cannot be used more than once in the same package. Optional rule attributes (such as salience or no-loop) that define rule behavior are below the rule name, before the when section.

Procedure

  1. In the DRL designer, enter when within the rule to begin adding condition statements. The when section consists of zero or more fact patterns that define conditions for the rule.

    If the when section is empty, then actions in the then section are executed every time a fireAllRules() call is made in the process engine. This is useful if you want to use rules to set up the process engine state.

    Rule without conditions

    rule "bootstrap"
  when   // empty

  then   // actions to be executed once
    insert( new Applicant() );
end

// The above rule is internally rewritten as:

rule "bootstrap"
  when
    eval( true )
  then
    insert( new Applicant() );
end

  2. Enter a pattern for the first condition to be met, with optional constraints, bindings, and other supported DRL elements. A basic pattern format is patternBinding : patternType ( constraints ). Patterns are based on the available data objects in the package and define the conditions to be met in order to trigger actions in the then section.

    • Simple pattern: A simple pattern with no constraints matches against a fact of the given type. For example, the following condition is only that the applicant exists. 

      when
  Applicant( )

    • Pattern with constraints: A pattern with constraints matches against a fact of the given type and the additional restrictions in parentheses that are true or false. For example, the following condition is that the applicant is under the age of 21. 

      when
  Applicant( age < 21 )

    • Pattern with binding: A binding on a pattern is a shorthand reference that other components of the rule can use to refer back to the defined pattern. For example, the following binding a on LoanApplication is used in a related action for underage applicants. 

      when
  a : LoanApplication( )
  Applicant( age < 21 )
then
  a.setApproved( false );
  a.setExplanation( "Underage" )

  3. Continue defining all condition patterns that apply to this rule. The following are some of the keyword options for defining DRL conditions:

    • and: Use this to group conditional components into a logical conjunction. Infix and prefix and are supported. By default, all listed conditions or actions are combined with and when no conjunction is specified. 

      a : LoanApplication( ) and Applicant( age < 21 )

a : LoanApplication( )
and Applicant( age < 21 )

a : LoanApplication( )
Applicant( age < 21 )

// All of the above are the same.

    • or: Use this to group conditional components into a logical disjunction. Infix and prefix or are supported. 

      Bankruptcy( amountOwed == 100000 ) or IncomeSource( amount == 20000 )

Bankruptcy( amountOwed == 100000 )
or IncomeSource( amount == 20000 )

    • exists: Use this to specify facts and constraints that must exist. Note that this does not mean that a fact exists, but that a fact must exist. This option is triggered on only the first match, not subsequent matches. 

      exists ( Bankruptcy( yearOfOccurrence > 1990 || amountOwed > 10000 ) )

    • not: Use this to specify facts and constraints that must not exist. 

      not ( Applicant( age < 21 ) )

    • forall: Use this to set up a construct where all facts that match the first pattern match all the remaining patterns. 

      forall( app : Applicant( age < 21 )
              Applicant( this == app, status = 'underage' ) )

    • from: Use this to specify a source for data to be matched by the conditional pattern. 

      Applicant( ApplicantAddress : address )
Address( zipcode == "23920W" ) from ApplicantAddress

    • entry-point: Use this to define an Entry Point corresponding to a data source for the pattern. Typically used with from. 

      Applicant( ) from entry-point "LoanApplication"

    • collect: Use this to define a collection of objects that the construct can use as part of the condition. In the example, all pending applications in the process engine for each given mortgage are grouped in ArrayLists. If three or more pending applications are found, the rule is executed. 

      m : Mortgage()
a : ArrayList( size >= 3 )
    from collect( LoanApplication( Mortgage == m, status == 'pending' ) )

    • accumulate: Use this to iterate over a collection of objects, execute custom actions for each of the elements, and return one or more result objects (if the constraints evaluate to true). This option is a more flexible and powerful form of collect. Use the format accumulate( <source pattern>; <functions> [;<constraints>] ). In the example, min, max, and average are accumulate functions that calculate the minimum, maximum and average temperature values over all the readings for each sensor. Other supported functions include count, sum, variance, standardDeviation, collectList, and collectSet. 

      s : Sensor()
accumulate( Reading( sensor == s, temp : temperature );
            min : min( temp ),
            max : max( temp ),
            avg : average( temp );
            min < 20, avg > 70 )
      Advanced DRL options

      These are examples of basic keyword options and pattern constructs for defining conditions. For more advanced DRL options and syntax supported in the DRL designer, see the Drools Documentation online.

  4. After you define all condition components of the rule, click Validate in the upper-right toolbar of the DRL designer to validate the DRL file. If the file validation fails, address any problems described in the error message, review all syntax and components in the DRL file, and try again to validate the file until the file passes.
  5. Click Save in the DRL designer to save your work.

4.2. Adding THEN actions in DRL rules

The then part of the rule contains the actions to be performed when the conditional part of the rule has been met. For example, when a loan applicant is under 21 years old, the then action of an Underage rule would be setApproved( false ), declining the loan because the applicant is under age. Actions execute consequences based on the rule conditions and on available data objects in the package.

Prerequisites

  • The package is defined at the top of the DRL file. This should have been done for you when you created the file.
  • The import list of data objects used in the rule is defined below the package line of the DRL file. Data objects can be from this package or from another package in Business Central.
  • The rule name is defined in the format rule "name" below the package, import, and other lines that apply to the entire DRL file. The same rule name cannot be used more than once in the same package. Optional rule attributes (such as salience or no-loop) that define rule behavior are below the rule name, before the when section.

Procedure

  1. In the DRL designer, enter then after the when section of the rule to begin adding action statements.

  2. Enter one or more actions to be executed on fact patterns based on the conditions for the rule.

    The following are some of the keyword options for defining DRL actions:

    • and: Use this to group action components into a logical conjunction. Infix and prefix and are supported. By default, all listed conditions or actions are combined with and when no conjunction is specified. 

      application.setApproved ( false ) and application.setExplanation( "has been bankrupt" );

application.setApproved ( false );
and application.setExplanation( "has been bankrupt" );

application.setApproved ( false );
application.setExplanation( "has been bankrupt" );

// All of the above are the same.

    • set: Use this to set the value of a field. 

      application.setApproved ( false );
application.setExplanation( "has been bankrupt" );

    • modify: Use this to specify fields to be modified for a fact and to notify the process engine of the change. 

      modify( LoanApplication ) {
        setAmount( 100 )
}

    • update: Use this to specify fields and the entire related fact to be modified and to notify the process engine of the change. After a fact has changed, you must call update before changing another fact that might be affected by the updated values. The modify keyword avoids this added step. 

      update( LoanApplication ) {
        setAmount( 100 )
}

    • delete: Use this to remove an object from the process engine. The keyword retract is also supported in the DRL designer and executes the same action, but delete is preferred for consistency with the keyword insert. 

      delete( LoanApplication );

    • insert: Use this to insert a new fact and define resulting fields and values as needed for the fact. 

      insert( new Applicant() );

    • insertLogical: Use this to insert a new fact logically into the process engine and define resulting fields and values as needed for the fact. The Red Hat Process Automation Manager process engine is responsible for logical decisions on insertions and retractions of facts. After regular or stated insertions, facts have to be retracted explicitly. After logical insertions, facts are automatically retracted when the conditions that originally asserted the facts are no longer true. 

      insertLogical( new Applicant() );
      Advanced DRL options

      These are examples of basic keyword options and pattern constructs for defining actions. For more advanced DRL options and syntax supported in the DRL designer, see the Drools Documentation online.

  3. After you define all action components of the rule, click Validate in the upper-right toolbar of the DRL designer to validate the DRL file. If the file validation fails, address any problems described in the error message, review all syntax and components in the DRL file, and try again to validate the file until the file passes.
  4. Click Save in the DRL designer to save your work.

4.2.1. Rule attributes

Rule attributes are additional specifications that you can add to business rules to modify rule behavior. The following table lists the names and supported values of the attributes that you can assign to rules:

Table 4.1. Rule attributes

AttributeValue

salience

An integer defining the priority of the rule. Rules with a higher salience value are given higher priority when ordered in the activation queue.

Example: salience 10

enabled

A Boolean value. When the option is selected, the rule is enabled. When the option is not selected, the rule is disabled.

Example: enabled true

date-effective

A string containing a date and time definition. The rule can be activated only if the current date and time is after a date-effective attribute.

Example: date-effective "4-Sep-2018"

date-expires

A string containing a date and time definition. The rule cannot be activated if the current date and time is after the date-expires attribute.

Example: date-expires "4-Oct-2018"

no-loop

A Boolean value. When the option is selected, the rule cannot be reactivated (looped) if a consequence of the rule re-triggers a previously met condition. When the condition is not selected, the rule can be looped in these circumstances.

Example: no-loop true

agenda-group

A string identifying an agenda group to which you want to assign the rule. Agenda groups allow you to partition the agenda to provide more execution control over groups of rules. Only rules in an agenda group that has acquired a focus are able to be activated.

Example: agenda-group "GroupName"

activation-group

A string identifying an activation (or XOR) group to which you want to assign the rule. In activation groups, only one rule can be activated. The first rule to fire will cancel all pending activations of all rules in the activation group.

Example: activation-group "GroupName"

duration

A long integer value defining the duration of time in milliseconds after which the rule can be activated, if the rule conditions are still met.

Example: duration 10000

timer

A string identifying either int (interval) or cron timer definition for scheduling the rule.

Example: timer "*/5 * * * *" (every 5 minutes)

calendar

A Quartz calendar definition for scheduling the rule.

Example: calendars "* * 0-7,18-23 ? * *" (exclude non-business hours)

auto-focus

A Boolean value, applicable only to rules within agenda groups. When the option is selected, the next time the rule is activated, a focus is automatically given to the agenda group to which the rule is assigned.

Example: auto-focus true

lock-on-active

A Boolean value, applicable only to rules within rule flow groups or agenda groups. When the option is selected, the next time the ruleflow group for the rule becomes active or the agenda group for the rule receives a focus, the rule cannot be activated again until the ruleflow group is no longer active or the agenda group loses the focus. This is a stronger version of the no-loop attribute, because the activation of a matching rule is discarded regardless of the origin of the update (not only by the rule itself). This attribute is ideal for calculation rules where you have a number of rules that modify a fact and you do not want any rule re-matching and firing again.

Example: lock-on-active true

ruleflow-group

A string identifying a rule flow group. In rule flow groups, rules can fire only when the group is activated by the associated rule flow.

Example: ruleflow-group "GroupName"

dialect

A string identifying either JAVA or MVEL as the language to be used for code expressions in the rule. By default, the rule uses the dialect specified at the package level. Any dialect specified here overrides the package dialect setting for the rule.

Example: dialect "JAVA"

Note

When you use Red Hat Process Automation Manager without the executable model, the dialect "JAVA" rule consequences support only Java 5 syntax. For more information about executable models, see Packaging and deploying a Red Hat Process Automation Manager project.