Rules Guide

CHAPTER 4

Rule and Macro Editors

This chapter describes how to create and edit rules in exteNd Director. 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 exteNd Director applications, see How You Use Rules.

Accessing the Rule Editor

The Rule Editor is where you create rules to use in a portlet 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 exteNd Director project.

To access the Rule Editor:

1. From the exteNd Director 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:

   

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 exteNd Director, open the Rule Editor.

2. Enter the rule name in the ID text box. 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 text box.

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 condition 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 specify 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 table lists 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 statements 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 statement).

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 portlet

Using the Run Rule command

The Run Rule command displays rule return values in the development environment Output Pane. 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 exteNd Director menu:

  

  Output for return values displays on the development environment Output Pane.

  To clear the Output Pane:

  • Place the cursor anywhere in the pane.

  • Right-click and select Clear.

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

Saving and editing rules

To save a rule:

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

   The contents of the rule definitions folder display in your project resource set.

2. Save the rule and exit the dialog.

To edit a rule:

1. Navigate to the location of the rule XML descriptor in your project.

2. Double-click the rule XML file.

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 exteNd Director 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, exteNd Director opens the appropriate subdirectory of your project's resource set.

To save a condition macro:

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

   The contents of the rule-conditions-macro folder display in your project resource set.

2. Save the macro and exit the dialog.

To edit a condition macro:

1. Navigate to the location of the condition macro descriptor.

2. Double-click the file.

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 exteNd Director 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, exteNd Director opens the appropriate subdirectory of your project's resource set.

To save an action macro:

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

   The contents of the rule-action-macro folder display in your project resource set.

2. Save the macro and exit the dialog.

To edit an action macro:

1. Navigate to the location of the action macro descriptor.

2. Double-click the file.

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.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...