The OpenRulesTM Tutorials         Home  TOC   PREV TOP NEXT Installation Guide
Divider

Getting Started with OpenRules

In this section we will use Hello-examples to introduce three major types of OpenRules applications.

         OpenRules Workspace
          Basic Decision Projects
          Basic Rule Projects
          Rules-based Web Applications
          Business Rules Deployed as Web Services
                    Excel-based Client for a Web Service
                    Java Client for a Web Service

OpenRules Workspace

In the following sections we will assume that you have all OpenRules configuration and sample projects installed. For both the Standalone or the Eclipse-based installations the structure of your OpenRules workspace is the same as described by section "OpenRules Installation Structure".

Here is a view of your Eclipse workbench:

Basic Decision Projects  ►top

These projects were introduced by OpenRules-6 - see their detailed descriptions in this document.

Basic Rule Projects  ►top

Start with the basic rule project "HelloRules".  It provides simple rules for greeting a customer based on the time of day and customer characteristics such as age, gender, or marital status.  Open the file rules/include/HelloRules.xls using Excel.  In Windows Explorer just double-click on the file and using Eclipse select the file with a right-click Open With + System Editor.  You will see two decision tables "defineGreeting" and "defineSalutation".  Hopefully, these tables are self-explanatory. If you click the "+" buttons, you will open hidden implementation information. You may read more about this example at http://openrules.com/examples.htm.  The rules inside these decision tables deal with the business objects "App" and "Customer" described in the another Excel file rules/include/HelloData.xls (see the worksheet "Glossary").  This file also contains some test data - see the worksheet "Data".  To execute this example, in Eclipse double-click on the file run.bat.  During the execution, this standard launcher calls the main method from the Excel table rules/main/Hello.xls.  Under Eclipse, you also may right-click to build.xml and select Run As + 1 Run Build. 

Let's see how Eclipse diagnoses the errors made in Excel.  Let's make a mistake in the Excel table rules/include/HelloRules.xls:

We "mistakenly" changed "min <= hour" to "min1 <= hour". After going back to Eclipse, refreshing and cleaning the project HelloRules, we will see the following error in the Console view:

Note. If errors in Excel files are not displayed, click ▼ to open the "Filters.." and make sure that type "OpenRules Problem" is marked.

If you double-click on the error hyperlink, the Excel file will be opened with the invalid cell selected.  If you try to run this project, you will receive the following syntax error on the Eclipse console:

Error: Field not found: min1
Invalid Code Fragment:
=======================
min1 <= hour
^^^^
=======================
at file:/C:/OpenRules/workspace/HelloJava/rules/include/HelloRules.xls?sheet=Decision Tables&cell=B5&start=0&end=3

Most of the other basic rule projects (samples) are organized similarly:

You can modify the rules or data using only Excel (or OpenOffice, or Google Spreadsheets), save changes and then run the rules again to see the results your changes produced. You may learn more by walking through the Use Case and you will be ready to start creating your own rule projects. 

Rules-based Web Applications  ►top

Now, let's look at the rule project "HelloForms".  It provides a Web-based GUI to test the basic HelloRules project.  Here is an Eclipse view of this project:

The main file rules/main//HelloWeb.xls for this web application is different from a basic main file.  A web application launcher will behave differently now: instead of running Java code, as in the case of the basic rule project, it will use a built-in OpenRules Forms Renderer to generate HTML code based on the executed rules.  Thus, the main method has the standard name "body" and returns a Table Layout dynamically defined during interaction sessions between a user and the Web server.  The project includes a new Excel worksheet rules/include/HelloForms.xls that defines the GUI layout.  However, the project uses the same Excel workbooks rules/include/HelloRules.xls and include/HelloData.xls to present business rules and the data types.

The main jsp-file war/index.jsp defines a location of the main xls-file:

<%
String xlsMain = "file:../webapps/HelloForms/rules/main/HelloWeb.xls";
String s_attr = "openrules_session";
OpenRulesSession openrules_session = (OpenRulesSession) session.getAttribute(s_attr);
if (openrules_session == null ) {
      openrules_session = new OpenRulesSession(xlsMain);
      session.setAttribute( s_attr, openrules_session);
}
%>

Note that here the main xls-file is defined relatively to the directory "bin" from which the Tomcat server has been started.

Open the file rules/include/HelloForms.xls using Excel as a System Editor. You will see a table that represents a one page GUI:

This TableLayout will be used to generate the following user's view:

Hopefully it is intuitive enough, but we would like to stress the following:

You may read more about this form's layout here.

As we described in the OpenRules Installation Structure section, OpenRules deploys web applications within any web application servers.  By default it uses a custom-installed open source Apache Tomcat server.  To deploy and run this web application please do the following:

  1. Start Tomcat server (if it has not been started yet).

  2. Double-click HelloForms/build.bat to build HelloForms.war

  3. Double-click HelloForms/deploy.bat to deploy HelloForms.war on Tomcat described at build.properties

  4. Double-click HelloForms/run.html to start an Internet Browser client for the deployed HelloForms project. Change the value of different input fields and push "Update Greeting" button to test greeting rules.

Most of the other sample projects with Web-based components are organized similarly:

If your web application uses the standard OpenRules forms library (like the sample LoanWeb does), you also need to install the standard project openrules.forms.lib and deploy it by double-clicking on openrules.forms.lib/build.and.deploy.bat.

You may modify the rules, data or form layouts using only Excel, save the changes, re-deploy the application and then run the proper html-file again to see the results of your changes in your Internet browser.  Explore more complex examples such as LoanWeb, HealthCareWeb, and NumberGuess, read OpenRules Use Case and start developing your own rules-based Web applications.

Business Rules Deployed as Web Services  ►top

Now, let's look at the rule project "HelloWS".  This project contains all components necessary to deploy the business rules defined in the file rules/include/HelloRules.xls as a Web Service on the Tomcat server.  Here is an Eclipse view of this project:

The main file war/rules/main/HelloWS.xls for this Web Service is different from a basic main file.  Web Services usually receive all business objects from an external application that calls this service.  Correspondingly, we changed the main method making it look like a regular Java method "hello" with the current hour, customer's age, gender, and marital status passed as parameters.  This method will return a string with a greeting produced in accordance with business rules defined inside the rule service HelloWS.  The signature of this method will define an external interface of our web service that will be automatically generated as a WSDL-file.  The project uses the same Excel workbooks include/HelloRules.xls and include/HelloData.xls to present business rules and the data types used.

As we described in the OpenRules Installation Structure section, by default OpenRules samples rely on Apache Tomcat and a Apache Axis pre-installed by a customer. OpenRules supports an automatic web service creation.  This project includes a source folder "gen".   This is a placeholder for the automatically generated Java classes. You may ignore these classes since they were generated by OpenRules only to allow Axis to create the proper web service.  File war/WEB-INF/server-config.wsdd is used to define this service. Actually only a few lines inside this file should be modified when you define your own web service:

<service name="HelloWS" provider="java:RPC">
<parameter name="allowedMethods" value="hello"/>
<parameter name="className" value="com.openrules.examples.HelloWS"/>
</service>

The project will be built in accordance with the properties specified in file build.properties:


appserver.home=C:/apache-tomcat-5.5.17
deploy.path=${appserver.home}/webapps
tomcat.manager.url=http://localhost:8080/manager
tomcat.manager.username=tomcat
tomcat.manager.password=tomcat

axis.lib=C:/axis-1_4/lib

war.name=HelloWS

# the name of generated class to be used by web service deployment
ws.gen.classname=com.openrules.examples.HelloWS

#source file address in deployment environment, may be different from compile
#environment like in this case
ws.deploy.src=HelloWS.xls

ws.axis.allowed.methods=hello

#user deployment home
# for Tomcat. We assume that Tomcat's basedir is "bin" and webapps is 
# at the same level as "bin"
ws.depl.uhome=file:../webapps/HelloWS/rules/main/

# for WAS 6.1 - your actual deployment home can be different as you
# define during HelloWS.war installation at WAS 6.1 
#ws.depl.uhome=file:installedApps/4c83Node01Cell/HelloWS_war.ear/HelloWS.war/rules/main/

#source file for ws generator
ws.compile.src=file:war/rules/main/HelloWS.xls

#user home for ws generation tool
ws.compile.uhome=.

#target root for generated source
ws.target.src.dir=gen

#compile-time user claspath
ws.compile.user.classpath=bin

If you make changes in file HelloWS.xls, you may explicitly re-generate the Java classes in the subdirectory "gen" by executing "generate.webservice.java.bat".

To deploy HelloWS project as a web service, do the following:

  1. Make sure that Tomcat server is running.

  2. Double-click on the HelloWS/build.bat to build HelloWS.war.

  3. Double-click on the HelloWS/deploy.bat to deploy HelloWS.war as a Web service on the Tomcat. Actually, the "deployment" just copies HelloWS.war to Tomcats's webapps directory, and Tomcat itself does the rest of work by creating a subdirectory HelloWS. A successful build will generate the WSDL file HelloWSDL.html.

  4. Double-click on the HelloWS/run.html to start Web Browser that will access a WSDL definition of the deployed HelloWS Web service.

NOTES.  You may ignore a warning "Unable to find required classes.." at the Tomcat log.  If you receive 404 error, you probably have to restart Tomcat, delete HelloWS.war and HelloWS subdirectory from webapps, then repeat deploy.bat.

Now your HelloWS project is successfully deployed on your local Tomcat server.  Similarly you may deploy the created war file on other web servers.  OpenRules provides two client projects to work with this web service: HelloWSExcelClient and HelloWSJavaClient.

Excel-based Client for a Web Service

We provide an example of the Excel-based client for the web service HelloWS in the spreadsheet (see the file HelloWSExcelClient/HelloWSClient.xls).  It contains a simple table with several tests for the HelloWS project deployed as a web service.  Make sure that your Tomcat server is running.  Open HelloWSClient.xls with Excel.  When asked, Enable Macros.  When you change the marital status, age or other fields in this table, the rule service HelloWS will be called which will produce and return a greeting that will be displayed in the column "greeting".

You may want to look at the Visual Basic interface automatically generated based on the service description located at "http://localhost:8080/HelloWS/services/HelloWS?wsdl".   From the Excel menu Tools go to Macro + Visual Basic Editor and look at the generated Class Module "clsws_HelloWSService".

Similarly, you may create a MS Word client or other MS Office-based clients for Java-based rule services.

NOTE. Make sure that your MS Office is web services enabled. Consult http://msdn.microsoft.com/webservices for additional information.

Java Client for a Web Service

We provide an example of the Java client for the web service "HelloWS" in the project "HelloWSJavaClient".  It contains a file HelloWSServiceClientMain.java that you can run using run.bat (first make sure that the server is up and running).

This is a simple example that uses an automatically generated Java package "ws.example" in the directory HelloWSJavaClient/gen.  The interface package was generated using Apache Axis based on the Web service description located at "http://localhost:8080/HelloWS/services/HelloWS?wsdl".  You may regenerate it by double-clicking HelloWSJavaClient/generate.axis.client.bat.

 

►top

Divider