Rules Repository

Organizing and maintaining business rules repositories

Logical and Physical Rule Repositories

 Hierarchies of Rule Workbooks
       Included Workbooks and Include Path
       Common Libraries of Rule Workbooks
       Imports from Java and XML
       External Rules: DB, XML, GUI, and more
Parameterized Rule Repositories
Rules Version Control
DB-based Repositories
Rules Authoring and Maintenance Tools

Rules Testing Facilities

OpenRules Logical and Physical Rule Repositories

OpenRules utilizes the well-established spreadsheet concepts of workbooks, worksheets, and tables to build enterprise-level rule repositories.  Each OpenRules workbook is comprised of one or more worksheets that can be used to separate information by types or categories.  The following picture shows the logical and physical organization of OpenRules repositories:

Logically the OpenRules® Repository may be considered as a hierarchy of inter-related Excel workbooks.  Each rule workbook may be comprised of one or more tables. Most typical OpenRules® tables are decision tables that 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.  A detailed description of OpenRules® tables can be found at

Physically all workbooks are saved as standard xls- or xml-files with well-known formats.  The proper Excel files may reside in the local file system, remote application servers, a version control system such as Subversion, or inside a standard database management system.  Click here to read more about DB-based repositories.

OpenRules uses an URL pseudo-protocol notation with prefixes such as "file:", "classpath:", "http://", "ftp://", "db:", etc.  Typically, the 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 the 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 "", you can use this string as its exact specification. 

Hierarchies of Rule Workbooks     top

An OpenRules repository usually consists of multiple Excel workbooks distributed between different subdirectories.  Each rule workbook may include references to other workbooks thus comprising complex hierarchies of inter-related workbooks and rule tables.

          Included Workbooks    top

Rules workbooks refer to other workbooks using so called "includes" inside OpenRules "Environment" tables.  To let OpenRules know about such include-relationships, you have to place references to all immediately included xls-files into the table "Environment".  Here is an example of a OpenRules repository that comes with the standard sample project "RuleRepository":

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, in this instance all included files are defined relative to the directory "rules/main" in which Main.xls resides.  You may 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 relative 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.

          Include Path and 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 subdirectory "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:

More detailed information about includes can be found in the user documentation.  Here we want to summarize the following important facts:

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

  • The 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 standard RulesRepository example all rule tables deal with Java objects defined in the Java package myjava.package1.  So, the proper Environment table inside file Main.xls (see above) contains a property "" with value "myjava.package1.*".

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.  Read more here.

          Imports from XML   top

Along with Java, OpenRules® allows 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:


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 ""
  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.
External Rules    top

OpenRules® allows a user to create and maintain their rules outside of Excel-based rule tables. It provides a generic Java API for adding business rules from different external sources such as:

  1. Database tables created and modified by the standard DB management tools

  2. Live rule tables in memory dynamically modified by an external GUI

  3. Java objects of the predefined type RuleTable

  4. Problem-specific rule sources that implement a newly offered rules provider interface.

With external rules you may keep the business parts of your rules in any external source while the technical part (Java snippets) will remain in an Excel-based template, based on which actual rules will be created by the OpenRulesEngine. For example, you may keep your rules in a regular database table as long as its structure corresponds to the columns (conditions and actions) of the proper Excel template. Thus, the standard DB management tools or your own GUI that maintains these DB-based rule tables de-facto become your own rules management environments. Read more.

Parameterized Rule Repositories     top

An OpenRules® repository may be parameterized in such a way that different rule workbooks may be invoked from the same repository under different circumstances.   For example, let's assume that we want to define rules that offer different travel packages for different years and seasons.  We may specify a concrete year and a season by using environment variables YEAR and SEASON.  Our rules repository may have the following structure:







To make the OpenRulesEngine automatically select the correct rules from such a repository, we may use the following parameterized include-statements inside the Environment table of the main xls-file rules/main/Main.xls:

Environment season.offers.*
include ../common/SalutationRules.xls
include ../${YEAR}/${SEASON}Rules.xls

Thus, the same rules repository will handle both WinterRules and SummerRules for different years.  The detailed example is provided in the standard project SeasonRules.

Rules Version Control      top

For rules version control you can choose any standard version control system that works within your traditional software development environment.  We would recommend using an open source product "Subversion" that is a compelling replacement for CVS in the open source community.  For business users a friendly web interface is provided by a popular open source product TortoiseSVN.  For technical users, it may be preferable to use a Subversion incorporated into Eclipse IDE.  One obvious advantage of the suggested approach is the fact that both business rules and related Java/XML files will be handled by the same version control system. 

You may even keep your Excel files with rules, data and other OpenRules® tables directly in Subversion. If your include-statements use http-addresses that point to a concrete Subversion repository then the OpenRulesEngine will dynamically access SVN repositories without the necessity to move Excel files back into a file system.

Another way to use version control is to place your rule workbooks in a database and use DBV-protocol to access different versions of the rules in run-time - read more.

Rules Authoring and Maintenance Tools      top

OpenRules relies on standard commonly used tools (mainly from Open Source) to organize and manage a Business Rules Repository:

To create and edit rules and other tables presented in Excel-files you can use any standard spreadsheet editors such as:

Google Spreadsheets are especially useful for sharing spreadsheet editing - see section Collaborative Rules Management with Google Spreadsheets.

For technical people responsible for rules project management OpenRules provides an Eclipse Plug-in that allows them to treat business rules as a natural part of complex Java projects. See more details here.

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 may even create and keep Datatypes directly in an Excel table.  This allows you to test your rules independently of Java code.  See more details about Data tables and Datatype tables at docs\man_data.html.