Rules Guide

Chapter 1 About Rules

This chapter provides an overview of the Rule subsystem and describes some of the benefits of developing rules-based applications. It has these sections:

About the Rule subsystem

The Rule subsystem provides a Java API and tool support for creating flexible, reusable logic for your Director applications. Typically, Director components fire rules at crucial points in their logic flows to make application decisions. A rule can perform virtually any programming task. You can handle the result in your component code, or you can let the rule handle processing outside the scope of your application.

What is a rule?

Rules consist of conditions and actions. The basic formula for a rule is: if a condition or group of conditions are true, the associated action or actions are executed. Rule structure is based on the case statement, a standard construct in many programming languages. You create rules using Workbench's Rule Editor, which provides a user interface for building the rule logic.

Basic structure Every rule consists of at least one decision node (case) that has at least these two sections:

The When section contains one or more conditions. You select the conditions and specify how the results of individual conditions are combined using AND and OR operators.
The Do section contains one or more actions that you select. It is executed when the When section evaluates to true. You can also insert decision nodes within an action, which are evaluated as nested rules.

A final Otherwise Do section is optional. It specifies default actions for the rule that are executed when none of the decision nodes are true.

For example, a rule with one case and a default section has this format:

  When {condition group is true} 
    Do {actions}
  Otherwise Do {actions}

Here's what it looks like in the Rule Editor:

wbREConditonExample

Nested logic Logic can be nested within rules by adding child nodes to a parent node, and as with standard case statements, you can control the flow of processing using break and continue statements.

wbRECase

Rule Editor features

You use the Rule Editor to combine conditions and actions to build rules. Here are the main features of the Rule Editor:

Feature	Description
Conditions and actions	Conditions and actions are prebuilt reusable JavaBeans with properties you can set in the Rule Editor. Director supplies an installed set of general-purpose conditions and actions. You can also create your own custom versions.
Macros	A macro is a series of conditions or actions that can be combined for reuse. For example, a condition macro could be: if today is a weekday, and the time is between 9 a.m. and 5 p.m., and this is not November.
Pipelines	A pipeline is a series of rules that you can set up in the Rule Editor and execute in your applications. Pipelines can be bound to users and groups, or to any named pipeline you define.

For more information For information about the Rule and Macro Editors, see Rule and Macro Editors.

Rule API

After you define rules in the Rule Editor you can access them in your applications using the rule API. The API includes a rule manager and context object for firing rules and accessing session data. There are also implementation classes for defining custom conditions and actions.

For more information, see the com.sssw.re packages in the API online help.

Why use rules?

As an application developer you might ask, why use rules? Why not just code the logic directly in my application? From the application development and deployment standpoint, rules provide several advantages:

Benefit of rules	Details
Easy to create and use	The Rule Editor provides a set of general-purpose conditions and actions that can address many application needs. Using a point and click interface, you can combine conditions and actions in flexible ways to create different types of rules. You also have access to runtime properties, such as userID, and you can easily store, retrieve, and evaluate your own session values using the whiteboard feature. Director API methods make it easy to fire rules and build logic by exchanging information between rules and application components.
Encapsulated logic	Rules contribute toward the goal of making applications modular. You can enhance code maintenance, for example, by separating business logic in rules and handling presentation in your component code. Also, depending on your application design, this separation of functions allows nonprogrammers such as business analysts to reconfigure logic without adversely affecting the underlying application code.
Reusable and extendable	Conditions and actions can be reused to create different rules for different purposes, or the rules themselves can be reused in the same application or across applications. For example, you might use the same set of rules with different properties to be executed when users of different groups log in to an application, or you might have some unique rules for each group, with some overlapping rules. Because conditions and actions are implemented as JavaBeans, they are easily extensible. The Rule subsystem provides complete support for JavaBeans, including built-in constructs that facilitate creating your own custom conditions and actions.
Interoperable with other subsystems	Rules can be easily integrated with other Director subsystems. For example, you can use rules: To control access to documents in the Content Management subsystem To define routing logic in a Workflow application For user profiling in Director applications

Planning a rules-based application

Because rules are flexible and provide many implementation options, you need to carefully plan how and when to use them in your applications. Your most fundamental decision is whether to implement your business logic in rules rather than directly in your component.

Here are criteria to consider:

Use	If logic
Rules	May be shared in different parts of an application Can be used in multiple applications Data or criteria change frequently Can be updated by nonprogrammers
Direct Java code	Has a narrow application Data or criteria change rarely Must be isolated for a specific scenario Must be controlled by programmers

Once you decide to use rules in your Director application, you need to decide how to implement them along with other application code and artifacts. Of course, implementation decisions depend on application requirements and your development environment. Along with the general application support provided by the Framework subsystem, Director encompasses standards-based implementations such as JSP and the Struts framework.

For more information, refer to the Portal Guide.

Design guidelines

Here are some guidelines for designing a rules-based application:

Guideline	Details
Determine what business logic can be encapsulated in rules and what needs to be handled by the application itself	This will vary with requirements. As a general principle, the more logic you can encapsulate in rules, the more reusable your code will be.
Create a detailed design specification that defines what each rule does	The design document should include the following: The condition or set of conditions (condition node) that determine an action. For example, WHEN the current user belongs to the administrator group AND today is a weekday. The action or actions taken when the condition is true or false. For example: if the condition node is true, return true AND return an HTTP response phrase to the caller. OTHERWISE return false AND return a different response phrase. How the component that fires the rule should respond to the result of the action. For example: if the action is true, display the response AND increment a log; if the action is FALSE, display the response and send an e-mail. In some cases, the rule may not respond at all.

Guideline

Details

Determine what business logic can be encapsulated in rules and what needs to be handled by the application itself

This will vary with requirements. As a general principle, the more logic you can encapsulate in rules, the more reusable your code will be.

Create a detailed design specification that defines what each rule does

The design document should include the following:

The condition or set of conditions (condition node) that determine an action. For example, WHEN the current user belongs to the administrator group AND today is a weekday.
The action or actions taken when the condition is true or false. For example: if the condition node is true, return true AND return an HTTP response phrase to the caller. OTHERWISE return false AND return a different response phrase.
How the component that fires the rule should respond to the result of the action. For example: if the action is true, display the response AND increment a log; if the action is FALSE, display the response and send an e-mail. In some cases, the rule may not respond at all.

Rules Guide