The OpenRulesTM Tutorials         Home  TOC

User's Guide

File-based OpenRules Repository

4Hierarchy of inter-related Excel Workbooks
4Included Files and Include Path
4Common Libraries of Rule Workbooks
4Imports from Java
4Imports from XML
4Test Data

Hierarchy of Inter-Related Workbooks  ►top

OpenRules utilizes commonly knows spreadsheets to represent business rules, forms, test data, and other tables with externalized information available to both business and technical users. OpenRules uses well-established spreadsheet concepts of workbooks, worksheets, and tables as rule books, rule sets, and rule tables.  Each OpenRules workbook is comprised of one or more worksheets that can be used to separate information by types or categories.  Each worksheet, in turn, is comprised of one or more tables.  Decision tables are most typical OpenRules tables and are used to represent business rules.  However, along with rule tables, OpenRules supports tables of other types such as: Form Layouts, Data and Datatypes, Methods, and Environment tables.  The BR Repository in the picture above shows different types of workbooks.  A detailed description of OpenRules tables can be found here.

Ultimately all workbooks are saved as standard xls- or xml-files with well-known formats.  Thus, any OpenRules BR Repository can be considered as a hierarchy of inter-related workbooks distributed among directories of a local file system.  Some files can be located at the remote servers and can be accessed through the standard http, ftp and other protocols.

OpenRules uses an URL pseudo-protocol notation with prefixes such as "file:", "classpath:", "http://", "ftp://", "db:", etc.  Typically, your main xls-file Main.xls is located in a subdirectory "rules/main".  In this case the location of this file may be defined as "file:rules/main/Main.xls".  If your main xls-file is located directly in the project classpath, you may defined its location as "classpath:Main.xls".  If it is located at a website with the URL "http://www.example.com/rules/Main.xls", you can use this string as its exact specification. 

Included Files and Include Path  ►top

Rules workbooks can contain references to other workbooks called "includes".  To let OpenRules know about such include-relationships, you have to describe all immediately included xls-files in the table "Environment" inside an xls-file that includes these files. 

Here is an example of a BR Repository that comes with an OpenRules installation:

The main xls-file "Main.xls" is located in the local directory "rules/main". To invoke any rules associated with this file, the proper Java program creates an OpenRulesEngine using a string "file:rules/main/Main.xls" as a parameter. There are many other xls-files related to the Main.xls and located in different subdirectories of "rules". Here is a fragment of the Main.xls "Environment" table:

As you can guess, here all included files are defined relatively to the directory "rules/main" in which Main.xls resides.  You can notice that files RulesA11.xls and RulesA12.xls are not included.  The reason for this is that only RulesA1.xls really "cares" about these files.  Naturally its own table "Environment" contains the proper "include":

Here, both includes are defined relatively to the directory "CategoryA" of their "parent" file RulesA1.xls. As an alternative, you can define your included files relatively to a so called "include.path" - see sample in the next section.

Common Libraries of Rule Workbooks  ►top

Includes provide a convenient mechanism to create libraries of frequently used xls-files and refer to them from different rule repositories.  You can keep these libraries in a file system with a fixed "include.path".  You may even decide to move such libraries with common xls-files from your local file system to a remote server.  For example, in our example above you could move a subrirectory "libA" with all xls-files to a new location with an http address http://localhost:8080/my.common.lib.  In this case, you should first define a so-called "include.path" and then refer to the xls-files relative to this include.path using angle brackets as shown below:

Let's to summarize the following important facts:

• Structure of your BR repository can be naturally presented inside xls-files themselves using "includes"

• BR Repository can include files from different physical locations

• Complex branches on the rules tree can encapsulate knowledge about their own organization.

Imports from Java   ►top

OpenRules allow you to externalize business logic into xls-files.  However, these files still can use objects and methods defined in your Java environment.  For example, in the RulesRepository example above all rule tables deal with a Java object Appl defined in the Java package myjava.package1.  So, the proper Environment table inside file Main.xls (see above) contains a property "import.java" with value "myjava.package1.*".  Here is a more complex example:

Environment
import.static	com.openrules.tools.Methods
import.java	my.bom.*
	my.impl.*
	my.inventory.*
	com.openrules.ml.*
	my.package.MyClass
	com.3rdparty.*
include	../include/Rules1.xls
	../include/Rules2.xls

Usually, you only place common Java imports inside the main xls-file.  If some included xls-files use special Java classes you can reference them directly from inside their own Environment tables.  To read more click here.

Imports from XML   ►top

Along with Java, OpenRules allow you to use objects defined in XML files.  For example, the standard sample project HelloXMLCustomer uses an object of the type Customer defined in the file Customer.xml located in the project classpath:

<Customer
     name="Robinson"
     gender="Female"
     maritalStatus="Married"
     age="55"
/>

The xls-file HelloCustomer.xls that deals with this object includes the following Environment table:

The property "import.schema" specifies a location of the proper xml-file, in this case "classpath:/Customer.xml".  Of course, it could be any other location in the file system that starts with the prefix "file:".  This example also tells you that this Excel file uses:

1. static Java methods defined in the standard OpenRules package "com.openrules.tools.Methods"
2. xml-file "classpath:/Customer.xml"
3. Java class "Response" from a package "hello"
4. include-file "HelloRules.xls" that is located in the subdirectory "include" of the directory where the main xls file is located.

Test Data   ►top

It is a good practice to include test data into a Business Rules Repository.  This allows the rules administrator to test all changes to the repository.  OpenRules allows you to put your test data in xsl-files in special tables with the predefined type "Data".  For example, the standard sample project HelloForms contains data file HelloData.xls.  It contains a data table that describes customers with different combinations of attributes to be tested.  You even can create and keep Datatypes directly in an Excel table.  This allows you to test your rules independently of Java code.  Click here to see more details about Data tables and Datatype tables.

►top