5 Developing Rules

This chapter describes the Business Rule Definition of the Design Console. It contains the following topics:

• Overview of Business Rule Definition

• Event Handler Manager Form

• Data Object Manager Form

• Reconciliation Rules Form

5.1 Overview of Business Rule Definition

The Development Tools/Business Rule Definition folder provides system administrators and developers with tools to manage the event handlers and data objects of Oracle Identity Manager.

This folder contains the following forms:

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

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

5.2 Event Handler Manager Form

This form is displayed in the Development Tools/Business Rule Definition folder. You use this form 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 that Oracle Identity Manager can recognize it.

There are two types of event handlers:

• Event handlers that are created through the Adapter Factory form. These begin with the letters adp. They are known as adapters.

• Event handlers that are created internally in Oracle Identity Manager. These begin with the letters tc. They are referred to as system event handlers.

By using 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 as follows:

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

• Pre-Update: Before information is modified in 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 in the database

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

Figure 5-1 shows the Event Handler Manager form.

Figure 5-1 Event Handler Manager Form

Table 5-1 describes the fields of the Event Handler Manager form.

Table 5-1 Fields of the Event Handler Manager Form

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

The following sections describe how to create and modify event handlers.

Note:

To use an event handler, you must attach it to a data object by using the Data Object Manager form. For more information about assigning event handlers to data objects, see Section 5.3, "Data Object Manager Form".

Caution:

Any event handler that begins with the letters adp is associated with adapters, and should not be modified. However, you can modify system event handlers. These event handlers begin with the letters tc.

Adding or Modifying an Event Handler

To add or modify an event handler:

1. Open the Event Handler Manager form.

2. To add an event handler to Oracle Identity Manager, enter the name of the event handler into the Event Handler Name lookup field.

   To modify an event handler, double-click the Event Handler Name lookup field.

   From the Lookup dialog box that is displayed, select the event handler that you want to edit.

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

4. Select the check boxes that correspond to when you want Oracle Identity Manager to trigger the event handler.

   You can schedule an event handler to run on preinsert, preupdate, predelete, postinsert, postupdate, and postdelete.

   Note:

   Selecting a check box does not mean that the event handler is triggered at that time, for example, on preinsert. It signifies that the event handler can run at that time.

5. In the Notes area, add or edit explanatory information about the event handler.

6. Click Save.

   The event handler is added or modified.

5.3 Data Object Manager Form

The Data Object Manager form is displayed in the Development Tools/Business Rule Definition folder. You use this form to:

• Assign a rule generator adapter, entity adapter, or an event handler to an object that can add, modify, or delete data in the database. This type of object is known as a data object.

• Schedule the adapter or event handler to run according to a schedule (pre-insert, pre-update, pre-delete, post-insert, post-update, or post-delete).

• Organize the order in which Oracle Identity Manager triggers adapters or event handlers that belong to the same execution schedule.

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

  See Also:

  Chapter 2, "Developing Adapters" for more information about adapter variables, rule generator adapters, and entity adapters

Figure 5-2 shows the Data Object Manager form.

Figure 5-2 Data Object Manager Form

Table 5-2 describes the fields of the Data Object Manager form.

Table 5-2 Fields of the Data Object Manager Form

Fields	Description
Form Description	The name of the form that 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.

The following section describes how to select the target data object to which a rule generator adapter, entity adapter, or event handler will be assigned.

Selecting a Target Data Object

To select a target data object:

1. Open the Data Object Manager form.

2. Double-click the Form Description field.

   From the Lookup dialog box displayed, 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.

   After you select a form, the name of the corresponding data object is displayed 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.

5.3.1 Tabs of the Data Object Manager Form

After you start 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 described in the following sections:

• Attach Handlers Tab

• Map Adapters Tab

5.3.1.1 Attach Handlers Tab

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

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

When an event handler, rule generator adapter, or entity adapter must no longer be triggered by Oracle Identity Manager, you must remove it from the data object.

For example, Oracle Identity Manager can trigger the adpCONVERTTOLOWERCASE, adpSOLARISHMDSTRINGGEN, adpSETSOLARISASSET, and adpSETPASSWORDFROMMAIN adapters on pre-insert. Based on the sequence numbers of these adapters, Oracle Identity Manager triggers 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 sections discuss these procedures:

• Assigning an event handler, rule generator adapter, or entity adapter to a data objectOrganizing the execution schedule of event handlers or adaptersRemoving an event handler, rule generator adapter, or entity adapter from a data object

5.3.1.1.1 Assigning an Event Handler or Adapter to a Data Object

To assign an event handler or adapter:

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.

5.3.1.1.2 Organizing the Execution Schedule of Event Handlers or Adapters

To organize the execution schedule:

1. Select the event handler or adapter whose execution schedule you want to change.

2. Click Assign.

   The Assignment dialog box is displayed.

3. Select the event handler or adapter.

4. If you click Up, the selected event handler or adapter will switch places and sequence numbers with the event handler or adapter that precedes it.

   If you click Down, the selected event handler or adapter will switch places and sequence numbers with the event handler or adapter that follows it.

5. Repeat Steps 3 and 4 until all event handlers and adapters have the appropriate sequence numbers.

6. Click OK.

   The event handlers and adapters will now be triggered in the correct order for the execution schedule or schedules that you organized.

5.3.1.1.3 Removing an Event Handler or Adapter from a Data Object

To remove an event handler or adapter:

1. Select the desired event handler or adapter.

2. Click Delete.

   The event handler or adapter is removed.

5.3.1.2 Map Adapters Tab

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

You use this tab to map the variables of a rule generator or entity adapter to their proper source and target locations. For example, suppose the adpSOLARISUSERIDGENERATOR adapter has three variables: firstname, Adapter return value, and lastname. If a Y is displayed in the Mapped column for each adapter variable, this signifies that all three variables are mapped to the correct locations, and the adapter's status will change to Ready.

Note:

An adapter can have any one of the following three statuses:

• Ready: This adapter has successfully compiled, and all of its variables are mapped correctly.

• Mapping Incomplete: This adapter has successfully compiled, but at least one of its variables has been not mapped correctly.

• Mapping Incomplete: This adapter has successfully compiled, but at least one of its variables has not been mapped correctly.

For more information about compiling adapters and mapping its variables, see Chapter 2, "Developing Adapters".

Note:

If no adapters are assigned to a data object, the Map Adapters tab is grayed out.

5.4 Reconciliation Rules Form

This form is located in the Development Tools folder.

Figure 5-3 Reconciliation Rules Form

You use this form to define rules that are invoked at the following times:

• When Oracle Identity Manager tries to determine which user or organization record is associated with a change on a trusted source. These rules are evaluated as soon as all required fields in the reconciliation event are processed on the Reconciliation Data tab of the Reconciliation Manager form.

• When Oracle Identity Manager attempts 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 are evaluated only when all required fields in the reconciliation event are processed on the Reconciliation Data tab of the Reconciliation Manager form, and no processes were matched to the event on the Processes Matched Tree tab of the same form.

As mentioned, rules defined by using this form are 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 similar to the ones you can define by using the Rule Designer form except that the rules created by using the Reconciliation Rules form are specific to the resource object (because they relate to a single target resource) and only affect reconciliation-related functions.

Topics in working with reconciliation rules include:

• Defining a Reconciliation Rule

• Adding a Rule Element

• Nesting a Rule Within a Rule

• Deleting a Rule Element or Rule

5.4.1 Defining a Reconciliation Rule

The following procedure describes how to define a reconciliation rule.

Note:

In the following procedure, you must ensure that the Active check box is selected. If this check box 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, you can only select this check box after Oracle Identity Manager has selected the Valid system check box. The Valid check box can only be selected after you have created at least one rule element, and Oracle Identity Manager has determined that the logic of this rule element is valid.

To define reconciliation rules for user or organization matching:

1. Go to 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, all elements (and rules if they are nested) of the rule must be satisfied for the rule to be evaluated to true. If Or is selected, 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.

5.4.2 Adding a Rule Element

To define individual elements in a reconciliation rule:

1. Go to the Rule definition to which you want 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 examines when evaluating the rule element. The menu will display all fields on the Oracle Users form (including any user-defined fields you have created).

   Note:

   If the rule being defined is for organization matching, 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. The following are valid operators:

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

     Note:

     • If you configure trusted source reconciliation of users, you must ensure that the User ID field of the Oracle Identity Manager User account is used in the reconciliation matching rule.

     • If you configure trusted source reconciliation of organizations, you must ensure that the Organization Name field of the Oracle Identity Manager User account is used in the reconciliation matching rule.

   • Contains: If you select this option, 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, the user or organization record's data element must begin with the attribute you select.

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

6. Select a value from the Attribute menu. The values in this menu are the fields that were 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, no values will be available.

   Note:

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

7. 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, after you click Save, you must also select the tab and set the appropriate properties so that Oracle Identity Manager is able to perform the transformation correctly.

   The possible transformations are described in Table 5-3.

   Table 5-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

   
   

8. Select the Case-Sensitive check box.

   For the rule element to be met, if this check box is selected, the value selected in the Attribute field must match the capitalization of the value being evaluated in the reconciliation event record. If this check box is deselected, 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.

9. Click Save.

10. 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 not be selected.

    You must select the Rule Element Properties tab, set the appropriate properties, and click Save again.

    The rule element will be added to the rule.

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

    Note:

    Ensure that the Active check box is selected.

5.4.3 Nesting a Rule Within a Rule

You can nest an existing rule within a rule. Oracle Identity Manager evaluates the criteria of the nested rule in the same way as any other element of the rule.

Note:

Only reconciliation-related rules that are associated with the same resource object are available for selection in the dialog box.

To nest a rule within a rule:

1. Go to the rule to which you want 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.

4. Click OK.

   The selected reconciliation rule is added to rule.

5. Repeat steps 2 through 4 for each rule you want to nest in the rule.

5.4.4 Deleting a Rule Element or Rule

To delete a rule element or a rule:

1. Go to the rule from which you want to delete an element.

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

3. Click Delete.