Rules Guide

Chapter 4   Rule and Macro Editors

This chapter describes how to use Workbench to create and edit rules. It has the following sections:

• Accessing the Rule Editor

• Using conditions

• Using actions

• Using cases

• Testing, editing, and saving rules

• Working with condition and action macros

    For background information about using rules in Director applications, see Rule Development Basics.

Accessing the Rule Editor

The Rule Editor lets you create rules to use in a component or JSP page in your application. You build a rule by selecting from predefined conditions and actions. Each rule definition is saved as an XML file in a specified directory in your Director project.

To access the Rule Editor:

1. From the Workbench main menu select File>New.

2. In the New File dialog, select the Rules Engine tab.

   

3. Select the Rule icon.

   The Rule Editor displays in the upper-right panel in Workbench.

   

About the rule tree view

Graphically, a rule is a combination of one or more conditions (When) and one or more actions (Do) that produces some result. It has the form:

  When the combination of some conditions is true, 
     Do some actions; 
  Otherwise Do some other actions.

Each When-Do statement is called a node and maps to a decision node in XML. You can also embed case statements within a parent node, as described in Using cases.

The Otherwise-Do section is executed only when all nodes in the rule evaluate to false.

Naming a rule

You invoke the rule name when firing a rule.

You can specify a rule owner as part of the identifier. Doing so allows you to organize your rules by application and avoids possible naming conflicts with other applications. You can use the Rule API to access rules associated with an owner.

To name a rule:

1. In Workbench, open the Rule Editor.

2. Enter the rule name in the ID field. For example:

   myrule

3. (Optional) To specify the owner, use the format ownername.rulename. For example:

   myapp.myrule

4. (Optional) Enter a description in the Description field.

Using conditions

A condition is a Java class containing logic that returns true or false. The installed conditions are implemented as JavaBeans that in many cases allow you to set relevant properties. You can add multiple conditions for a rule, and manipulate those conditions in various ways.

Default condition   The default value for a condition is When:On. In cases where you always want the associated actions to execute (for certain types of pipelines, for example), you can leave the default and just select actions for the Do section.

Reusing a series of conditions   If you have a series of conditions that you might want to reuse in another rule, you can create a macro for it. For more information, see Working with condition and action macros.

To add a condition:

1. In the Rule Editor, select the When section where you want to enter the condition and right-click to display the condition popup menu.

   

2. Select Add Condition.

   The condition property panel displays. The dropdown lists all installed conditions plus any custom conditions you have written and deployed.

3. Select the condition you want.

   The settable properties for the condition display on the panel.

       For information about using the installed conditions, see Installed Conditions.

4. Set the properties as required and exit the panel.

   The condition description appears in the Rule Editor. For example, choosing the Check Month condition displays a result like this:

   

To add more conditions:

1. In the Rule Editor, select the description of the condition below which you want to add a condition. To add the condition at the top, select the appropriate When element.

2. Right-click and select Add condition from the popup menu.

3. Add the condition as described in To add a condition:.

   By default, the condition is added with the AND operator, meaning that this and the previous condition must be true for the Do section to execute.

Selecting a logical operator for processing   When you have two or more conditions in a series, you can specify the OR operator if you want either condition to be true, and the NOT operator if you want a condition to be false.

To toggle the operator between AND and OR:

1. Select the condition containing the operator.

2. Right-click and select AND/OR from the popup menu.

To toggle the NOT operator to and from NOT:

1. Select the condition where you want to add or remove the operator.

2. Right-click and select NOT/NOT.

Editing and deleting conditions

This section describes other ways to edit conditions in the Rule Editor.

Deactivating a condition

If you want a condition not to be evaluated but do not want to delete it from the rule, you can deactivate it.

To toggle a condition between activate and deactivate:

1. Select the condition.

2. Right-click and select Active/Inactive from the popup menu.

Using actions

An action is a Java class that does something based on the condition it is associated with in a rule. Actions are added to the Do and Otherwise Do sections of a decision node. The Do section is activated if the When section of the node evaluates to true. The Otherwise Do section is executed when the When section is false.

For many of the installed actions, you can set relevant properties in the Rule Editor. You can also embed cases in an action and control the processing between decision nodes.

Default action   The default value for an action is return true.

To specify any other action (including return false), you need to add an action.

To add actions:

1. With the Rule Editor open, select the Do or Otherwise Do section where you want to enter the action, and right-click to display the conditions.

2. Select Add Action.

   The action property panel displays. The dropdown lists all the installed actions plus any custom actions you have written and deployed.

3. Select the action you want.

   The settable properties for the condition display on the panel.

       For information about properties, see Installed Actions.

4. Set the properties as required and exit the panel.

   The action description appears in the Rule Editor. For example, choosing the DenyAccess action displays a result like this:

   

To add additional actions for this node, repeat this procedure.

To add a case for an action:

1. In the Rule Editor, select the action where you want to insert a case.

2. Right-click and select Add Case from the popup menu.

Editing and deleting actions

This section describes other ways to edit actions in the Rule Editor.

Deactivating an action

If you want a condition not to be evaluated but do not want to delete it from the rule, you can deactivate it.

To toggle an action between activate and deactivate:

1. Select the action.

2. Right-click and select Active/Inactive from the popup menu.

Using cases

You can add When-Do sections to a parent node to make case statements (or child nodes) in a rule. Adding cases expands the tree control for the rule. You can add a case at the top (When) or in an embedded (Do) level of your logic.

You can handle the flow of processing for cases in two ways:

• Break specifies that if the When section is true, the rule ends with that case.

• Continue specifies that after the rule does the actions for the case, it goes on to evaluate the next node.

To add a case to a rule:

1. Select the When, Do or Otherwise Do section where you want to add a case.

2. Right-click and select Add Case from the popup menu.

   The Rule Editor adds a decision node (When-Do section).

3. Repeat Step 2 for each additional case.

4. Use the Rule Editor to add conditions and actions for each node.

To toggle the case processing value:

1. Select the Do section you want to change.

2. Right-click and select Break/Continue from the popup menu.

Adding case descriptions

If you have a complex rule with many cases, you can add a description for each to make them easier to identify. The description appears next to the When section that begins the case.

To add a case description:

1. Select the When section for the case you want to add the description to.

2. Right-click and choose Edit Description from the popup menu.

3. Add the description in the dialog and click OK.

   The description appears in the Rule Editor.

Using other case commands

The Rule Editor provides various other ways to manipulate cases.

To use other case commands:

1. Select the When section of the case.

2. Right-click and select the appropriate command from the popup menu:

   To	Do this
   Delete the case	Click Delete Case
   Deactivate/activate a case	Click Active/Inactive
   Copy a case	Click Copy Case
   Paste a case	Select the point where you want to paste and click Paste Case
   Move a case up one level in the logic	Click Move Case Up
   Move a case down one level in the logic	Click Move Case Down

Testing, editing, and saving rules

Testing rules

There are a couple of ways you can test rules before deploying them:

• Using the Run Rule command

• Using the RuleWrapper component

Using the Run Rule command

The Run Rule command displays rule return values in the Workbench console. Use this command to verify that the rule is returning the correct values at each logic point. The Run Rule command does not display actual return values, like HTML data.

To run a rule:

• With the Rule Editor open, select the Run Rule icon from the Workbench menu:

  

  Output for return values displays on the Workbench console.

  To clear the console:

  1. Place the cursor anywhere in the console area.

  2. Right-click and select Clear.

Using the RuleWrapper component

You can use the RuleWrapper component in the installed MyPortal application to display the result of any rule that returns HTML.

    For more information, see the chapter on sample components in Samples.

Saving and editing rules

When you save a rule, Workbench opens the appropriate subdirectory of the resource set in your project's source.

The ResourceSet.war is automatically installed with the Rule subsystem, in the Director Project Wizard. Among other functions, the resource set controls the processing of XML data and other resources in your Director project environment.

    For more information about the resource set, see the chapter on the Director product architecture in the Core Development Guide.

To save a rule:

1. With the rule open in the Rule Editor, select File>Save from the Workbench menu or press Ctrl-S.

   This displays a dialog with the content of the ResourceSet/data/rule directory in your Director project source. The file name is the rule name you provided in the Rule Editor.

2. Save the rule and exit the dialog.

To edit a rule:

1. Navigate to the location of the rule XML file in your project. The default location is ResourceSet/data/rule directory in your project source.

2. Double-click the rule XML file.

Editing the rule XML source

You can also edit the XML descriptor directly outside the Rule Editor. For more information, you can access the DTD and sample XML in your Director project source directory at:

• library/RuleService/RuleService-conf/DTD/rule_3_0.dtd

• library/RuleService/RuleService-conf/DTD/rule-basicRule_3_0_sample.xml

Working with condition and action macros

Macros allow you to save conditions and actions in reusable groups. For example, you might have standard logic that uses multiple conditions. Similarly, you might have a group of discrete actions that you want to fire under different conditions. Macros provide a higher level of organization while preserving the flexibility of using single conditions and actions.

Each macro is saved as an XML file. After you create a macro, you can add it to a condition and action in the Rule Editor.

Using condition macros

This section describes how to create a condition macro and use it in a rule.

To create a condition macro:

1. From the Workbench menu select File>New.

2. In the New File dialog select the Rules Engine tab.

3. Select the Condition Macro icon:

   

   The Condition Macro Editor displays.

   

4. Specify a name and description at the top of the Macro Editor.

   The name you specify is the default file name for the macro XML file.

5. Click the When section in the tree view.

6. Select Add Condition.

   The condition property panel displays.

7. Select a condition from the dropdown, as described in To add a condition:.

8. To add another condition, select the existing condition and right-click.

9. Add more conditions, as described in To add more conditions:.

10. Select an operator, as described in Selecting a logical operator for processing.

11. Edit, move, or delete conditions, as described in Editing and deleting conditions.

Saving and editing a condition macro

When you save a condition macro, Workbench opens the appropriate subdirectory of the resource set in your project's source.

    For more information about the resource set, see the chapter on the Director product architecture in the Core Development Guide.

To save a condition macro:

1. With your macro open in the Condition Macro Editor, select File>Save from the Workbench menu or press Ctrl-S.

   This displays a dialog with the contents of the ResourceSet/data/rule-condition-macro directory in your project source. The default file name is the macro name you provide in the Condition Macro Editor.

2. Save the macro and exit the dialog.

To edit a condition macro:

1. Navigate to the location of the macro XML file in your Director Workbench project.

2. Double-click the file.

Editing the condition macro XML source

You can also edit the XML descriptor directly outside the Rule Editor. For more information, you can access the DTD and sample XML in your Director project source directory at:

• library/RuleService/RuleService-conf/DTD/rule_conditionmacro_3_0.dtd

• library/RuleService/RuleService-conf/DTD/rule-conditionmacro_3_0_sample.xml

Using a condition macro in a rule

After you save the macro in an appropriate directory, you can use it in a rule.

To use a condition macro in a rule:

1. Open the rule in the Rule Editor.

2. Select the point in the When section where you want to add the macro.

3. Right-click and choose Insert Macro or Add Macro.

   A dropdown list of condition macro descriptions displays.

   

4. Select a macro and click OK.

To delete, inactivate, or move a macro within the rule:

1. Select the macro in the Rule Editor and right-click.

2. Select the appropriate command from the popup menu.

Using action macros

This section describes how to create an action macro and use it in the Rule Editor.

To create an action macro:

1. From the Workbench menu select File>New.

2. In the New File dialog, click the Rules Engine tab.

3. Select the Action Macro icon:

   

   The Action Macro Editor displays:

   

4. Specify a name and description at the top of the Action Macro Editor.

   The name you specify is the default file name for the macro XML file.

5. Click the Do section in the tree view.

6. Right-click and choose Add Action.

   The action property panel displays.

7. Select an action from the dropdown menu, as described in To add actions:.

8. To add another action, select the existing action and right-click.

9. Add more actions, as described in To add a case for an action:.

10. Edit, move, or delete actions, as described in Editing and deleting actions.

Saving and editing an action macro

When you save an action macro, Workbench opens the appropriate subdirectory of the resource set in your project's source.

    For more information about the resource set, see the chapter on the Director product architecture in the Core Development Guide.

To save an action macro:

1. With your macro open in the Action Macro Editor, select File>Save from the Workbench menu or press Ctrl-S.

   This displays the contents of the ResourceSet/data/rule-action-macro directory in your project source.

2. Save the macro and exit the dialog.

To edit an action macro:

1. Navigate to the location of the macro XML file in your project.

2. Double-click the file.

Editing the action macro XML source

You can also edit the XML descriptor directly outside the Rule Editor. For more information, you can access the DTD and sample XML in your Director project source directory at:

• library/RuleService/RuleService-conf/DTD/rule_actionmacro_3_0.dtd

• library/RuleService/RuleService-conf/DTD/rule-actionmacro_3_0_sample.xml

Using an action macro in a rule

After you save the action macro in an appropriate directory, you can use it in a rule.

To use an action macro in a rule:

1. Open the rule in the Rule Editor.

2. Select the point in the Do section where you want to add the macro.

3. Right-click and choose Insert Macro or Add Macro.

   A dropdown list of action macro descriptions displays.

   

4. Select a macro and click OK.

To delete, inactivate, or move a macro within a rule:

1. Select the macro in the Rule Editor and right-click.

2. Select the appropriate command from the popup menu.

Rules Guide

Copyright © 2002, SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.