Enabling rule-based decision services as Web services

Combining rules' agility with SOA's flexibility

JRules allows decision services to be exposed as web service without any coding. Exposing the business decision services as web services combine business rules' agility with SOA's flexibility. It facilitates an easy integration with other SOA-enabled products.

Yang Chen Ming (yangcm@sg.ibm.com), Consultant, IBM Corporation

Yang Chen MingYang Chen Ming has six years of experience with a primary focus on Business Rule Management System and JEE. For the past four years, Yang has been working extensively with the ILOG JRules portfolio.



24 June 2010

Also available in Japanese Spanish

Introduction

IBM WebSphere ILOG JRules is a leading Business Rule Management System (BRMS) that offers a comprehensive set of features covering all aspects of business rules, from design, development, testing, deployment, execution to maintenance.

Web service is a technology that allows applications to communicate with each other in a platform- and programming language-agnostic manner. A Web service is a software interface that describes a collection of operations that can be accessed over the network through standardized XML messaging. Web service is widely used and plays a central role in most service oriented architecture (SOA).

JRules introduces a feature called Hosted Transparent Decision Server (HTDS) that allows the decision services to be exposed as web service with no additional program coding required.


Installation and configuration

To run this sample, the following products need to be installed and configured properly:

  • IBM WebSphere ILOG JRules V7.0.x

After installation, we should be able to:

  • Launch Rule Studio that comes with the JRules installer.
  • View the Rule Execution Server console homepage at http://localhost:8080/res/. This is supported by the out-of-box tomcat server instance. Additional configurations are required for JRules to run on other application servers, such as WebSphere, or Oracle WebLogic.

Note that the following JRules bundles/components are not needed to run the sample.

  • Rule Team Server bundle
  • Decision Validation Service
  • Rule Solutions for Office

Scenario overview

The business scenario is very simple. Assume there is a Java EE web-based loan quotation application that takes in customer information and invokes the decision service to determine the loan rate if the loan application is eligible. For simplicity, we determine the loan rate with the loan amount and the age of the applicant provided. Two key entities are Customer and Loan.

There are two ways to model JRules Execution Object Model (XOM), which is the underlying object model that JRules leverages on during the actual execution. The domain objects can be either modeled in Java or XML. We use XML XOM in this example.

Figure 1. XML_Customer
XML_Customer
Figure 2. XOM_Loan
XOM_Loan

There are two rules implemented in the rule project, Loan Value and Young Applicant. They are categorized into Eligibility and Rating sub-package respectively.

Listing 1. SRule Eligibility.Loan Value
if
    the advance amount of the loan of 'the customer' is more than 100000
then
    set the decision of the loan of 'the customer' to "Declined";
else
    set the decision of the loan of 'the customer' to "Accepted";
    set the rate of the loan of 'the customer' to 5.5;
Listing 2. Rule Rating.Young Applicant
if
    the age of 'the customer' is less than 21
then
    set the rate of the loan of 'the customer' to 6.5;

The orchestrated ruleflow wire the rules from both eligibility package and rating package.

Figure 3. Ruleflow
Ruleflow

The RuleSet parameters define the data interface for the ruleset that will be invoked as the decision service. For every Customer input, the decision service is able to determine what the appropriate loan rate is. The loan rate will be returned in a updated customer object via customer.getLoan().getRate().

Figure 4. RuleSet Parameter
RuleSet Parameter

There are many integration options available out of box, for example, Web service, J2SE or Local/Remote EJB mode etc. In this article we will learn how to enable it as a Web service. Assume we already have this rule project LoanRules (comprise of all artifacts presented above) created before hand, what we are going to do next is as follows.

  1. Create a RuleApp project to package LoanRules into a RuleApp Archive
  2. Create a Rule Execution Server Configuration for the built-in Tomcat Server
  3. Deploy the RuleApp Archive to Tomcat
  4. Generate and Verify the WSDL file of the Decision Service
  5. Run a Web service Client to invoke the Web service

Detailed explanation

Step 1. Create a RuleApp project to package LoanRules into a RuleApp Archive

Create a new RuleApp project using "New Project" wizard. A RuleApp project is used to generate a RuleApp archive.

Figure 5. Create a new RuleApp
Create a new RuleApp

Specify "LoanRules" and add it to the RuleApp project. By doing this, we are telling JRules that the RuleApp archive will contain the rules defined in Rule Project "LoanRules".

Figure 6. Add RuleProject "LoanRules"
Add RuleProject LoanRules

Accept all other default settings, and click "Finish". Now the RuleApp project "LoanRuleApp" is ready.

Step 2. Create a Rule Execution Server Configuration for Tomcat

Note that though this step is optional in deploying the ruleapp to Rule Execution Server (RES), it is a recommended and more systematic approach to store the RES configuration for future use. It is much easier to switch the target RES if we have a list of RES configuration available for development, testing and production environments.

Figure 7. Create a new RES Configuration Project
Create a new RES Configuration Project

Input the right configuration for Tomcat server, and specify the user and password for Rule Execution Server (RES) Console that running on this tomcat instance. Verify the connection is working by clicking on the "Test Connection" button.

Figure 8. Configure Tomcat Server
Configure Tomcat Server

Accept all other default settings, and click "Finish". We now have our RES Configuration Project. This project will be used by the RuleApp project we created in Step1 for a proper deployment.

Step 3. Deploy the RuleApp Archive to Tomcat

Double click "archive.xml" file in LoanRuleApp project folder.

Figure 9. Open the RuleApp Project
Open the RuleApp Project

Notice there is a "Deploy" link at the bottom left of the panel. Click on it, we are asked to select a versioning policy. Since this is our first time deploying a RuleApp, we select "Increment RuleApp major version".

Figure 10. Deploy as a new version
Deploy as a new version

Click the first radio button and select "Tomcat". This is to tell JRules that we want our rules to be deployed on the Tomcat server. Click "Finish" to complete the wizard.

Figure 11. Deploy the RuleApp to the Server
Deploy the RuleApp to the Server

The console panel will have the verbose printout indicating that the deployment is successful.

Figure 12. Message indicated that the RuleApp is deployed
Message indicated that the RuleApp is deployed

Step 4. Generate and Verify the WSDL file of the Decision Service

Log on to the RES console on Tomcat, the default URL is http://localhost:8080/res. Change the hostname or port if necessary. The default user name and password are resAdmin.

Once log in, Click on the "Explorer" tab. A list of deployed RuleApps are displayed. In this example, we shall see a RuleApp named "LoanRuleApp" with version 1.0.

Figure 13. RuleApp listed in RES Console
RuleApp listed in RES Console

Click on "LoanRuleApp" to enter the RuleApp view. This is where we edit custom properties for LoanRuleApp. On the bottom "RuleSet" panel, there is a row with name "LoanRules". This is the ruleset included in LoanRuleApp.

Figure 14. RuleApp View
RuleApp View

Click on "LoanRules" to enter the RuleSet view.

Figure 15. RuleSet View
RuleSet View

We will see a link "Get HTDS WSDL for this ruleset version". Click on it to generate a WSDL file for this decision service. We will be directed to the WSDL page. This web service end point URL is http://localhost:8080/DecisionService/ws/LoanRuleApp/1.0/LoanRules/1.0?WSDL.

Figure 16. WSDL Generated
WSDL Generated

Step 5a. Simulate a Web service client using SOAPUI to invoke the Web service

In this step, we will use SOAPUI as the web service client to test the above Web service.

Firstly, create a new SOAPUI project by specifying the WSDL URL in the wizard dialog box, http://localhost:8080/DecisionService/ws/LoanRuleApp/1.0/LoanRules/1.0?WSDL. Optionally tick the option "Create sample requests for all operations" to take a look at what the structure of the input XML looks like.

Figure 17. New SOAPUI Project Wizard
New SOAPUI Project Wizard

Secondly, paste the following XML into the request textbox on the left hand side of SOAPUI. Note that there is a postfix "Z" for the DOB of the customer, which means the same time zone as Coordinated Universal Time (UTC).

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:dec="http://www.ilog.com/rules/DecisionService" 
xmlns:loan="http://ilog.com/loan" 
xmlns:par="http://www.ilog.com/rules/param" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
   </soapenv:Header>
   <soapenv:Body>
      <dec:DecisionServiceRequest>
         <par:inputCustomer>
            <loan:Customer>
               <loan:ID>AB1265H</loan:ID>
               <loan:Salary>35000</loan:Salary>
               <loan:Dob>1960-01-01Z</loan:Dob>
               <loan:Security/>
               <loan:Loan>
                  <loan:AdvanceAmount>100000</loan:AdvanceAmount>
                  <loan:Term>36</loan:Term>
                  <loan:PaymentFrequency>1</loan:PaymentFrequency>
                  <loan:ID>AB1265H</loan:ID>
                  <loan:Product/>
               </loan:Loan>
            </loan:Customer>
         </par:inputCustomer>
      </dec:DecisionServiceRequest>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP Input Message in XML

Click on the "Run" button, the reply soap message in XML will be shown on the right hand side, from which we should be able to find information related to the business decision: Loan Accepted with the rate of 5.5 percent.

Listing 3. XML Output
<Loan>
    <AdvancedAmount>1000000.0</AdvancedAmount>
    <Term>36</Term>
    <Rate>5.5</Rate>
    <RepaymentAmount xsi:null="true"/>
    <Decision>Accepted</Decision>

The SOAPUI GUI we have by now may look like the screenshot below in figure 18.

Figure 18. SOAPUI Screenshot
SOAPUI Screenshot

Step 5b. Run a Apache Axis Client to invoke the Web service

Instead of leveraging on SOAPUI, advanced developers may want to implement an Apache Axis client to test the Web service. For example, we will be using a .NET application to verify this Web service.

We invoke the service by using ServiceLocator and PortType classes. These classes are auto-generated by WSDL2Java ant target.

DecisionServiceLoanRules_ServiceLocator service 
    = new DecisionServiceLoanRules_ServiceLocator();
DecisionServiceLoanRules_PortType port 
    = service.getDecisionServiceSOAPlocalhost();

DecisionServiceRequest request = new DecisionServiceRequest();
DecisionServiceResponse response = null;

InputCustomer customerWrapper = new InputCustomer();
Customer customer = new Customer();

Initialize Axis ServiceLocator and portType instance

We continue to set the input data of type Customer. It has the following values set. In particular the DOB of the customer is January 1, 1960, and the loan amount is $100,000.

customer.setID("AB1265H");
customer.setSalary(35000.00);
customer.setDob(new Date(60,1,1));
Loan loan = new Loan();
loan.setAdvanceAmount(100000.00);
loan.setTerm(36);
loan.setPaymentFrequency(1);
loan.setProduct(new Product());
customer.setLoan(loan);

Populate Input Data

The last step is to invoke the decision service and print the loan rate. If the decision is to decline the loan request, Customer.Loan.Decision attribute will be set to "Declined".

response = port.executeDecisionService(request);			
InputCustomer customerWrapperReturned 
    = response.getInputCustomer();
System.out.println("The decision is " + 
    customerWrapperReturned.getCustomer().getLoan().getDecision());
System.out.println("The rate is " + 
    customerWrapperReturned.getCustomer().getLoan().getRate());

Extract and Print output Data

Next, we run the client. The result returned is printed on the console. The loan will be accepted, the implied loan rate is 5.5 percent. The first output message "Unable to find required class..." concerning missing MIME library is irrelevant to our test case, ignore it.

Figure 19. Java Console Output
Java Console Output

Conclusion

JRules generates and hosts the web service automatically upon a successful RuleApp deployment. This combines the agility that JRules offers with the flexibility that comes with Web Services. This feature facilitates a smoother integration with other IBM products such as WebSphere Process Server, WebSphere Enterprise Service Bus and WebSphere Message Broker.

Resources

Learn

Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.

Discuss

  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

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 SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=497884
ArticleTitle=Enabling rule-based decision services as Web services
publish-date=06242010