Introduction

Part 1 of this series introduced the Generic Ruleset Signature pattern (GRS). The GRS pattern enables agile changes of rule parameters using a hash map. In Part 2, we'll "battle-harden" the original sample. This article is divided into three sections. The first section explains how GRS makes parameter changes more agile; the second section gives an overview of the improvements we've made to the original GRS; the third section provides a tutorial on how to use it.

Back to top

Making parameters agile

This section explains why the traditional way of adding parameters in WebSphere Operational Decision Management lacks flexibility and describes how using GRS can improve agility.

The problem

To illustrate the problem of adding parameters, let's take the simple share trading system shown in Figure 1. This system takes a single input parameter called StockName and, depending on its value, decides to BUY or SELL.

Consider what happens when adding a second input parameter called StockPrice, as shown in Figure 2.

This is a disruptive change, requiring the following steps, as shown in Figure 3:

1. Add the parameter to the rule project.
2. Synchronize change from the Rule Designer to the Decision Center.
3. Create the business rule.
4. Regenerate the Decision Validation Services model.
5. Create and run the DVS test.
6. Deploy to the Decision Server.
7. Rebuild the client interface.

Simplifying parameter changes using GRS

You can add parameters using GRS in just five steps. All the steps can be done entirely within Decision Center, so Rule Designer is not required:

1. Add the parameter to the Excel dynamic domain.
2. Refresh the BOM.
3. Create the business rule using the parameter.
4. Create and run the DVS test.
5. Deploy to the Decision Server.

Figure 4 illustrates these five steps. The assumption is that the client application is intelligent and can dynamically handle parameter changes. If this is not the case, you would need to add a a step 6 to rebuild the client.

Back to top

The GRS framework revisited

Now that we've reviewed the advantages of using the GRS patterns, let's discuss how we have improved the original implementation presented in Part 1.

Dynamic domains

In Part 1, we used strings for parameter names and values. This approach is error-prone and not a best practice. See the strings circled in Figure 5.

A better approach is to use dynamic domains. Dynamic domains constrain the rule author to a list of values to avoid mistyping. In our share trading example, we use dynamic domains for both parameter names and string values. The improved rule using domains is shown in Figure 6.

Domains are implemented using the new Excel Dynamic Domains feature in WebSphere Operational Decision Management V7.5.

Type checking

One of the problems with the approach in Part 1 was that parameter types could be confused. In the following example, we have written a rule that accidentally uses the stockName parameter when it should be using stockPrice. This error would only be spotted at runtime, when a class cast exception would occur when casting from a String to an Integer. See the rule in Figure 7 with the error circled.

To fix this in our battle-hardened GRS, we introduce the concept of parameter types. Each parameter type is defined within a domain. In the share trading example, we define domains for common primitive types, as shown in Figure 8.

As you can see, among the parameters defined are the decimal parameter called stockPrice and the string parameters called response and stockName. It is now impossible to mix decimal and string parameters, as shown in Figure 9.

Error handling

One of the most useful improvements of the battle-hardened GRS is its ability to perform runtime parameter checking. In the original GRS framework passing an empty parameter caused a null pointer exception. This is fixed in the battle-hardened GRS by introducing parameter validation decision tables that check the parameters. The validation tables are called before the business rules are invoked. See the parameters defined in Figure 10.

The validation tables verify all required input parameters have been supplied and that they are of the correct type. For example, if stockPrice was missing the following error would be returned:
Error code 1: Missing Decimal Parameter stockPrice

Missing parameters are assigned a default value. In Figure 10, the default value for stockPrice is 0. Default values are useful in allowing rules to continue to run without throwing an exception.

If the parameter stockPrice was given the wrong type (for example, a String rather than a Decimal), the following error would be returned:
Error code 2: Expected Decimal in stockPrice, found String

Again the default value is used instead of the supplied one in order for the rules to run successfully.

Regarding output parameters, only those parameters marked explicitly as output will be passed out from the rule engine. In Figure 10, the only output parameter is response.

DVS testing

Decision Validation Services (DVS) is the tool provided by WebSphere Operational Decision Management to test your business rules. DVS works well with a stable and simple object model, but there is a problem when the object model changes; the DVS Excel scenario file has to be regenerated, which wipes out previous test data. A cut and paste from the old to the new spreadsheet can salvage existing test data, but if the object model changes significantly this is not always possible. When using GRS, there is no need to regenerate the Excel scenario file when a parameter is added or removed. All you need to do is add or remove a row in the spreadsheet. This makes DVS testing significantly more agile.

For the share trading project, the DVS test scenario is a stockName of IBM and stockPrice of 200, as shown in Figure 11.

The expected result is a response of BUY, as shown in Figure 12.

When DVS is run, it produces the report shown in Figure 13.

Consider a change to the share trading project in which the customer wants to know how much profit is made on selling stock. You would need to add an integer input parameter called sharesHeld and a decimal output parameter called profit, as shown in Figure 14.

You would also need to change the business rule to calculate profit, as shown in Figure 15.

The existing DVS scenario is enhanced with a sharesHeld test value of 50, as shown in Figure 16. Note that unlike traditional use of DVS, you did not have to regenerate the Excel Scenario file in order to add this new parameter.

The expected results are enhanced with profit, as shown in Figure 17. Note again that we did not have to regenerate the Excel Scenario file in order to add this new parameter.

Now when the DVS test is re-run the test report reflects the test for the profit as well as the BUY decision, as shown in Figure 18.

Calling GRS via an HTDS web service

Now we'll turn our attention to how to invoke GRS from a Hosted Transparent Decision Service (HTDS) web service. As already been discussed, the underlying input/output parameters to GRS are based on a Java™ HashMap. But how do we preserve the flexible nature of the HashMap when calling from a web service? The answer lies in using a meta-model defining the parameters without explicitly naming them. The explicit naming of variables is made within the XML payload, thereby allowing variables to be declared at runtime. To go back to the share trading example, a concrete XSD would fix the parameters as shown in Figure 19.

The concrete payload associated with this XSD is shown in Listing 1.

<shareTrader >
	<stockName>IBM</stockName>
	<stockPrice>100</stockPrice>
</shareTrader>

This is not flexible because the schema would have to be changed in order to accommodate new parameters. A more flexible way is to define the XSD as a metamodel as shown in Figure 20.

Now the XML request payload rather than the XSD contains the names of the parameters and their types. Listing 2 shows the metadata XML payload.

<rpx:GrsRequest>
	<rpx:RequestId>0</rpx:RequestId>
	<rpx:NamedFields>
		      <rpx:NamedField Name="stockName" Value="IBM" DataType="String"/>
	          <rpx:NamedField Name="stockPrice" Value="100" DataType="Double"/>
    </rpx:NamedFields>
</rpx:GrsRequest>

Listing 3 shows the response payload.

<rpx:GrsResponse>
	<rpx:RequestId>0</rpx:RequestId>
	<rpx:NamedFields>
		<rpx:NamedField Name="response" Value="BUY”  DataType="String"/>	
	</rpx:NamedFields>
</rpx:GrsResponse>

Back to top

Using GRS: A step-by-step tutorial

This section walks you through the steps of using the GRS pattern. It includes the following sections:

1. Adding GRS parameters in Rule Designer
2. Adding GRS parameters in Decision Center
3. Invoking GRS from a web service using Decision Server

Adding GRS parameters in Rule Designer

To add GRS parameters in Rule Designer, complete the following steps:

1. Download the GRS reference implementation.
2. Unzip the GRS files and import the existing projects into a clean workspace within Rule Designer.

   You should see the projects shown in Figure 21.

   
   
   Figure 21. GRS projects
   
   
   

   All projects should be built without errors. There are two warnings which can be ignored.

3. To run GRS from Rule Designer using Java, find RuleEngineRunner.java within the grs-simple-tester project. An excerpt of the Java code from RuleEngineRunner.java is shown in Listing 4. At line 2 the parameter hash-map is created. At lines 5 and 6 two input parameters stockName and stockPrice are loaded into the hash-map. At line 9 the hash-map is set as the input parameter to the rule engine. The rules are executed at line 12. The execution response is fetched at line 15. If there are any errors they are fetched at line 18.

1	// create the input parameter hashmap
2	java.util.Map<String, Object> vars = new java.util.HashMap<String, Object>();
3
4      // Create the input variables
5	vars.put("stockName", "IBM");	
6	vars.put("stockPrice", new Double(100));  	    
7	
8       // Set the request	
9	runner.inputs.setParameter("request", vars);
10
11	// Execute the rules
12	runner.executeRules();
13
14      // Get the response
15	java.util.Map response = runner.getOutputResult().getObjectValue("response");
16
17	// Get the errors (if any)
18	java.util.List errors = runner.getOutputResult().getObjectValue("errorList"); 

5. To run this program, select Run => Run Configurations and then select grs-simple-tester, then click Run, as shown in Figure 22.
   
   Figure 22. Run configurations
   
   
   

   The result should be successful. The input parameters were stockName and stockPrice and the output parameter was response, as shown in Listing 5.

Request = {stockName=IBM, stockPrice=100.0}
Response = BUY
Errors = []

6. Now we'll add an input parameter called sharesHeld to the framework. In the Resources folder of the grs-bom project, edit Domains.xls using Excel outside the Eclipse environment, as shown in Figure 23.
   
   Figure 23. Domains file in BOM project
   
   
   
7. In Excel, go to the Integer tab and replace myIntParam with sharesHeld. You only need to type the name in column A for the other columns to be updated. See Figure 24.
   
   Figure 24. Integer tab
   
   
   
8. Save the Excel file. Open the grs-bom project, then right-click and refresh the Resources folder to pick up the Excel changes.
9. Now select the IntegerParameter class within the dynamic domains section of the BOM.
10. Click Create a domain, as shown in Figure 25.
    
    Figure 25. Create a domain
    
    
    
11. Select the Excel Dynamic Domain and click Next, as shown in Figure 26.
    
    Figure 26. Select Excel Dynamic Domain
    
    
    
12. Select the Domains Excel file and values, as shown in Figure 27. Make sure to check Table with headers and the Integer sheet, then click Finish and then Ctrl+S to save.
    
    Figure 27. Excel Domain settings
    
    
    
13. The sharesHeld parameter is now defined as a domain value. You now need to declare it in the parameters table as an integer input parameter. To do this, open the IntegerParameters table, as shown in Figure 28.
    
    Figure 28. GRS projects
    
    
    
14. Add the integer parameter to the decision table so that it looks like Figure 29. Ensure Input is set to true and Output is set to false.
    
    Figure 29. Adding an integer parameter
    
    
    
15. Now you need to change the business rule to use the new parameter. To do this, edit the BuyRule in the grs-rules project, as shown in Figure 30, and click Ctrl+S save the project.
    
    Figure 30. Using an integer parameter
    
    
    
16. Run the grs-simple-tester again. You should see the result shown in Listing 6.

Request = {stockName=IBM, stockPrice=100.0}
Response = BUY
Errors = [{value=null, errorCode=1, paramType=Integer, name=sharesHeld, 
errorMessage=Missing input var}] 

17. The error is expected because we have not yet changed the Java code to supply the sharesHeld parameter. Note that the rules still ran and returned a result of BUY. The reason for this is that a default value of sharesHeld was set to 0 in the parameters table.

    To fix the error, edit RuleEngineRunner.java in the grs-simple-tester project. On line 169, add the line in bold in Listing 7.

java.util.Map&lt;String, Object> vars = new java.util.HashMap<String, Object>();
	
vars.put("stockName", "IBM");
vars.put("stockPrice", new Double(100));
vars.put("sharesHeld", new Integer(10));
	    
System.out.println("Request = " + vars);
runner.inputs.setParameter("request", vars);

// Execute the rules
runner.executeRules();

18. Now run grs-simple-tester again. You should see the following successful result:
    Response = BUY.
19. Now run the same GRS rules using DVS. In the grs-ruleflow-dvs project, edit testsuite.xlsx using Excel outside the Eclipse environment, as shown in Figure 31.
    
    Figure 31. DVS testsuite file
    
    
    
20. Examine the inputs and outputs to the test, as shown in Figures 32 and 33.
    
    Figure 32. GRS scenario input data
    
    
    
    
    Figure 33. Scenario expected results
    
    
    
21. To run the DVS test, select Run => Run Configurations, then select GrsDvsTester, as shown in Figure 34. Click Run to execute the tests.
    
    Figure 34. DVS Run Configurations
    
    
    
22. To view the test results, right-click the grs-rulowflow-dvs project and click Refresh. You should see report.html appear in the top-level grs-ruleflow-dvs folder. Open the HTML file in a web browser. The success report in Figure 35 is displayed.
    
    Figure 35. DVS execution report
    
    
    

Adding a parameter in Decision Center

This section describes how to add a new Integer parameter called stockPrice in Decision Center.

1. In Rule Designer, synchronize the GRS rule projects to Decision Center.
2. Log in to Decision Center and open the grs-bom project.
3. Click the Compose tab and create a new Smart Folder. Call the folder Resources and click Next.
4. Change the query to Find all resources and click Finish.
5. In the Resources Smart Folder, save Domains.xls to a temporary folder and edit it, as shown in Figure 36.
   
   Figure 36. Domains Excel file
   
   
   
6. On the Decimal tab, add a new a decimal parameter called profit as shown in Figure 37.
   
   Figure 37. Add decimal parameter
   
   
   
7. Save the spreadsheet to a temporary folder, then click Browse to upload the same file. It's important to reopen the file to verify the changes have been uploaded successfully. If not, repeat the import.
8. On the Project tab, select Reload Dynamic Domains, as shown in Figure 38.
   
   Figure 38. Reload dynamic domains
   
   
   

   You should see the message shown in Figure 39.

   
   
   Figure 39. Successful reload of dynamic domains
   
   
   
9. Edit the Decimal Parameters table shown in Figure 40.
   
   Figure 40. Decimal parameters table
   
   
   
10. Add the profit parameter as shown in Figure 41. Ensure that the Input flag is false and the output flag is true. Press Finish.
    
    Figure 41. Adding profit
    
    
    
11. Now create a new rule based on the profit output parameter. Within the Decision Center Home tab, open the grs-rules project. In the Explore tab, edit the BuyRule, as shown in Figure 42.
    
    Figure 42. BUY rule
    
    
    
12. Amend the Buy Rule with the additional action circled in red shown in Figure 43.
    
    Figure 43. Amended BUY rule
    
    
    
13. Now create the DVS test. On the Home tab, select the grs-ruleflow-dvs project. On the Compose tab select Test Suite and click OK. Set the name of the DVS test suite to GRS Test. Press Next until you come to Step 3. Click Browse and select testsuite.xls in the grs-ruleflow-dvs folder on your file system. Click Finish and Run. After a few moments, you should see the failed test screen shown in Figure 44.
    
    Figure 44. Failed DVS test
    
    
    
14. The reason this test failed is that the additional output parameter profit is not being tested. To fix, edit testsuite.xlsx within the grs-ruleflow-dvs folder on your file system. On the Expected Results tab, change the expected result as shown in Figure 45.
    
    Figure 45. Fix expected result
    
    
    
15. Now import the changed Excel file by editing the Test Suite and in Step 3: Scenarios, re-import the Excel file using Browse. Now re-run the test suite and the output should be successful, as shown in Figure 46.
    
    Figure 46. Successful DVS test result
    
    
    

Invoking GRS from a web service

This section shows you how to deploy the GRS project to Decision Server and then run it from HTDS.

1. Log in to Decision Center and open the grs-ws project, as shown in Figure 47.
   
   Figure 47. The GRS web service project
   
   
   
2. On the Configure tab, select Manage Ruleapps, then create a new RuleApp with a name of GrsWsApp and a ruleset with a name of GrsRuleset. Ensure that the project is grs-ws, as shown in Figure 48.
   
   Figure 48. GRS projects
   
   
   
3. Click Save and then Save again, then deploy the RuleApp to Decision Server. You should see the "Deployment Succeeded" message shown in Figure 49.
   
   Figure 49. Deployment succeeded
   
   
   
4. To get the URL of the GRS web service, first log in to Decision Server. Go to the Explorer tab and select GrsRuleset/1.0 under the RuleApps/grsWsApp/1.0 branch. Then click Show HTDS WSDL Options and select Retrieve HTDS WSDL File, as shown in Figure 50.
   
   Figure 50. GRS WSDL
   
   
   
5. Select the latest ruleset version and then view and copy the WSDL URL. The URL should look something like this:
   http://localhost:9083/DecisionService/ws/GrsWsApp/1.0/GrsRuleset?WSDL
6. To invoke the HTDS web service using Eclipse, return to the Rule Designer and open the Web perspective.
7. From the Run menu, select Launch the Web Services Explorer as shown in Figure 51.
   
   Figure 51. Launch Web Services Explorer
   
   
   
8. When the Web Services Explorer window opens, click the WSDL Page link in the upper right, then click WSDL Main in the Navigator box. Finally paste the URL of the ShareTraderHTDS WSDL into the WSDL URL field, as shown in Figure 52, and click Go.
   
   Figure 52. Web Services Explorer
   
   
   
9. Click GrsRuleset, as shown in Figure 53.
   
   Figure 53. GRS projects
   
   
   
10. Click source, as shown in Figure 54.
    
    Figure 54. Select Source
    
    
    
11. Paste the payload in Listing 8 into the soapenv body (not the header).

<q0:GrsRulesetRequest>
  <q2:request> 
    <q1:GrsRequest>
      <q1:RequestId>0</q1:RequestId>
	<q1:NamedFields>
	  <q1:NamedField Name="stockPrice" Value="100" DataType="Double"/>
	  <q1:NamedField Name="sharesHeld" Value="10" DataType="Integer"/>
	  <q1:NamedField Name="stockName" Value="IBM" DataType="String"/>
	</q1:NamedFields>
      </q1:GrsRequest>
   </q2:request>
</q0:GrsRulesetRequest>

12. Click Go. In the Status frame, click source. You should see the request payload and the successful response in the status frame, as shown in Figure 55.
    
    Figure 55. GRS Soap request and response
    
    
    

Back to top

Conclusion

Congratulations! You've now completed the GRS tutorial. In Part 3 of this series, you'll learn about applying the GRS pattern to big data using a Hadoop prototype, including best practices for applying rules to massive amounts of unstructured data.

A more in-depth tutorial on how to extend the original GRS sample from Part 1 is included for download with this article.

Back to top

Acknowledgements

The authors would like to thank Dan Selman and Jerome Boyer for reviewing Part 1 of this series, and Alain Robert and Ben Cornwell for reviewing Part 2.

Back to top

Downloads

Information about download methods

Resources

• This article does not discuss the use of BOM classes based on Maps, or synthetic objects. For more information on this pattern, refer to Creating intermediate facts in WebSphere ILOG JRules using synthetic objects (developerWorks, 2010)
  
  
• For a full list of Java primitive wrapper classes, refer to the wikipedia Primitive wrapper class topic.
  
  
• developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
  
  
• IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.
  
  

About the authors

Nigel T. Crowther is a Senior IT Consultant in the IBM Software Services for WebSphere BPM Practice specializing in business rules. He has over 10 years experience in designing and developing business rules and business process management systems and 25 years experience in IT. Nigel has experience across all business sectors with his greatest focus on financial systems. Nigel joined IBM as part of the ILOG acquisition in 2009.

Jonathon Carr is a Staff IT Consultant in the IBM Software Services for WebSphere BPM Practice specializing in business rules and visualization. Jonathon has over 10 years of experience in designing, building and documenting business rules and GUI applications. He joined IBM as part of the ILOG acquisition in 2009.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Making parameters agile
• The GRS framework revisited
• Using GRS: A step-by-step tutorial
• Conclusion
• Acknowledgements
• Downloads
• Resources
• About the authors
• Comments

Dig deeper into Business process management on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers