Chapter 4. Creating DRL rules in Business Central

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

   Copy to Clipboard Toggle word wrap

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( )

     Copy to Clipboard Toggle word wrap

   • 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 )

     Copy to Clipboard Toggle word wrap

   • 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" )

     Copy to Clipboard Toggle word wrap

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.

     Copy to Clipboard Toggle word wrap

   • 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 )

     Copy to Clipboard Toggle word wrap

   • 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 ))

     Copy to Clipboard Toggle word wrap

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

     not (Applicant( age < 21 ))

     Copy to Clipboard Toggle word wrap

   • 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' ) )

     Copy to Clipboard Toggle word wrap

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

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

     Copy to Clipboard Toggle word wrap

   • 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"

     Copy to Clipboard Toggle word wrap

   • 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' ) )

     Copy to Clipboard Toggle word wrap

   • 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 )

     Copy to Clipboard Toggle word wrap
     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.

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.

     Copy to Clipboard Toggle word wrap

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

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

     Copy to Clipboard Toggle word wrap

   • 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 )
     }

     Copy to Clipboard Toggle word wrap

   • 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 )
     }

     Copy to Clipboard Toggle word wrap

   • 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 );

     Copy to Clipboard Toggle word wrap

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

     insert( new Applicant() );

     Copy to Clipboard Toggle word wrap

   • 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() );

     Copy to Clipboard Toggle word wrap
     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.