10 Business Rule Definition

This chapter describes the Business Rule Definition of Oracle Identity Manager. It contains the following topics:

• "Overview"

• "The Event Handler Manager Form"

• "The Data Object Manager Form"

• "The Reconciliation Rules Form"

Overview

The Development Tools/Business Rule Definition folder provides System Administrators and developers with the tools necessary to manage the event handlers and data objects of Oracle Identity Manager. This folder contains the following forms:

• Event Handler Manager: This form allows you to create and manage the event handlers that are used with Oracle Identity Manager.

• Data Object Manager: This form allows you to define a data object, assign event handlers and adapters to it, and map any adapter variables associated with it.

The Event Handler Manager Form

Figure 10-1 displays the Event Handler Manager form, which is located in the Development Tools/Business Rule Definition folder. It is used to manage the Java classes that process user-defined or system-generated actions (or events). These classes are known as event handlers. When you add a new event handler to Oracle Identity Manager, you must first register it here, so Oracle Identity Manager can recognize it.

Figure 10-1 Event Handler Manager Form

Description of "Figure 10-1 Event Handler Manager Form"

There are two types of event handlers:

• Event handlers that are created through the Adapter Factory form. These event handlers, which begin with the letters "adp," are known as adapters.Event handlers that are created internally within Oracle Identity Manager. These event handlers, which begin with the letters "tc," are referred to as system event handlers.

In addition, through the Event Handler Manager form, you can specify when you want Oracle Identity Manager to trigger an event handler. An event handler can be scheduled to run on:

• Pre-Insert: Before information is added to the database

• Pre-Update: Before information is modified within the database

• Pre-Delete: Before information is removed from the database

• Post-Insert: After information is added to the database

• Post-Update: After information is modified within the database

• Post-Delete: After information is removed from the database

Important: To actually use an event handler, you must attach it to a data object (using the Data Object Manager form). For more information on assigning event handlers to data objects, refer to "The Data Object Manager Form".

You will now learn about the data fields of the Event Handler Manager form. Table 10-1 describes the data fields of this form.

Table 10-1 Data Field

Field Name	Descriptions
Event Handler Name	The name of the event handler.
Package	The Java package to which the event handler belongs.
Pre-Insert	By selecting this check box, Oracle Identity Manager can trigger the event handler before information is added to the database.
Pre-Update	If you select this check box, Oracle Identity Manager can trigger the event handler before information is modified within the database.
Pre-Delete	By selecting this check box, Oracle Identity Manager can trigger the event handler before information is removed from the database.
Post-Insert	If you select this check box, Oracle Identity Manager can trigger the event handler once information is added to the database.
Post-Update	By selecting this check box, Oracle Identity Manager can trigger the event handler after information is modified within the database.
Post-Delete	If you select this check box, Oracle Identity Manager can trigger the event handler once information is removed from the database.
Notes	Additional information about the event handler.

Now that we have reviewed event handlers and the data fields of the Event Handler Manager form, you are ready to create and modify event handlers.

Add or Modify an Event Handler

To add or modify an event handler, perform the following steps:

1. Open the Event Handler Manager form.

2. If you are adding an event handler to Oracle Identity Manager, enter the name of the event handler into the Event Handler Name lookup field.

   If you are modifying an event handler, double-click the Event Handler Name lookup field. From the Lookup dialog box that appears, select the event handler that you wish to edit.

   
   

   Caution: Any event handlers that begin with the letters "adp" is associated with adapters, and should not be modified. However, you can modify system event handlers (event handlers that begin with the letters "tc").

   
   

3. In the Package field, add or edit the name of the Java package of which the event handler is a member.

4. Select or clear the checkboxes that correspond to when you want Oracle Identity Manager to either trigger the event handler or not activate the event handler, respectively. An event handler can be scheduled to run on pre-insert, pre-update, pre-delete, post-insert, post-update, and post-delete.

   
   

   Important: Selecting a check box does not mean that the event handler will be triggered at that time (for example, on pre-insert). It signifies that the event handler can run at that time.

   
   

In the Notes area, you can add or edit explanatory information about the event handler. Click Save. The event handler you added or modified will now reflect the settings you have entered.

The Data Object Manager Form

Figure 10-2 displays the Data Object Manager form, which is located in the Development Tools/Business Rule Definition folder. It is used to:

• Assign a rule generator adapter, entity adapter, or an event handler to an object, which can add, modify, or delete data to or from the database. This type of object is known as a data object.Schedule the adapter or event handler to be executed during a particular execution schedule (pre-insert, pre-update, pre-delete, post-insert, post-update, or post-delete).Organize the order in which Oracle Identity Manager will trigger adapters or event handlers that belong to the same execution schedule.See the user groups that can add, modify, and delete the current data object.Map the variables of an adapter to their proper source and target locations.

Note: For more information on adapter variables, rule generator adapters, and entity adapters, refer to the Oracle Identity Manager Tools Reference Guide.

Figure 10-2 Data Object Manager Form

Description of "Figure 10-2 Data Object Manager Form"

You will now learn about the data fields of the Data Object Manager form. Table 10-2 describes the data fields of this form.

Table 10-2 Data Field

Field	Description
Form Description	The name of the form, which is associated with the data object.
Data Object	The name of the data object, to which you are assigning event handlers rule generator adapters, or entity adapters.

Now that we have reviewed data objects and the data fields of the Data Object Manager form, you are ready to select the target data object to which a rule generator adapter, entity adapter, or event handler will be assigned.

Select a Target Data Object

To select a target data object, perform the following steps:

1. Open the Data Object Manager form.

2. Double-click the Form Description field. From the Lookup dialog box that appears, select the name of the form that is associated with the data object to which you want to assign an event handler, rule generator adapter, or entity adapter.

   Once you select a form, the name of the corresponding data object appears in the Data Object field.

3. Click Save. The target data object is selected. You can now assign rule generator adapters, entity adapters, and event handlers to it.

Tabs of the Data Object Manager Form

Once you launch the Data Object Manager form, and select a target data object, the tabs of this form become functional.The Data Object Manager form contains the following tabs:

• Attach HandlersMap Adapters

Each of these tabs is covered in greater detail in the following sections.

Note: The Map Adapters tab will become operational only after you assign a rule generator adapter or entity adapter to the data object.

Attach Handlers

This tab is used to select the rule generator adapters, entity adapters, or event handlers that will be assigned to or removed from a data object. This includes:

• Specifying when Oracle Identity Manager will trigger the assigned event handlers or adapters (on pre-insert, pre-update, pre-delete, post-insert, post-update, or post-delete).Setting the order that Oracle Identity Manager will trigger the adapters or event handlers that belong to the same execution schedule.

When an event handler, rule generator adapter, or entity adapter no longer needs to be triggered by Oracle Identity Manager, you must remove it from the data object.For this example, Oracle Identity Manager will trigger the adpCONVERTTOLOWERCASE, adpSOLARISHMDSTRINGGEN, adpSETSOLARISASSET, and adpSETPASSWORDFROMMAIN adapters on pre-insert. Based on the sequence numbers of these adapters, Oracle Identity Manager will trigger the adpCONVERTTOLOWERCASE adapter first, followed by the adpSOLARISHMDSTRINGGEN, adpSETSOLARISASSET, and adpSETPASSWORDFROMMAIN adapters, respectively.

Note: To see the user groups that can add, modify, and delete the current data object, click the Insert Permissions, Update Permissions, or Delete Permissions tabs, respectively.

The following procedures will demonstrate how to:

• Assign an event handler, rule generator adapter, or entity adapter to a data object.Organize the execution schedule of event handlers or adapters.Remove an event handler, rule generator adapter, or entity adapter from a data object.

Assign an Event Handler or Adapter to a Data Object

1. Select the tab of the Data Object Manager form that represents when you want the adapter or event handler to be triggered. For example, if you want Oracle Identity Manager to activate an adapter on pre-insert, select the Pre-Insert tab.

2. From the selected tab, click Assign. The Assignment dialog box is displayed.

3. Select the event handler or adapter, and assign it to the data object.

4. Click OK. The event handler or adapter is assigned to the data object.

Organize the Execution Schedule of Event Handlers or Adapters

1. Highlight the event handler or adapter whose execution schedule you wish to change.

2. Click Assign. The Assignment dialog box is displayed.

3. Highlight the event handler or adapter..

4. Click Up. The selected event handler or adapter will switch places (and sequence numbers) with the event handler or adapter that precedes it.

5. Or, Click Down. The highlighted event handler or adapter will trade places (and sequence numbers) with the event handler or adapter that that follows it.

6. Repeat Steps 3-5 until all event handlers and/or adapters have the appropriate sequence numbers.

7. Click OK. The event handlers or adapters will now be triggered in the proper order for the execution schedule(s) you organized.

Remove an Event Handler or Adapter From a Data Object

1. Highlight the desired event handler or adapter.

2. Click Delete. The event handler or adapter is removed.

Map Adapters

This tab is used to map the variables of a rule generator or entity adapter to their proper source and target locations. For this example, the adpSOLARISUSERIDGENERATOR adapter has three variables: firstname, Adapter return value, and lastname. Since a "Y" appears in the Mapped column for each adapter variable, this signifies that all three variables have been mapped to the correct locations, and the adapter's status will change to Ready.

Note: An adapter can have one of three statuses: Ready. This adapter has been successfully compiled and all of its variables have been mapped correctly. Mapping Incomplete. This adapter has been successfully compiled, but at least one of its variables has been not mapped correctly. Mapping Incomplete. This adapter has been successfully compiled, but at least one of its variables has been not mapped correctly.

For more information on compiling adapters and/or mapping its variables, refer to the Oracle Identity Manager Tools Reference Guide.

Note: If no adapters are assigned to a data object, the Map Adapters tab will be disabled.

The Reconciliation Rules Form

This form is located in the Development Tools folder. It is used to define the rules that are invoked:

• When Oracle Identity Manager is attempting to determine which user (or organization) record is associated with a change on a trusted source. These rules will be evaluated as soon as all required fields within the reconciliation event have been processed on the Reconciliation Data tab (of the Reconciliation Manager form).

• When Oracle Identity Manager is attempting to determine which user (or organization) record is the owner of an account discovered on a target resource (for example, as a result of a change detected on that system). These rules will be evaluated only when all required fields within the reconciliation event have been processed on the Reconciliation Data tab (of the Reconciliation Manager form) and no processes have been matched to the event on the Processes Matched Tree tab (of the same form).

As mentioned, rules defined using this form is used to match either users or organizations associated with a change on a trusted source or target resource. Rules of these types are referred to as user matching or organization matching rules, respectively. These rules are very similar to the ones you can define using the Rule Designer form except that the rules created using the Reconciliation Rules form are resource object-specific (since they relate to a single target resource) and only affect reconciliation-related functions.

Define a Reconciliation Rule

To define reconciliation rules for user or organization matching, perform the following steps:

1. Access the Reconciliation Rules form.

2. Enter a name for the rule in the Name field.

3. Select the target resource with which this rule is to be associated in the Object field

4. Enter a description for the rule in the Description field.

   Select the And or Or Operator for the rule. If And is selected, then all elements (and rules if they have been nested) of the rule must be satisfied for the rule to be evaluated to true. If Or is selected, then the rule will be evaluated to true if any element (or rule if one has been nested) of the rule is satisfied.

5. Click Save. The rule definition will be saved. Rule elements must now be created for the rule.

Note: You must ensure that the Active checkbox is selected. If this checkbox is not selected, the rule will not be evaluated by Oracle Identity Manager's reconciliation engine when processing reconciliation events related to the resource. However, this checkbox can only be set once Oracle Identity Manager has selected the Valid system checkbox. The Valid checkbox will only be selected once you have created at least one rule element and Oracle Identity Manager has determined that the logic of this rule element is valid.

Add a Rule Element

To define individual elements within a reconciliation rule, perform the following steps:

1. Access the Rule definition to which you wish to add elements.

2. Click Add Rule Element on the Rule Elements tab. The Add Rule Element dialog box is displayed.

3. Click the Rule Element tab.

4. Select a user-related data item from the User Data menu. This will be the user data element that Oracle Identity Manager will examine when evaluating the rule element. The menu will display all fields on the Oracle Users form (including any user-defined fields you may have created).

Note: If the rule being defined is for organization matching, then both the data available and the name of the menus will be related to organizations rather than users.

5. Select an Operator from the Operator menu. This will be the criteria that Oracle Identity Manager applies to the attribute for data item you selected when evaluating the rule element. Valid operators are:

• Equals. If you select this option, then the (user or organization record's) data element must exactly match the attribute you select.

• Contains. If you select this option, then the (user or organization record's) data element must only contain (not be an exact match with) the attribute you select.

• Start with. If you select this option, then the (user or organization record's) data element must begin with the attribute you select.

• End with. If you select this option, then the (user or organization record's) data element must end with the attribute you select.

Select a value from the Attribute menu. The values displayed in this menu are the fields that have been defined on the Reconciliation Fields tab for the resource associated with the rule. If the reconciliation fields have not yet been designated for the resource, then no values will be available.

Note: When defining a rule element for a target resource (as opposed to a trusted source), only those fields associated with parent tables of the resource's custom process form will be available for selection in the Attribute field.

6. If you want Oracle Identity Manager to perform a particular transformation on the data in the Attribute field (before applying the operator), select the desired transformation from the Transform menu.

Note: If you select a value (other than None) from this menu, once you click Save, you must also select the tab and set the appropriate properties so that Oracle Identity Manager is able to properly perform the transformation.

The possible transformations are described in Table 10-3.

Table 10-3 Transformation Properties

Transformation	Properties to be set on the Rule Element Properties tab
Substring	Start Point, End Point
Endstring	Start Point
Tokenize	Delimiters, Token Number, Space Delimiter

7. Set the Case-Sensitive check box. If this check box is selected, the value selected in the Attribute field must exactly match the capitalization used in the value being evaluated in the reconciliation event record in order for the rule element to be satisfied. If this check box is cleared, then the value selected in the Attribute field is not required to match the capitalization used in the value being evaluated in the reconciliation event record.

8. Click Save.

9. If you select a value (other than None) in the Transform menu and have not yet set the properties for the transformation, the Properties Set check box will be clear. You must then select the Rule Element Properties tab, set the appropriate properties and click Save again.

   The rule element will be added to the rule.

10. Repeat this entire procedure for each rule element you wish to add to the rule.

Note: Ensure that the Active checkbox is selected.

Nest a Rule Within a Rule

You can nest an existing rule within a rule. Oracle Identity Manager will evaluate the criteria of the nested rule in the same manner as any other element of the rule. To nest a rule within a rule, perform the following steps:

1. Access the rule to which you wish to add another rule.

2. Click Add Rule on the Rule Elements tab.

3. The Rule Choice lookup dialog box is displayed. Locate and select the desired rule.

Note: Only reconciliation-related rules that are associated with the same resource object will be available for selection within the dialog box.

4. Click OK. The selected reconciliation rule will be added to rule.

5. Repeat steps 2-4 for each rule you wish to nest within the rule.

Delete a Rule Element or Rule

To delete a rule element or a rule, perform the following steps:

1. Access the rule from which you wish to delete an element.

2. Select the rule element or rule to be deleted on the Rule Elements tab.

3. Click Delete.