第18章 Creating DRL rules in Business Central

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 in a DRL file

   package
   
   import
   
   function  // Optional
   
   query  // Optional
   
   declare   // Optional
   
   global   // Optional
   
   rule "rule name"
       // Attributes
       when
           // Conditions
       then
           // Actions
   end
   
   rule "rule2 name"
   
   ...

   Copy to Clipboard Toggle word wrap

   • 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 packageName.objectName, with multiple imports on separate lines.

     Importing data objects

     import org.mortgages.LoanApplication;

     Copy to Clipboard Toggle word wrap

   • function: (optional) Use this to include a function to be used by rules in the DRL file. Functions in DRL files put semantic code in your rule source file instead of in Java classes. 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 from a helper class 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
         // Empty
       then
         System.out.println( hello( "James" ) );
     end

     Copy to Clipboard Toggle word wrap

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

     import function my.package.applicant.hello;
     
     rule "Using a function"
       when
         // Empty
       then
         System.out.println( hello( "James" ) );
     end

     Copy to Clipboard Toggle word wrap

   • query: (optional) Use this to search the decision engine for facts related to the rules in the DRL file. You add the query definitions in DRL files and then obtain the matching results in your application code. 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.

     Example query definition in a DRL file

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

     Copy to Clipboard Toggle word wrap

     Example application code to obtain query results

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

     Copy to Clipboard Toggle word wrap

   • 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 Decision 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 decision 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

     Copy to Clipboard Toggle word wrap

   • global: (optional) Use this to include a global variable to be used by rules in the DRL file. Global variables typically provide data or services for the rules, such as application services used in rule consequences, and return data from rules, such as logs or values added in rule consequences. Set the global value in the working memory of the decision engine through a KIE session configuration or REST operation, declare the global variable above the rules in the DRL file, and then use it in an action (then) part of the rule. For multiple global variables, use separate lines in the DRL file.

     Setting the global list configuration for the decision engine

     List<String> list = new ArrayList<>();
     KieSession kieSession = kiebase.newKieSession();
     kieSession.setGlobal( "myGlobalList", list );

     Copy to Clipboard Toggle word wrap

     Defining the global list in a rule

     global java.util.List myGlobalList;
     
     rule "Using a global"
       when
         // Empty
       then
         myGlobalList.add( "My global list" );
     end

     Copy to Clipboard Toggle word wrap

     警告

     Do not use global variables to establish conditions in rules unless a global variable has a constant immutable value. Global variables are not inserted into the working memory of the decision engine, so the decision engine cannot track value changes of variables.

     Do not use global variables to share data between rules. Rules always reason and react to the working memory state, so if you want to pass data from rule to rule, assert the data as facts into the working memory of the decision engine.

   • 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. Each rule must have a unique name within the rule 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.

     Rule for loan application age limit

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

     Copy to Clipboard Toggle word wrap

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

     The following is an example DRL file in a loan application decision service:

     Example DRL file for a loan application

     package org.mortgages;
     
     import org.mortgages.LoanApplication;
     import org.mortgages.Bankruptcy;
     import org.mortgages.Applicant;
     
     rule "Bankruptcy history"
     	salience 10
     	when
     		$a : LoanApplication()
     		exists (Bankruptcy( yearOfOccurrence > 1990 || amountOwed > 10000 ))
     	then
     		$a.setApproved( false );
     		$a.setExplanation( "has been bankrupt" );
     		delete( $a );
     end
     
     rule "Underage"
     	salience 15
     	when
     		$application : LoanApplication()
     		Applicant( age < 21 )
     	then
     		$application.setApproved( false );
     		$application.setExplanation( "Underage" );
     		delete( $application );
     end

     Copy to Clipboard Toggle word wrap

     図18.1 Example DRL file for a loan application in Business Central

     

     View larger image

     
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.