Defining Rules

 

Rules are used by the iiServer to evaluate the contents of a message and perform actions based on the evaluation results. You use the Rules interface to define rules and associated subscriptions.

Rules are defined within an application group/message type pair. Rules are uniquely identified by the application group/message type/rule name triplet.

Rule application groups allow you to easily maintain rules associated with business needs. An application group is a logical grouping used to organize rules. For example, a company can split rules into groups by projects or split projects into logical subgroups.

Each application group can contain several message types, and a message type can be in more than one application group. You define message types through the Rules definition mechanism. A message type defines the layout of a string of data. When using Formatter, the message type is the same as the input format name.

Each rule has evaluation criteria (called an expression) that consists of fields from the message and associated Rules operators linked together with Boolean operators. You define field names through the Formatter definition mechanism. Fields can be compared against constant data or other fields within a message.

A rule can have multiple subscriptions, and each subscription can have multiple actions. A subscription is created in the Subscription list, then assigned to one or more rules within an application group/message type.

A subscription is defined by an application group/message type in the same way as a rule. Subscriptions are groupings of actions processed when a rule evaluates true. A subscription cannot be executed if it is not assigned to a rule.

This section discusses the following topics:

• Starting Rules

• Building Rules

 

---

Starting Rules

You can access the Rules application by using the steps described in the following procedure.

1. Double-click the Rules icon. The Rules Logon dialog box appears as in Figure 4-1.

   Note: If you do not have an assigned user ID and password, ask your system administrator to create them for you.

   Figure 4-1 Rules Logon

   

2. Enter your user ID in the User ID field and press Tab.

3. Enter your password in the Password field and press Tab.

4. Select a database type from the DBMS drop-down list box. The database field appears or disappears based on your selection.

   • If you selected the Microsoft SQL server type, specify the server in the Server field and the database in the Database field.

   • If you selected an Oracle database type, specify the server in the Server field.

5. Click OK. The Rules main window appears as in Figure 4-2.

   Figure 4-2 Rules Main Window

   

The Rules main window is divided into two panes. Rules components are displayed in an hierarchical or tree-structured organization in the left pane, with Application Groups at the top level of the hierarchy. The right pane contains tabs that are associated with the selected object.

 

---

Building Rules

This section describes how to build the following Rules components:

• Application groups

• Message types

• Rules

• Expressions

• Subscriptions

• Actions

• Conditional branching

Application Groups

An application group allows you to logically organize rules associated with a particular subject. For example, an application group could be the accounting department of a company.

Adding an Application Group

You can add an application group using the steps described in the following procedure.

1. Select the New Application command under the Insert menu on the menu bar.

   A text box appears at the top of the application group list. The cursor is positioned in the application group text box where you can type an application group name.

   Note: The application group name must be 32 characters or less.

   If you are using a case-insensitive database, you cannot use the same name with a change in case to identify components. For example, you cannot name one application group D1 and another d1. In a case-insensitive environment, make each item unique using something other than case differences.

2. Press Enter to add the application group.

   The application group is highlighted and alphabetically positioned in the list in the left pane, and the New Message property sheet appears in the right pane.

   An application group should contain at least one message type, which corresponds to your input formats. For the procedure to add a message type, refer to Adding a Message Type.

Copying an Application Group

You can copy an application group by using the steps in the following procedure.

1. Select the application group you want to duplicate.

2. Hold down the right mouse button to activate the pop-up menu and select Duplicate.

   The cursor is positioned in the application group text box. Type a unique application group name.

3. Press Enter to copy the application group and its components (messages, rules, and subscriptions) to the new application group name.

   Note: The application group name must be 32 characters or less.

Deleting an Application Group

You can delete an application group by using the steps described in the following procedure.

1. Select the application group you want to delete.

2. Hold down the right mouse button to activate the pop-up menu and select Delete. The delete confirmation box appears.

3. Click OK to delete the application group. The Delete box closes, and the application group and its components (messages, rules, and subscriptions) are deleted.

Message Types

The message type is the input format name from Formatter. A rule is evaluated based on the message type.

An application group should contain at least one message type. For the procedure to add an Application Group, see Adding an Application Group.

Adding a Message Type

You can add a message type by using the steps described in the following procedure.

1. Select the application group that you want to add a message type to. The list of current message types and the New Message tab is displayed in the right pane.

2. Select the New Message property sheet. The property sheet appears as in Figure 4-3.

   Figure 4-3 New Message Property Sheet

   

   The Available box on the left displays available message types. This list contains the input format names defined in Formatter.

   The Current box on the right displays the message types currently associated with the application group.

3. Select the message type from the Available list box and double-click to add a message type to the selected application group.

   The message type appears in the Current list box and in the left pane below the application group.

4. Select the message type from the Current list box and double-click to delete a message type from the selected application group.

Copying a Message Type

You can copy a message type to a different application group using the steps described in the following procedure.

1. Select the message type to duplicate in the left-hand pane.

2. Drag the message type to the application group you want to add it to in the left-hand pane.

Deleting a Message Type

You can delete a message type using the steps described in the following procedure.

1. Select the message type you want to delete.

2. Hold down the right mouse button to activate the pop-up menu and select Delete. The Delete box appears.

3. Click OK to delete the message type. The Delete box closes and the message type is deleted.

Rules

A rule contains subscriptions that allow you to define message destination IDs, receiver locations, message formats, and any processes initiated upon message delivery.

Adding a Rule

You can add a rule using the steps described in the following procedure.

1. Select the message type that you want to define a rule for from the Rules window tree and click the right mouse button. A pop-up menu appears.

2. Select New Rule. The cursor is positioned in the rule text box where you can type a unique rule name.

   Note: The rule name must be 32 characters or less.

3. Press Enter to add the rule.

   The rule is highlighted and alphabetically positioned in the list to create a new rule in the left pane. The Expressions property sheet appears in the right pane.

   For the Rules engine to correctly process a rule, you must define the rule's expression and subscription. The procedure to add an expression to a rule is described in Expressions. The procedure to add a subscription to a rule is described in Subscriptions.

Deleting a Rule

When you delete a rule, the expression and links to subscriptions belonging to the rule are also deleted. The subscriptions are not deleted.

You can delete a rule by using the steps described in the following procedure.

1. Select the rule that you want to delete.

2. Hold down the right mouse button to activate the pop-up menu and select Delete. The Delete box appears.

3. Click OK to delete the rule. The Delete box closes, and the rule is deleted.

Copying a Rule

The Duplicate function lets you copy the selected rule, which includes the rule's associated expression and its links to subscriptions. The new rule is owned by the current user who has update permission.

You can duplicate a rule by using the steps described in the following procedure.

1. Select the rule that you want to duplicate.

2. Hold down the right mouse button to activate the pop-up menu and select Duplicate.

   The cursor is positioned in the rule box where you can type a unique rule name.

   Note: The rule name must be 32 characters or less.

3. Press Enter to save the name.

   To change the rule's expressions, select the Expression tab and make the changes. For more information, refer to Expressions.

   To change a rule's subscriptions, select the Subscription tab and make the changes. For more information, refer to Subscriptions.

Enabling a Rule

You can enable a disabled rule by using the steps described in the following procedure.

1. Select the rule that you want to enable.

2. Hold down the right mouse button to activate the pop-up menu.

3. Select Enable. The fields in the Expression tab are now active.

Disabling a Rule

You can disable a rule by using the steps described in the following procedure.

1. Select the rule that you want to disable.

2. Hold down the right mouse button to activate the pop-up menu.

3. Select Disable. The fields in the Expression tab are now inactive.

Expressions

The Expression tab is used to create, modify, or delete an expression for a selected rule.

The following tabs appear within the Expression tab:

• Expression Components-Combinations of expression strings used to automate typing for a user

• Field List-List of fields that appear in the format

• Operators-Comparison operator choices

• Values-Masked values for integers, strings, and so forth

• Functions-Symbols used in the expression such as & (AND), | (OR), and parentheses

The evaluation criteria for a rule consists of a Boolean expression containing the Boolean operators & and |, expressions, and parentheses to control the order of evaluation. You can use | to explicitly direct what Boolean operations do together.

There must be at least one space between the field name and the Rules operator as well as between the Rules operator and the comparison value. The EXIST and NOT_EXIST operators should be followed by at least one space before a parenthesis or a Boolean operator.

Creating or Modifying an Expression

You can create or modify an expression using the steps described in the following procedure.

1. Select the appropriate rule.

2. Select the Expression tab. The tab appears as in Figure 4-4.

   Figure 4-4 Expression Tab

   

3. Select the Expression Components tab. Select (by clicking or double-clicking) an Expression Component in the Rules tree to display it in the Expression tab.

   Use the Doubleclick checkbox to modify mouse action to a click or a double-click when selecting expression components.

4. Use the Field List, Operators, Values, and Functions tabs to add components to your expression.

   Notes: The Literals AND and OR do not evaluate correctly in a rules expression. If you enter these values, a message box appears stating the expression is valid, but AND will be changed to &, and OR will be changed to |.

   You can type the expression directly into the Expression box without using the component tabs. You can modify the expression by right clicking within the Expression window to access the text edit menu. Use the following text edit functions to modify your expression: Undo your last change, Cut, Copy, Paste, Delete, and Select All of the text within the Expression window.

   You can create an expression that defaults to true to define a rule that will always be processed. To do this, type TRUE in the Expression box. In this case, subscriptions associated with this rule will also always be processed.

5. Click Verify to validate the final expression. This tests the expression but does not save it to the iiDatabase.

6. Click Apply to either create or modify an expression.

   If you move out of the Expression tab by using the mouse or the keyboard, the expression is automatically saved.

Examples of expressions are shown in Table 4-1.

Table 4-1 Expression Examples

Description	Layout	Expression
Default to TRUE		TRUE
Single Argument	A	F1 STRING= Acct
Arguments use AND	A & B & C	F1 STRING= Acct & F2 INT= 100 & F3 INT= 150
Arguments use OR	A | B | C	F1 STRING=Acct | F2 INT= 100 | F3 INT= 150
Precedence	A | B & C	F1 STRING= Acct | F2 INT= 100 & F3 INT= 150
Nested Parens	(A | ((B & (C)) | D))	(F1 STRING= Acct | ((F2 INT= 100 & (F3 INT= 150)) | F4 INT= 200))

Clearing an Expression

You can clear an expression for a selected rule using the steps described in the following procedure.

1. Select the rule that contains the expression you want to clear. The expression is displayed in the Expression box.

2. Click Clear, and enter a new expression.

   Note: Rules will not allow you to overwrite an existing expression with a blank expression.

3. Click Apply to update the iiDatabase.

Subscriptions

After a rule is created, subscriptions that contain actions should be added to the rule's Subscription List. Each application/message group has its own Subscription List. You can drag and drop one or more subscriptions to any rule from the Subscription List or drag and drop into the Subscription List tab of a rule.

A subscription describes the actions that are performed if the rule's expressions pass evaluation. A subscription allows you to define message destination IDs, receiver locations, message formats, and any processes initiated upon message delivery.

A subscription can only be assigned to a rule within the same application group/message type.

Note: A subscription can be assigned to several rules if the rules are in the same application group and message type.

Adding a Subscription

You can add a subscription by using the steps described in the following procedure.

1. Select the Subscription List for the Application Group/Message Type that you want to add a subscription to from the Rules window tree and click the right mouse button. A pop-up menu appears.

2. Select New Subscription. The cursor is positioned in the Subscription List text box where you can type a unique subscription name.

   The subscription name must be 64 characters or less.

3. Press Enter to add the subscription to the Subscription List.

   If there is no duplicate name for this subscription, the subscription is added and the Actions tab appears.

   Each subscription should have at least one action. For the procedure to add an action, see Adding an Action.

Duplicating a Subscription

You can copy a subscription by using the steps described in the following procedure.

1. Select the subscription that you want to duplicate from the Subscription List.

2. Hold down the right mouse button to activate the pop-up menu and select Duplicate. A text entry box appears at the top of the rules list.

3. Type a unique subscription name in the text box and press Enter to save a copy of this subscription with a new name.

Deleting a Subscription

A subscription can only be deleted if it is not linked to any rules from the Subscription List.

If you own the subscription and the subscription is not linked to any rules, the subscription is deleted.

You can delete a subscription by using the steps described in the following procedure.

1. Select the subscription that you want to delete from the Subscription List.

2. Click the right mouse button to activate the pop-up menu and select Delete. The Delete box appears.

3. Click OK to delete the subscription. The delete box closes, and the subscription is deleted.

Adding a Comment to a Subscription

You can associate a comment with a subscription by using the steps described in the following procedure. A comment must be 64 characters or less.

1. Select the subscription for which you want to add a comment from the Subscription List.

2. Select the Misc tab. A Comments text entry box appears containing the word "None" (if no comments were previously added) as in Figure 4-5.

   Figure 4-5 Misc Tab

   

3. Select and delete the word None and type your comment.

4. Click Apply to save your comment.

Removing a Subscription

Use the Remove function to remove a subscription from a rule. You cannot remove a subscription from the Subscription List, only from a rule. After you remove the subscription from the rule, the subscription will still be in the Subscription List.

You can remove a subscription by using the steps described in the following procedure.

1. Select the subscription you want to remove from the specific rule.

2. Click the right mouse button to activate the pop-up menu and select Remove. The Remove box appears.

3. Click OK to remove the subscription. The remove box closes, and the subscription is removed from the rule.

Actions

Actions hold subscription instructions. The Actions affecting subscriptions include:

• Reformat

• Enqueue

• Post

• Call

• Call Async

• Explode

• Return

Adding an Action

You can add an action to a subscription by using the steps described in the following procedure.

1. Select the subscription in which you want to add an action. The Actions tab appears as in Figure 4-6.

   Figure 4-6 Actions Tab

   

2. Select the action that you want to add, hold down the left mouse button, and drag the action to the Action List box. Then do one of the following:

   • To add the action to the bottom of the list, drop the action onto the gray space below the last action in the list.

   • To insert the action above an existing action, drop the action on top of the position you want the action to be above.

     The parameters you enter in the Action Values box should be based on the type of action selected. The action types are described in Table 4-2.

     Table 4-2 Subscription Actions

     Action	Description
     Reformat	Identifies the input and output message formats used when reformatting a message. In addition, the names of the input and output messages are assigned. These names may be used in other actions to identify the buffer to be used. Note: The FMLVO Name parameter is only used when the output type is set to FMLVO.
     Enqueue	Identifies all the data required to place a typed buffer on a Tuxedo queue. In addition, you can optionally specify the values to be used for reply queue, failure queue, and priority.
     Post	Permits entry of all the information required to post a typed buffer to the Tuxedo event broker.
     Call	Obtains the necessary information to send a typed buffer to another Tuxedo service and accept a reply from that service. Note: The FMLVO Name, Error Q Space, and Error Q Name parameters are optional.
     Call Async	Gathers information required to send a typed buffer to another Tuxedo service. Note: No reply is returned from the called service.
     Explode	Parses an input message into its component parts using a supplied input format. After parsing is complete, explode performs the next action in the subscription list for each member of the subcomponent. The explode action taken for each action type includes: Enqueue-The enqueue action is performed for each matching subcomponent. Post-The post action is performed for each matching subcomponent. Call Async-The call async action is performed for each matching subcomponent. Note: The Reformat, Call, Explode, and Return actions cannot be used after an Explode action.
     Return	Identifies the buffer that is returned to the client. The return action must be the last action defined.

3. Click Apply to save the actions.

Deleting an Action

You can delete an action by using the steps described in the following procedure.

1. Select the action that you want to delete in the Action List.

2. Position the cursor on the action and press the right mouse button to open the pop-up menu.

3. Select Delete Action from the pop-up menu. The action is deleted from the Actions tab.

4. Click Apply to delete the action.

Conditional Branching

If Rules is started from the Formatter interface, Rules opens in Conditional Branching mode. The only application group that appears in the Rules tree is II_FORMATTER.

You can add message types, rules, arguments, subscriptions, and actions to the II_FORMATTER application group using the procedures described earlier in this section. However, there is a difference in the Actions tab.

The Actions tab only contains the Rules Field action. When adding or inserting Rules Field actions, three options are necessary:

• FIELD_NAME

• OUTPUT_FORMAT

• FORMAT_CONTROL

See Adding an Action for details on adding and changing actions and options.