Introducing the Generic Ruleset Signature pattern for WebSphere Operational Decision Management V7.5, Part 2: Improving agility and robustness

The second part of this series extends the Generic Ruleset Signature pattern, which can be applied to business rules in IBM® WebSphere® Operational Decision Management to improve productivity and maintainability of rules projects using a flat business model. This content is part of the IBM Business Process Management Journal.

Nigel T. Crowther (nigelcro@uk.ibm.com), Senior IT Consultant, IBM

Nigel Crowther photoNigel 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 (jonathon.carr@uk.ibm.com), Staff IT Consultant, IBM

Jonathon Carr photoJonathon 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.



13 June 2012

Also available in Chinese

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.


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.

Figure 1. Simple trading system
Simple trading system

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

Figure 2. Simple trading system with new parameter
Simple trading system with new parameter

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.
Figure 3. Traditional changes required to add a parameter
Traditional changes required to add a parameter

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.

Figure 4. GRS changes required to add a parameter
GRS changes required to add a parameter

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.

Figure 5. Original GRS using strings
Original GRS using strings

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.

Figure 6. Improved GRS using domains
Improved GRS using domains

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.

Figure 7. Mixing types in original GRS
Mixing types in original GRS

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.

Figure 8. Defining parameters using domains
Defining parameters using domains

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.

Figure 9. Using domains to select correct type of parameter
Using domains to select correct type of parameter

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.

Figure 10. GRS parameter definition
GRS parameter definition

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.

Figure 11. DVS test scenario
DVS test scenario

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

Figure 12. DVS expected results
DVS expected results

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

Figure 13. DVS execution report
DVS execution report

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.

Figure 14. Adding new GRS parameters
Adding new GRS parameters

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

Figure 15. Enhanced business rules
Enhanced business rule

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.

Figure 16. Adding new GRS parameters
Adding new GRS parameters

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.

Figure 17. Adding new GRS parameters
Adding new GRS parameters

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.

Figure 18. DVS execution report after adding parameters
DVS execution report after adding parameters

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.

Figure 19. Concrete XSD for shareTrader
Concrete XSD for shareTrader

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

Listing 1. Concrete XML request payload
<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.

Figure 20. GRS metamodel schema
GRS metamodel schema

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.

Listing 2. XML GRS request 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.

Listing 3. XML GRS response payload
<rpx:GrsResponse>
	<rpx:RequestId>0</rpx:RequestId>
	<rpx:NamedFields>
		<rpx:NamedField Name="response" Value="BUY”  DataType="String"/>	
	</rpx:NamedFields>
</rpx:GrsResponse>

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
    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.
Listing 4. Java code to invoke GRS
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");
  1. 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
    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.

Listing 5. GRS successful result
Request = {stockName=IBM, stockPrice=100.0}
Response = BUY
Errors = []
  1. 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
    Domains file in BOM project
  2. 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
    Integer
  3. Save the Excel file. Open the grs-bom project, then right-click and refresh the Resources folder to pick up the Excel changes.
  4. Now select the IntegerParameter class within the dynamic domains section of the BOM.
  5. Click Create a domain, as shown in Figure 25.
    Figure 25. Create a domain
    Create a domain
  6. Select the Excel Dynamic Domain and click Next, as shown in Figure 26.
    Figure 26. Select Excel Dynamic Domain
    Select Excel Dynamic Domain
  7. 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
    Excel Domain settings
  8. 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
    GRS projects
  9. 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
    Adding an integer parameter
  10. 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
    Using an integer parameter
  11. Run the grs-simple-tester again. You should see the result shown in Listing 6.
Listing 6. GRS missing input error
Request = {stockName=IBM, stockPrice=100.0}
Response = BUY
Errors = [{value=null, errorCode=1, paramType=Integer, name=sharesHeld, 
errorMessage=Missing input var}]
  1. 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.

Listing 7. Input parameters
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();
  1. Now run grs-simple-tester again. You should see the following successful result:
    Response = BUY.
  2. 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
    DVS testsuite file
  3. Examine the inputs and outputs to the test, as shown in Figures 32 and 33.
    Figure 32. GRS scenario input data
    GRS scenario input data
    Figure 33. Scenario expected results
    Scenario expected results
  4. 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
    DVS Run Configurations
  5. 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
    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
    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
    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
    Reload dynamic domains

    You should see the message shown in Figure 39.

    Figure 39. Successful reload of dynamic domains
    Successful reload of dynamic domains
  9. Edit the Decimal Parameters table shown in Figure 40.
    Figure 40. Decimal parameters table
    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
    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
    BUY rule
  12. Amend the Buy Rule with the additional action circled in red shown in Figure 43.
    Figure 43. Amended BUY rule
    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
    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
    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
    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
    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
    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
    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
    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
    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
    Web Services Explorer
  9. Click GrsRuleset, as shown in Figure 53.
    Figure 53. GRS projects
    GRS projects
  10. Click source, as shown in Figure 54.
    Figure 54. Select Source
    Select Source
  11. Paste the payload in Listing 8 into the soapenv body (not the header).
Listing 8. Input payload
<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>
  1. 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
    GRS Soap request and response

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.


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.


Downloads

DescriptionNameSize
Extended GRS tutorialShareTraderTutorial.zip2MB
GRS reference implementationGrsProjects.zip118KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=820817
ArticleTitle=Introducing the Generic Ruleset Signature pattern for WebSphere Operational Decision Management V7.5, Part 2: Improving agility and robustness
publish-date=06132012