Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
eLink Information Integrator Doc Home | eLink Information Integrator User Guide | Previous Topic | Next Topic | Contents | Index

Defining Rules

This chapter describes Information Integrator Rules. The following topics are discussed:

- Understanding Information Integrator Rules

- Starting Rules

- Building Rules

- Example

Understanding Information Integrator Rules

Rules determine the runtime behavior of Information Integrator. Rules enable you to evaluate the data contained in a message and determine the Actions or tasks that will be performed based on the evaluation of that data.

A Rule consists of two parts: an Expression and a Subscription List. An Expression is the evaluation criteria for a Rule. It consists of a Boolean expression created from the fields in a message and comparison operators. A Subscription List contains multiple Subscriptions. Each Subscription consists of one or more Actions. An Action is an atomic task that is performed on the data in the message, such as, Reformatting the data or Enqueing the data to a queue. When a Rule's Expression evaluates to TRUE, the Subscriptions in the Rule's Subscription List will be executed.

Application Groups and Message Types categorize Rules. The coarsest division of Rules is into Application Groups. Application Groups are logical divisions of sets of Rules for different business needs. For example, there might be an Application Group for each department in a company. The Message Type further categorizes Rules. It is the same as the Input Format that is used to parse the message (see Building Format Definitions for more information on Input Formats). Each Application Group can have multiple Message Types, and each Message type may contain multiple Rules.

A service advertised by the Information Integrator Server is associated with a unique Application Group and Message type. When a client to the IISERVER makes a request for a particular service, the Expression for each Rule associated with that Message Type under the given Application Group is evaluated. The subscriptions associated with each TRUE Expression are then executed.

Using the Rules graphical user interface (GUI) you can define the various components of Rules in the following order:

- Application Groups

- Message Types

- Rules

- Expressions

- Subscriptions

- Actions

Rules are defined within an application group/message type pair, and are uniquely identified by the application group/message type/rule name. Figure 6-1 illustrates the Rules hierarchy.

Figure 6-1 Rules Hierarchy Diagram

Using the Rules Interface

You use the Rules graphical user interface (GUI) to define the rules components. The following sections describe the Rules GUI.

Starting Rules

Start the Rules GUI as follows.

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

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

   Figure 6-2 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 6-3.

Using the Rules Window

This section gives you instructions and tips for navigating through the Rules GUI. Refer to it for assistance in working in the Rules application as needed.

Each Rules window is split into two panes (see Figure 6-3). The left pane is a navigation tool and the right pane displays details about components selected in the left pane.

Figure 6-3 Rules Main Window

The left pane displays a list of all Application Groups and their associated Message Types, Rules, and Subscriptions. Single-click each category to just display a list of its contents in the right pane. Double-click each category to display its contents in the tree. For example, double-click to expand an Application Group. You can then double-click a Message Type name (or click on the + sign to its left) to display its associated Rules and Subscriptions.

The right pane, or Property Sheet, is where you will add the majority of information. It uses tabbed sheets to display the details for whichever object is currently selected. For example, if you have an Application Group selected, you can view the Message Type List and New Message tabs.

Note: You can open more than one Rules window at a time for access to multiple component types at the same time.

Opening a New Window

To open a new window, select New from the File menu.

Tip

When the Rules window opens, it may default to a size too small to display all window components, including the Apply and Cancel on some property sheets. Maximize the application or resize the window to see all window components.

Renaming Components

Rules components can be renamed in the left pane of the Rules window. To rename a component, follow these steps.

1. In the left pane of the Rules window, select the component name.

2. Click again without moving the mouse a text box appears around the selected component name and is highlighted.

3. Edit the component name.

4. Press ENTER or click the mouse outside the component name text box. If there is no duplicate name, the component name is highlighted and moves to its alphabetical location in the list.

   Note: Since Message Types are the same as the Input Formats created using Formatter or MsgDefAdmin, you cannot change Message Type names from the Rules window. Message Types must be renamed in Formatter. For more information, see Using the Formatter Interface.

Duplicating Components

Rules components can be duplicated in the left pane of the Rules window. To duplicate a component, follow these steps.

1. In the left pane of the Rules window, select any user-defined component and right-click. A popup menu appears.

2. Select Duplicate. A copy of the component is made and a text box appears around the duplicated component name.

3. Type the new component name.

4. Press ENTER or click the mouse outside the component name text box. If there is no duplicate name, the component name is highlighted and moves to its alphabetical location in the list.

Deleting Components

Rules components can be deleted in the left pane of the Rules window. To delete a component, follow these steps.

1. In the left pane of the Rules window, select a user-defined component and right-click. A popup menu appears.

2. Select Delete. A dialog box appears asking if you are sure you want to delete the component.

3. Choose either Yes or No to confirm or cancel your action.

Using Drag and Drop

You can use drag and drop to:

- Assign Actions to Subscriptions

- Assign Subscriptions to Rules

Drag and drop works across both windows and panes. To copy an object using drag and drop, you must drag the object from the first window's tree to the second window's property sheet.

Building Rules

This section describes how to build the following Rules components:

- Application Groups

- Message Types

- Rules

- Expressions

- Subscriptions

- Actions

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.

To add an application group, follow these steps.

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.

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 Message Types.

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 Application Groups.

To add a message type, follow these steps.

1. Select the application group to which you want to add a message type. 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 6-4.

   Figure 6-4 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 click >>> or 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. To delete a message type from the selected application group, select the message type from the Current list box and click <<< or double-click. The message type is removed from the Current list box.

Rules

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

To add a rule, follow these steps.

1. Right-click the message type for which you want to define a rule. 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.

   Note: When the first rule is created, a subscription list is automatically created for the application group.

   For the Rules engine to correctly process a rule, you must define the rule's expression and subscription(s) or subscription list. 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.

Disabling and Enabling a Rule

You can temporarily "turn off" a rule by disabling it. This means that the message will not be evaluated against the disabled rule.

To disable a rule, follow these steps.

1. Right-click the rule you want to disable. A pop-up menu appears.

2. Select Disable. The rule is now disabled for the message.

When you want to "turn on" the rule again, follow these steps.

1. Right-click the rule you want to enable. A pop-up menu appears.

2. Select Enable. The rule is now enabled for the message.

   Notes: Rules are automatically enabled when you create them, and remain enabled until you disable them. Rules remain disabled until you enable them again.

Expressions

The Expression tab is used to create, modify, or delete an expression for a selected rule. You can create an expression by entering it directly in the Expression text area, or by building it interactively using the sub-tabs at the bottom of the Expression tab (see Figure 6-5). The following sub-tabs appear within the Expression tab:

- Expression Components - Contains a list of expression templates, combining one or more sets of arguments and Boolean operators for a complete expression phrase.

- Field List - Contains a list of field names associated with the selected message type. You define field names when you create an input format.

- Operators - Comparison operator choices. For an explanation of all valid operators, refer to Operators.

- Values - Contains the matching data types of the operator in the operation expression field.

- 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) and | (OR), expressions, and parentheses to control the order of evaluation. You can use | to explicitly direct what Boolean operations do together.

Notes: 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

To create or modify an expression, follow these steps.

1. Select the appropriate rule.

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

   Figure 6-5 Expression Tab

3. Select the Expression Components sub-tab.

4. If you want to double-click expression components to add them to the expression, check the Doubleclick checkbox. If you would rather single-click expression components to add them to the expression, clear the Doubleclick checkbox.

5. Build the rest of the expression by using the other subtabs (Field List, Operators, Values, Functions) and clicking or double-clicking their components as needed.

6. Click Verify if you want to check the final expression and make sure it is valid. If it is not, an error message displays, showing you the location of the error in the expression. Correct the error by doing one of the following:

   1. Click Input on the error message window and enter the correction in the User Input text area.

   2. Click OK on the error message window and correct the error directly in the Expression text area.

      Note: Click Clear to erase the contents of the Expression text area.

7. When you have finished creating or updating the expression, click Apply to save the expression to the Database.

   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; however, AND is changed to &, and OR is changed to |.

   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 6-1.

####

Table 6-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))

Subscriptions

Subscriptions are lists of actions to take when a message evaluates true. Each rule must have at least one associated subscription. Subscriptions enable you to define message destination IDs, subscriber locations, message formats, and any processes initiated on message delivery.

Subscriptions are created in Subscription Lists. There are two types of subscription lists. There is a subscription list for each application group/message type. This list is created when the first rule is added to the message type. There is also a subscription list for each rule. This list contains only those subscriptions that are associated with the rule (see Associating Subscriptions with Rules for more information).

To add a subscription, follow these steps.

1. Right-click the Subscription List for the Application Group/Message Type to which you want to add a subscription. 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.

   Note: 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.

4. To add a comment to the Subscription, choose the Misc tab and type the comment in the Comments field.

5. Click Apply when finished. This creates the subscription list for the application group/message type.

6. Continue with the procedures described in Associating Subscriptions with Rules.

   Notes: Each subscription must have at least one action. For the procedure to add an action, see Actions.

   For hints on creating subscriptions by using a combination of actions, refer to Combining Actions to Create Subscriptions.

Associating Subscriptions with Rules

Creating a subscription does not automatically associate the subscription with a rule. In order for the actions in the subscription to be executed, you must associate the subscription with a rule by doing the following:

1. From the subscription list for the application group/message type, click and hold the left mouse button on the desired subscription.

2. While holding the left mouse button, drag the subscription from the right pane to the desired rule in the left pane.

3. When the cursor is over the desired rule, release the left mouse button. The subscription is now associated with the rule, and appears below the rule in the left pane.

   Note: Subscriptions may only be assigned to a rule within the same message type and application group pair. A subscription can be assigned to several rules if the rules are in the same application group and message type.

Actions

Actions hold subscription instructions. The Actions affecting subscriptions are as follows:

- Reformat - Identifies the input and output message formats used when reformatting a message. In addition, the numbers of the input and output messages are assigned. These numbers may be used in other actions to identify the buffer to be used. For instructions on adding a Reformat action, refer to Adding a Reformat Action.

- 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. For instructions on adding an Enqueue action, refer to Adding an Enqueue Action.

- Post - Permits entry of all the information required to post a typed buffer to the Tuxedo event broker. For instructions on adding a Post action, refer to Adding a Post Action.

- Call - Obtains the necessary information to send a typed buffer to another Tuxedo service and accept a reply from that service. For instructions on adding a Call action, refer to Adding a Call Action.

- Call Async - Gathers information required to send a typed buffer to another Tuxedo service. For instructions on adding a Call Async action, refer to Adding a Call Async Action.

- 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.

    For instructions on adding an Explode action, refer to Adding an Explode Action.

- Cast - Reformats an entire message to a different type of buffer. For instructions on adding a Cast action, refer to Adding a Cast Action.

- Return - Identifies the buffer that is returned to the client. The return action must be the last action defined. For instructions on adding a Return action, refer to Adding a Return Action.

  Note: The Reformat, Call, Cast, Explode, and Return actions cannot be used after an Explode action.

To add an action to a subscription, follow these steps.

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

   Figure 6-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.

3. Click Apply to save the actions.

Adding a Reformat Action

1. Use the Input Format drop down list to select an Input Format.

2. Use the Input Message drop down list to select the message to be reformatted (if this is the first action, this will be message 1).

3. Use the Output Format drop down list to select an Output Format.

4. The Output Message is automatically generated.

5. Use the Output Type to select an Output type for this message.

6. If FMLVO is selected as the Output Type, enter the FML field name for output data.

Adding an Enqueue Action

1. Use the Input Message drop down list to select the message to be placed on a Queue (if this is the first action, this will be message 1).

2. Enter the name of the Queue Space where the message will be sent.

3. Enter the Queue Name where the message will be sent.

4. Enter the name of the Reply Queue (this field is optional).

5. Enter the name of the Failure Queue (this field is optional).

6. Select a Priority for this request (this field is optional).

Adding a Post Action

1. Use the Input Message drop down list to select the message to be Posted to the Tuxedo event broker (if this is the first action, this will be message 1).

2. Enter the Event Name to be Posted

Adding a Call Action

1. Use the Input Message drop down list to select the message to be input to the called service (if this is the first action, this will be message 1). The Output Message is automatically generated.

2. Enter the Service Name that will be Called.

3. Enter the FML field name for output data. This field is optional and is only used for FML value processing.

4. Enter the name of the Error Queue Space (this field is optional).

5. Enter the name of the Error Queue (this field is optional).

Adding a Call Async Action

1. Use the Input Message drop down list to select the message to be input to the called service (if this is the first action, this will be message 1).

2. Enter the Service Name to be Called.

   Note: No reply is returned from the called service.

Adding an Explode Action

1. Use the Input Format drop down list to select an Input Format.

2. Use the Input Message drop down list to select the message to be reformatted (if this is the first action, this will be message 1).

3. Use the Output Format drop down list to select an Output Format.

4. Use the Output Type to select an Output type for this message.

5. If FMLVO is selected as the Output Type, enter the FML field name for output data.

   Note: The Explode action cannot be followed by any action that creates new buffers, such as Reformat, Call, or Cast. Explode is used for messages in which there are some variable number of identical parts. The action that immediately follows the Explode action is applied to each of the items in the exploded message.

Adding a Cast Action

1. Use the Input Format drop down list to select an Input Format.

2. Use the Input Message drop down list to select the message to be reformatted (if this is the first action, this will be message 1). The Output Message is automatically generated.

3. Use the Output Type to select an Output type for this message.

4. If FMLVO is selected as the Output Type, enter the FML field name for output data.

Adding a Return Action

- Use the Input Message drop down list to select the message to be returned (if no buffer is to be returned, select 'NULL Message')

Deleting an Action

To delete an action, follow these steps.

1. Right-click on the action you want to delete in the Action List. A pop-up menu appears.

2. Choose Delete Action. The action is deleted from the Actions tab.

3. Click Apply to delete the action from the subscription.

   Note: If you delete an action that generates a new buffer (Reformat, Call, or Cast), the message numbers for subsequent actions in the subscription may change. This is to account for the fact that the output message from the deleted action no longer exists. All input and output message numbers greater than the deleted output message numbers are decremented. Any input messages that used that output message number will be blank, and you must manually reset these to valid message numbers.

Combining Actions to Create Subscriptions

The Information Integrator Rules application allows you to accomplish multiple tasks on messages using subscriptions. Subscriptions are simply actions that you combine in the appropriate order to achieve the desired results. Any number of actions can be combined to create a subscription. Therefore, the incoming message must be able to be successfully parsed with the Input Format for the first action in a subscription. The Input Format for the first action in a subscription will generally be the same as the Application Group's Message Type. The Input Message for the first action in the subscription is automatically set to 1, signifying that the input buffer for this action is the original message buffer.

The Reformat, Call, and Cast actions generate new buffers. When any one of these actions is added to a subscription, the Output Message is automatically set to one number greater than the highest Message number in the subscription. The new message number is added to the drop down list of possible Input Message numbers for all actions added after that action.

The Explode action is used for messages with a variable number of identical parts. The action that immediately follows the Explode action is applied to each of the component pieces of the exploded message. The Input Message parameter for the action following Explode can be any of the possible values. Since it is the action following an Explode, the results of the Explode are automatically used as the Input Message for this action. Explode cannot be followed by any action that creates new buffers, such as Reformat, Call, or Cast. If the results of an Explode action need to be reformatted, this reformatting must be configured in a separate subscription.

If a Return action is included in a subscription, it must be the last action in the subscription. This is because rule evaluation terminates at the end of all rules or at the first Return action encountered.

Example

This section outlines the procedure required to complete Step 6 in Using Information Integrator. In Step 6, you define the actions required to perform the data translation for the sample application.

In the steps that follow, we will create a new application group, message type, rule, and subscription list, and assign the subscription list to the rule.

To create an new application group, follow these steps.

1. Open the Rules application.

2. Right-click Application Groups in the left pane of the Rules window and select New Application from the popup menu.

3. Type II_Sample as the name of the new application group in the left pane and press Enter. The New Message tab displays in the right pane see (Figure 6-7).

   Figure 6-7 New Message Tab

We will now create a new message type in the new application group.

- From the New Message tab, select II_payroll_msg1_I from the Available list and click >>> to move it to the Current list. This adds the message to the II_Sample application group you created (see Figure 6-8).

  Figure 6-8 New Message Type

We will now create a new rule within in the new message type.

1. Right-click II_payroll_msg1_I in the left pane and select New Rule.

2. Type II_Sample_Rule as the name of the new rule and press Enter. This adds the rule to the II_payroll_msg1_I message type you created (see Figure 6-9).

   Figure 6-9 New Rule

We will now create an expression for the new rule.

1. On the Expression tab, type TRUE in the Expression text area. This tells Information Integrator that you want the actions in the rule to execute unconditionally.

2. Click Apply. This creates the expression for the II_Sample_Rule (see Figure 6-10).

   Figure 6-10 Expression for II_Sample_Rule

We will now create a subscription list to hold the actions we want Information Integrator to perform.

1. Right-click Subscription List under II_payroll_msg1_I in the left pane and select New Subscription.

2. Type II_Sample_Sub as the name of the new subscription and press Enter. This adds the subscription to the subscription list for the II_payroll_msg1_I message type (see Figure 6-11).

   Figure 6-11 New Subscription

We will now add actions to the new subscription. We want to reformat the input data and return the reformatted data.

1. On the Actions tab, click on the Reformat action and drag it into the Action List for this subscription.

2. From the Input Format drop down list, choose II_payroll_msg1_I to select it as the input format.

3. From the Input Message drop down list, choose 1 to assign the number "1" to the incoming message.

4. From the Output Format drop down list, choose II_payroll_msg1_O to select it as the output format.

   Note: The Output Message defaults to 2, assigning the number "2" to the output data.

5. From the Output Type drop down list, choose FML32 to indicate that the output message is in FML32 format.

6. Click on the Return action and drag it into the Action List.

7. From the Return Message drop down list, choose 2. This indicates that the data you want to return is the result of the Reformat action (Output Message 2).

8. Click Apply. This creates the subscription in the II-Sample_Sub subscription list (see Figure 6-12)

   Figure 6-12 Subscription for II_Sample_Sub

We will now add the subscription we just created to the II_Sample_Rule.

Note: This must be done in order for the actions in the subscription to be executed. Simply creating the subscription does not associate it with a rule.

1. Click II_Sample_Sub in the left pane of the Rules window and hold down the left mouse button.

2. Drag II_Sample_Sub to II_Sample_Rule and release the left mouse button. The subscription II_Sample_Sub appears under the II_Sample_Rule, indicating that it is associated with this rule, and its actions will be executed (see Figure 6-13).

   Figure 6-13 II_Sample_Sub Associated with II_Sample_Rule

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.