14 Customizing Reconciliation

This chapter describes reconciliation features and architecture and the various aspects of customizing reconciliation operations in the following sections:

14.1 Reconciliation Features

Reconciliation features can be divided into the following categories:

14.1.1 Performance Enhancement Features

The following features help increase performance during reconciliation:

14.1.1.1 New Metadata Model - Profiles

If metadata is associated with a reconciliation target, then it limits the ability to run multiple jobs performing different types of reconciliation against the same target. Therefore, all configurations in various components of Oracle Identity Manager are stored centrally in an XML store called MDS.

For backward compatibility, current deployments continue managing their configurations through Oracle Identity Manager Design Console and the configuration continues to be stored in the Oracle Identity Manager database. The configuration APIs automatically read the configurations from the tables in Oracle Identity Manager and convert them into XML profiles, called default profiles, and associate those profiles with the existing reconciliation runs.

You manage all the metadata by using Oracle Identity Manager Design Console. Using Oracle Identity Manager Design Console, you can generate the default reconciliation profile. This can be used to regenerate the profile when reconciliation configurations are changed from Oracle Identity Manager Design Console. When configurations are imported from the Deployment Manager, the profile is generated by default.

All nondefault profiles can be completely managed by using any XML editor.

See Also:

"Reconciliation Profile" for information about reconciliation profiles

14.1.1.2 Parameters to Control Flow and Processing of Events

This section consists of the following topics:

Parameters to Control Event Processing

BatchSize is the parameter to control event processing. This dictates the size of the batch. A batch size of 1 is equivalent to processing of events one at a time. Batch size is available as a system property and can be managed from Oracle Identity Manager Design Console. The property name is OIM.ReconBatchSize. The default value of the system BatchSize parameter is 500. For information about system properties, see "Managing System Properties" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

System Property to Control AutoRetry

The Retry Count for recon event system property controls auto retry by indicating how many times an item needs to be retried before the reconciliation engine marks it as an error or sends it to manual queue. The value 0 for this property means that the auto retry option is not configured.

See Also:

"Handling of Race Conditions" for more information about auto retry

14.1.1.3 Grouping of Events by Reconciliation Runs

All the events created in the reconciliation database are grouped by reconciliation runs. All events in a reconciliation run are grouped with a common reconciliation run ID. Because each reconciliation run is associated with a profile, all events in a reconciliation run are processed by using the same profile. This helps in optimizing the performance because the configurations have to be retrieved only once per reconciliation run.

Each profile can use a different batch size. This enhances system performance for each target reconciliation by tuning the appropriate batch for it.

14.1.1.4 Grouping of Events by Batches

Batches are introduced to increase system performance during reconciliation. A batch consists of a number of events. It is a unit of processing in the reconciliation engine. The size of the batch is configurable. Reconciliation runs are broken into fixed size batches. For example, if a reconciliation run consists of 9900 events and batch size is 1000, then that reconciliation run is divided into 10 batches each with size 1000, and last batch with size 900.

Processing a batch as a unit optimizes system performance by eliminating the overhead of processing one event at a time. This also allows performing bulk operations wherever possible. Batches can also run in parallel to balance the use of hardware resources.

14.1.1.5 Implementing Reconciliation Engine Logic in the Database

In earlier releases, all engine logic was implemented in Java and the processing happened one event at a time. In 11g Release 2 (11.1.2.3.0), most of the logic to process the events is implemented as stored procedures. A combination for processing at batch level and the logic being implemented in PLSQL makes it possible to perform bulk operations at the SQL layer. The following steps are performed in bulk (one batch at a time):

  • Required data check

  • Applying matching rules

  • Applying action rules

14.1.1.6 Improved Java Engine

Processing that cannot be performed in stored procedures and must be performed in Java layer also provides better performance than earlier releases of the engine for the following reasons:

  • Java engine performs bulk operations by default:

    • Submits events in batches to the database

    • Submits bulk postprocess orchestration depending on the action

  • Performs bulk operations wherever possible.

14.1.1.7 Improved Database Schema

A notable performance enhancement from the new database schema in 11g Release 2 (11.1.2.3.0) is by using horizontal tables for storing event details for various targets instead of using a single vertical table for storing the event details from various targets. A horizontal table is used for each profile.

See Also:

"Staging Tables" for more information about horizontal tables

14.1.2 Web-Based Event Management Interface

Oracle Identity Manager provides a Web-based event management interface that allows you to manage the events from the Web. Authorized users are able to search for events, users, and handle exceptions by linking events with users and accounts. You can also close events, force failed events to be re-evaluated, and perform ad-hoc linking.

Ad-hoc linking refers to the ability provided to authorized users of the Event Management section to link an event to any user in Oracle Identity Manager. Although the reconciliation engine finds user matches for events, the user through this ad-hoc link feature can ignore those matches and select a different user. This allows you to handle exceptions resulting from error matches.

See Also:

"Managing Reconciliation" in Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about the tasks performed to manage reconciliation events

14.1.3 Other Features

Other reconciliation features are described in the following sections:

14.1.3.1 Staging Tables

In earlier releases of Oracle Identity Manager, the reconciliation schema has one table to store all the event details from various targets. The list of attributes and their names and types that the various reconciliation events contain can vary from target to target. This means that events from one target can contain a different set of data compared to events from another target. The only way to store data from such events in a single table is by storing one attribute per row. Therefore, in earlier releases, each row in the event detail table represents a single attribute of reconciliation event data. For each attribute, it stores the event to which it belongs, the attribute name, type, and value. This is also referred to as vertical table in this document. Although vertical tables are beneficial from the point of view of flexibility and extensibility, it is not an efficient way to store event records from the performance prospective.

Storage in vertical tables is replaced by separate tables for each target, called horizontal tables or staging tables. They are called horizontal tables because instead of storing attributes of an event vertically in the table as rows (as many rows as there are number of attributes), the attributes of an event are stored as columns. This means that there are as many columns as there are number of attributes for a target. Each event is stored as a row. Because different targets can have different sets of attributes, each target has a separate table in the reconciliation schema to store event details. There can be multiple tables per target because of requirements to handle multi-valued attributes that are stored as rows in child tables.

Each row of the event detail table for a specific profile stores the list of reconciliation fields for a single event. For example, for trusted user reconciliation in which firstname, lastname, email attributes are being reconciled, there is the RA_XELLERATE_USER staging table with the following columns:

RE_KEY, RECON_FIRSTNAME, RECON_LASTNAME, RECON_EMAI

Creating and Maintaining Staging Tables

Staging tables can be created only when a target is being deployed against Oracle Identity Manager. This is because, at the time of target deployment, the reconciliation system knows the list of attributes and their types for the target, which needs to be reconciled.

Staging tables are updated when configurations are imported from the Deployment Manager or changes are made by using Oracle Identity Manager Design Console. To generate a staging table from Oracle Identity Manager Design Console, in the Object Reconciliation form, click Generate Reconciliation Profile.

14.1.3.2 Handling of Race Conditions

In earlier releases of Oracle Identity Manager, when an event is being reconciled, the reconciliation engine may not be able to process it successfully because before this event can be reconciled, another event needs to be reconciled. For example, before the reconciliation engine can reconcile an event that is supposed to create an account, the engine needs to reconcile an event that is supposed to create a user. This is called a race condition.

In Oracle Identity Manager 11g Release 2 (11.1.2.3.0), the race conditions are handled by setting the value of the 'Retry Count for recon event' system property. To configure auto retry, specify a value greater than 0 for this property. If you do not want to configure auto retry, then specify 0 as the value of the Retry Count for recon event system property.

When auto retry is configured, the reconciliation engine checks for the race conditions. If a race condition is found, then the reconciliation engine puts the reconciliation event in a re-evaluate queue until the retry count is exhausted.

A Reconciliation Retry Scheduled Task periodically checks if there is any event waiting for retry and is ready to be re-evaluated and if yes, it queues them up for reconciliation engine processing. This scheduled task is configured by default.

Note:

If the auto retry count is exhausted, the reconciliation engine does not further process the event and sets the status per the matching rules. However, you can manually retry by requesting for re-evaluate from Event Management. For information about re-evaluating events, see "Re-evaluating Events" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

Auto retry can handle the following race conditions:

  • An account event for creating an account in Oracle Identity Manager is processed before the user is created for this event because the event for creating user is not processed yet.

  • A user event for creating a Xellerate user in Oracle Identity Manager is processed before the organization is created to which this user belongs.

All auto retry parameters are stored as part of the reconciliation profiles. This means that while the events belonging to one reconciliation run may have auto retry configured, the events belonging to another reconciliation run may not have auto retry configured.

In Oracle Identity Manager, there is no UI to manage these parameters within a profile and you must use an XML editor to manage them by directly editing the XML profile. For information about editing an XML profile, see "Creating and Updating Reconciliation Profiles".

14.1.3.3 Ad Hoc Linking

If the reconciliation engine is not able to determine the owner based on the matching rules, then you can manually link an account to a user by using Oracle Identity Manager Advanced Administration. Subsequent modifications to the account is automatically linked to that account.

Ad hoc linking is supported for user and account events. If the reconciliation engine is not able to determine the owner based on the matching rules, then you can manually link a user or account event to a user.

See Also:

"Ad Hoc Linking" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about how to perform ad hoc linking

14.2 Reconciliation Architecture

Reconciliation is the process of pulling entity data from the target system into Oracle Identity Manager to keep the entity data in a consistent state between the two systems. The various components of Oracle Identity Manager involved in reconciliation and the interaction between these components are shown in the Figure 14-1:

Figure 14-1 Reconciliation Architecture

Description of Figure 14-1 follows
Description of ''Figure 14-1 Reconciliation Architecture''

The reconciliation architecture is described in the following steps:

  1. Each connector has scheduled tasks associated with it. The scheduler triggers the connector scheduled task, which invokes reconciliation APIs to generate events. The event can be of type Regular, Changelog, or Delete.

    For more information about the scheduler, see "Managing the Scheduler" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager. For more information about scheduled tasks, see "Connector for Reconciliation".

  2. The reconciliation events are stored in the reconciliation event repository, which is Oracle Identity Manager database.

  3. When batch size is met, an asynchronous message is submitted which processes the batch of events in bulk. At the end of the schedule task another asynchronous message is submitted for processing the events of the last batch.

    Note:

    • In Figure 14-1, the reconciliation engine encapsulates the Action JAVA Layer as well as parts of the Reconciliation Event Repository, and orchestrates all the arrows in that diagram.

    • In this release, trusted source reconciliation is supported for users only. It is not supported for roles, role membership, and role hierarchy reconciliation.

    • In this release, Oracle Identity Manager supports trusted source reconciliation and account reconciliation for organizations.

  4. The processing involves data validation, matching of the entities and action (create, update, delete and so on). This is followed by post processing via kernel orchestrations. For information about the action module, see "Action Module". For information about the reconciliation profile, see "New Metadata Model - Profiles".

  5. By default the reconciliation event processing happens in bulk, and therefore all the steps till post processing are performed by PL/SQL stored procedures. Event can be processed one at a time in the following scenarios (in this case all the steps till matching are done in PL/SQL and the action is performed in java layer):

    • When events are processed from the Event Management UI

    • When failed events are retried by the retry scheduled task that runs periodically

    For reconciliation single event processing, actions and post processing take place through the kernel.

  6. Reconciliation events are made available to the Event Management UI by another API call in the reconciliation management service.

The functionality of various components of the reconciliation service are explained in the following sections:

14.2.1 Reconciliation Profile

A reconciliation profile is the configuration defined to govern how reconciliation is run for a particular resource. A particular resource can have multiple reconciliation profiles, each of which defines matching rules, action rules, and field mappings, which can differ in each profile corresponding to the resource. For example, while one reconciliation run can perform reconciliation of new and modified accounts, another reconciliation run can reconcile deletion of accounts because you might want to run the deletions only once a day. In this example, you define two reconciliation runs and two profiles. Each profile is associated with respective reconciliation run and each profile having its own rules of reconciliation.

The profile is an XML-based configuration file stored in Oracle Identity Manager MetaData Store (MDS). Example 14-1 shows a sample reconciliation profile:

Example 14-1 Sample Reconciliation Profile

<?xml version='1.0' encoding='UTF-8'?>
<profile xmlns="http://www.oracle.com/oracle/iam/reconciliation/config/" ownerType="User" changeType="CHANGELOG" auditEnabled="true" batchSize="500" resourceType="Account" name="Modified AD User" configure="true" active="true">
   <matchingRule>((UPPER(USR.usr_udf_obguid)=UPPER(RA_ADUSERE469E5C8.RA_OBJECTGUID)))</matchingRule>
   <form oimTableName="UD_ADUSER" stagingTableName="RA_ADUSERE469E5C8" name="Modified AD User" mlsOimTable="mlsOIMTableIfAny" mlsStagingTable="mlsStagingTableIfmlsOIMTable">
      <matchingRule>(UD_ADUSER.UD_ADUSER_OBJECTGUID=RA_ADUSERE469E5C8.RA_OBJECTGUID)</matchingRule>
      <targetAttributes>
         <targetAttribute type="String" name="Status">
            <stagingField type="String" length="256" name="RA_STATUS"/>
         </targetAttribute>
         <targetAttribute type="String" name="copyStatus" ref="Status" mls="true">
            <stagingField type="String" length="256" name="COPY_STATUS"/>
            <oimAttribute type="String" fieldName="OIM_OBJECT_STATUS" fieldType="String" name="OIM_OBJECT_STATUS"/>
         </targetAttribute>
         <targetAttribute type="String" name="password" encrypted="true" keyField="false" required="false">
            <stagingField type="String" length="256" name="PASSWORD"/>
            <oimAttribute type="String" fieldName="UD_ADUSER_PASSWORD" fieldType="String" name="AD Password"/>
         </targetAttribute>         
         <targetAttribute type="Date" name="accountExpires">
            <stagingField type="Date" name="RA_ACCOUNTEXPIRES"/>
            <oimAttribute type="Date" fieldName="UD_ADUSER_DATE" fieldType="Date" name="Account Expiration Date"/>
         </targetAttribute>         
         <targetAttribute type="ITResource" name="IT Resource" keyField="false">
            <stagingField type="ITResource" length="19" name="RA_ITRESOURCE15641F83"/>
            <oimAttribute type="Number" fieldName="UD_ADUSER_AD" fieldType="Number" name="AD Server"/>
         </targetAttribute>
         <targetAttribute type="String" keyField="true" name="objectGUID">
            <stagingField type="String" length="32" name="RA_OBJECTGUID"/>
            <oimAttribute type="String" fieldName="UD_ADUSER_OBJECTGUID" fieldType="String" name="Object GUID"/>
         </targetAttribute>
      </targetAttributes>
      <form oimTableName="UD_ADUSRC" stagingTableName="RA_ADUSERGROUPDETA902DB909" name="memberOf">
         <matchingRule>(UD_ADUSRC.UD_ADUSRC_GROUPNAME=RA_ADUSERGROUPDETA902DB909.RA_MEMBEROF)</matchingRule>
         <targetAttributes>
            <targetAttribute type="String" keyField="true" name="memberOf">
               <stagingField type="String" length="256" name="RA_MEMBEROF"/>
               <oimAttribute type="String" fieldName="UD_ADUSRC_GROUPNAME" fieldType="String" name="UD_ADUSRC_GROUPNAME"/>
            </targetAttribute>
         </targetAttributes>
      </form>
   </form>
   <actionRules>
      <actionRule condition="One Entity Match Found" action="Establish Link"/>
   </actionRules>
</profile>

Table 14-1 describes the elements and the structure of the reconciliation profile XML file.

Table 14-1 Elements in the Reconciliation Profile XML

Element Level 1 Sub-element Level 2 Sub-element Level 3 Sub-element Level 4 Sub-element Level 5 Description

<profile>

       

The root element or object of the reconciliation configuration profile.

 

<ownerType>

     

Populated only for role hierarchy, role membership, and account with values Role, Role, and User respectively.

 

<changeType>

     

By default, or if the element is not present, then the value is CHANGELOG. Otherwise, the value can be REGULAR, CHANGELOG, or DELETE.

 

<auditEnabled>

     

Used with account type profile only. By default or if the element does not exist, then value is false, and audit for the resource object is stopped.

 

<batchSize>

     

Changes the size or number of reconciliation events per batch. By default, or if the element is not present, then batch size is 500.

 

<resourceType>

     

Value can be any one of Account, User, Role, RoleRole, RoleUser, and Organization.

 

<name>

     

This is the resource object name.

 

<configure>

     

By default or if the element is not present, then the value is false. If reconciliation configuration is to be created or updated on a system, then this must be marked as true. After all manual corrections of a profile, this attribute must be marked as true. For test to production, mark this element as true before importing into target system.

 

<active>

     

By default or if the element is not present, then the value is true. Value is false for corrupt or invalid profiles and marks profile unusable. Such profiles are never loaded into the system. After all manual corrections of a profile, this attribute must be removed or marked as true.

 

<matchingRule>

     

Populated only for role hierarchy, role membership, and account with owner matching rule. Otherwise, the element is not present.

 

<form>

     

This specifies one parent form per profile.

   

<oimTableName>

   

Oracle Identity Manager table into which data will be reconciled.

   

<stagingTableName>

   

Staging table into which data from the target system is stored before processing.

   

<name>

   

Same as profile name for the parent form and same as multivalued attribute name for the child forms.

   

<mlsOimTable>

   

Multilanguage supported (MLS) Oracle Identity Manager table into which data will be reconciled if resource object is MLA-enabled.

   

<mlsStagingTable>

   

MLS staging table into which data from target system is stored before processing if resource object is MLS-enabled.

   

<matchingRule>

   

Matching rule for the form (resource object associated with the profile), and is always required.

   

<targetAttributes>

   

Groups all target attributes.

     

<targetAttribute>

 

One for each attribute from the target system.

       

<type>

Data type of the target attribute.

       

<keyfield>

By default, the value is false. Used in matching rule for account resource type.

       

<name>

Name of the attribute from the target system provided by the connector that starts reconciliation.

       

<required>

If the attribute is required, then this element must be present.

       

<encrypted>

If the value is true, then the attribute value will be encrypted and stored in staging and Oracle Identity Manager tables.

       

<ref>

Name of the target attribute in the same form whose value will be copied and stored in this attribute.

       

<stagingField>

Specifies the column of the staging table corresponding to the target attribute. This contains the following elements:

<type>: data type of the staging table column.

<length>: length/size of the staging table column/field.

<name>: name of the staging table column.

       

<oimAttribute>

Specifies the mapped Oracle Identity Manager domain attribute name. The element is present only if the target attribute is mapped. This contains the following elements:

<name>: Oracle Identity Manager attribute name

<type>: Oracle Identity Manager attribute type

<fieldName>: Column name of the Oracle Identity Manager table corresponding to the Oracle Identity Manager mapped attribute

<fieldType>: Column type of the Oracle Identity Manager table corresponding to the Oracle Identity Manager mapped attribute

   

<form>

   

Specifies child form or forms for the parent or root form. It corresponds to a multivalued attribute.

     

<matchingRule>

 

Matching rule for a child form.

     

<targetAttributes>

 

This is the same element as the parent <targetAttributes> element. This element can be nested several times, for example, <form><targetAttributes><form><targetAttributes>.

 

<actionRules>

     

Groups all action rules for the resource object.

   

<actionRule>

   

An actionRule element for each action rule.

     

<condition>

 

The value can be any one of No Matches Found, One Entity Match Found, Multiple Entity Matches Found, One Process Match Found, Multiple Process Matches Found.

     

<action>

 

Can be anything based on the profile XSD.


There is always a default profile associated with reconciliation configurations for any resource object. The default profile can be explicitly generated from Oracle Identity Manager Design Console in the developer's environment or implicitly generated during import from the Deployment Manager. For details on how to create and update profiles, see "Updating Reconciliation Profiles Manually".

14.2.2 Reconciliation Metadata

The reconciliation metadata consists of various configurations used in creating and processing the reconciliation events. The reconciliation metadata is stored in a logical container called a profile. For information about reconciliation profile, see "Reconciliation Profile".

Examples of the reconciliation metadata are:

  • Mapping rules: Used to map the data received from the target system to the data managed about that target system in Oracle Identity Manager.

  • Matching rules: Used during the processing of each reconciliation event to correlate the event data to a particular account, user, or role in Oracle Identity Manager.

  • Action Rules: Used to specify the actions taken by Oracle Identity Manager based on the result of the processing of a reconciliation event.

  • List of target attributes: Used to define the data attributes received from the target system via reconciliation. It is used in the mapping rules, and is configured by using Oracle Identity Manager Design Console.

The various configurations used in creating and processing the reconciliation events are managed by using Oracle Identity Manager Design Console, and for backward compatibility, is stored in the same Oracle Identity Manager tables as in Oracle Identity Manager release 9.1.0. In addition, the configurations are also stored in the reconciliation profile.

Note:

For reconciliation in Oracle Identity Manager, a metadata model is being used. See "Managing Reconciliation Events" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

14.2.3 Reconciliation Target

Reconciliation target refers to an instance of an application that acts as a source of changes for Oracle Identity Manager. An example of reconciliation target is an HR system, which acts as a source of identities for Oracle Identity Manager. A reconciliation target can be a source of users or accounts.

14.2.4 Reconciliation Run

Reconciliation run refers to the combination of a reconciliation connector and associated configurations which when run by the scheduled task, performs the reconciliation based on the rules defined in the associated configurations. The scheduler runs reconciliation periodically at fixed intervals. Reconciliation runs are scheduled within Oracle Identity Manager scheduler to run at a specified frequency. All events created during a reconciliation run are grouped together by a unique reconciliation run ID.

14.2.5 Reconciliation APIs

These are a set of published APIs to provide reconciliation data to Oracle Identity Manager in the form of reconciliation events. Connectors can use the APIs to push data to the reconciliation event repository. Scheduled tasks can be setup to run the APIs when reconciliation is to be run on a scheduled basis. The existing connectors do not need to be changed because the existing APIs are supported.

14.2.6 Reconciliation Schema

The data that comes from the target system for reconciliation is stored in the reconciliation schema. The data contains the changes to be reconciled with Oracle Identity Manager.

Reconciliation schema refers to the set of schema tables to store the reconciliation data. The reconciliation schema is redesigned for performance reasons and future extensibility. See "Improved Database Schema" for more information about the reconciliation schema.

14.2.7 Reconciliation Engine

The reconciliation engine uses all configurable components and includes the data processor and rule evaluator that use these components to convert input data into a list of action items. It also includes the components that determine whether or not the actions can be automated based on the rule context. When an action is performed, either automatically or manually, the engine performs the appropriate updates and provisioning actions.

The main task of the reconciliation engine is to perform the comparison, determine the action to be taken, and apply the action in Oracle Identity Manager. It contains two modules, which are described in the following sections:

14.2.7.1 Matching Module

The matching rule specified in the profile is used to identify whether the record being searched, exists in Oracle Identity Manager or not. Matching rules are rules to identify whether the data is for an identity that Oracle Identity Manager already has a record of, or to identify the owner of the account in Oracle Identity Manager.

For account entities, when no record is found, an owner match is then performed to identify the owner of the account.

For role hierarchy events, matching is performed to identify the parent and child role.

Note:

While performing role hierarchy and role membership reconciliation, the matching criteria must contain both Namespace and Role Name in the matching criteria. The following is an example of a matching rule:

((UGP.ugp_rolename=x) and (UGP.ugp_namespace=y))

Here, x is the name of the staging table name column that is mapped to Role Name, and y is the name of the staging column that is mapped to Namespace.

At the end of the evaluation, the match table contains all the possible matches found within Oracle Identity Manager that meet the criteria for the event, and the state of the event is updated to one of the statuses listed in Table 14-2:

Table 14-2 Reconciliation Status Events

Status Events Description

Data Received

Event data has been created in the database and is ready for further processing.

Event Received

A reconciliation event has been created and is ready for further processing. The finishReconciliationEvent API has not yet been called.

Data Validation Failed

The reconciliation event record is invalid. For example, a role event with an invalid role category will fail to validate. This situation could indicate a race condition.

Data Validation Succeeded

The event data was successfully validated and the event can now safely be processed by the Engine.

Multiple Accounts Match Found

Given the current matching rules, multiple matching account records were found for the data.

No Account Match Found

Given the current matching rules, no matching account records were found for the data.

Single Account Match Found

Given the current matching rules, one matching account record was found for the data.

Multiple Org Matches Found

Given the current matching rules, multiple matching organization records were found for the data.

No Org Match Found

Given the current matching rules, no matching organization records were found for the data.

Single Org Match Found

Given the current matching rules, one matching organization record was found for the data.

Multiple Role Grants Match Found

Multiple matching records for user membership within a role were found.

No Role Grant Match Found

No matching records for user membership within a role were found.

Single Role Grant Match Found

One matching record for user membership within a role was found.

Multiple Roles Match Found

Given the current matching rules, multiple matching role records were found for the data.

No Role Match Found

Given the current matching rules, no matching role records were found for the data.

Single Role Match Found

Given the current matching rules, one matching role record was found for the data.

No Role Members Found

The Reconciliation Engine did not find role members matching the data, given the current matching rules.

No Role Parent Found

The Reconciliation Engine did not find a role matching the data, given the current matching rules.

Multiple Role Relationships Match Found

Given the current matching rules, reconciliation has found multiple role-to-role relationships that match data in the event.

No Role Relationship Match Found

Given the current matching rules, reconciliation did not find any role-to-role relationships that match data in the event.

Single Role Relationship Match Found

Given the current matching rules, reconciliation has found one role-to-role relationship that matches data in the event.

Multiple Users Match Found

Given the current matching rules, multiple matching user records were found for the data.

No User Match Found

Given the current matching rules, no matching user records were found for the data.

Single User Match Found

Given the current matching rules, one matching user record was found for the data.

Invalid Event Data Passed

The event contains invalid data.

Being Re-evaluated

The reconciliation event is being re-evaluated from the reconciliation event management UI.

Being Re-tried

The reconciliation event is being retried automatically. This status event has been deprecated.

Creation Failed

The user/account/role entity was not created successfully.

Creation Succeeded

The user/account/role entity was created successfully.

Delete Failed

The user/account/role entity was not successfully deleted.

Delete Succeeded

The user/account/role entity was deleted successfully.

Event Closed

The reconciliation event was closed from the reconciliation event management UI. The change is complete.

Update Failed

The user/account/role entity was not updated successfully.

Update Succeeded

The user/account/role entity was updated successfully.


14.2.7.2 Action Module

This module applies the action based on the event state, entity type, and the action rules, as listed in Table 14-3:

Table 14-3 Action Rules

Event State Entity Type Action Description

No User Match Found

User

None

Does not perform any action

   

Create User

Creates a user in Oracle Identity Manager

No Account Match Found

Account

None

Does not perform any action

User Matched

User or Account

None

Does not perform any action

 

User

Establish Link

Modifies or deletes the matched user based on the change type

 

Account

Establish Link

Owner identified - creates an account

Users Matched

User or Account

None

Does not perform any action

Account Matched

Account

None

Does not perform an action

   

Establish Link

Modifies or revokes the account based on the change type

Accounts Matched

 

None

Does not perform any action

No Role Match Found

Role

None

Does not perform any action

Single Role Match Found

Role

None

Does not perform an action

   

Establish Link

Modify or delete a role

 

Role Membership

Create role membership

Grant a role member to Oracle Identity Manager

   

Delete role membership

Delete a role member from Oracle Identity Manager

   

None

Does not perform an action

 

Role Hierarchy

Create role hierarchy

Creates a role hierarchy in Oracle Identity Manager

   

Delete role hierarchy

Delete a role hierarchy in Oracle Identity Manager

   

None

Does not perform an action

Multiple Roles Matched

Role, Role membership and Role Hierarchy

None

Does not perform an action

No Role Grant Match Found

Role Membership

None

Does not perform an action

   

Create Role Member

Creates a role member in Oracle Identity Manager

Single Role Grant Match Found

Role Membership

None

Does not perform an action

   

Establish Link

Delete role member

Multiple Role Grant Match Found

Role Membership

None

Does not perform an action

Note: This state does not occur because the role grant match is done by looking for the primary key, which is a combination of the usr key and the group key.

No Role Parent Match Found

Role Hierarchy

None

Does not perform an action

   

Create role parent

Create a role parent in Oracle Identity Manager

Single Role Parent Match Found

Role Hierarchy

None

Does not perform an action

   

Establish Link

Delete role parent

Multiple Role Parent Match Found

Role Hierarchy

None

Does not perform an action

Data Validation Failed

Role, Role Hierarchy, Role Member

Race condition

Does not perform an action. The event needs to be re-evaluated.

Parent role not found

Role Hierarchy

Race condition

Does not perform an action. The event needs to be re-evaluated.

Role member not found

Role membership

Race condition

Does not perform an action. The event needs to be re-evaluated.


14.2.8 Connector for Reconciliation

The connector refers to the software that extracts the changes from the target system and creates events in the reconciliation schema by calling the reconciliation APIs. If the connector that you want to use is shipped with a predefined reconciliation module, then a scheduled task definition is available. You use this component to control the frequency at which the target system is polled for changes to track data and other connector-specific parameters.

The connector for reconciliation is deployed by using the Deployment Manager. When the connector is deployed, the corresponding reconciliation profile for that connector is created in the metadata store (MDS), and horizontal tables that store the event data are also created.

Note:

Do not manually update reconciliation profile or update any reconciliation configurations from the Deployment Manager or Oracle Identity Manager Design Console when a reconciliation run is still in progress. This is because, if a reconciliation field is deleted or updated when a reconciliation run is in progress, then the event data might not be valid any more.

For information about configuring connectors, see Oracle Identity Manager Connector documentation.

See Also:

14.2.9 Archival

The Reconciliation Archival utility allows you to move processed events from the active reconciliation tables to archive tables. The events to move can be selected based on a time range. Only linked and closed events, which means successfully processed or closed by an administrator, can be archived.

See Also:

"Using the Reconciliation Archival Utility" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about how to use the Reconciliation Archival utility

14.2.10 Backward Compatibility

You do not need to change the existing reconciliation configurations or scheduled tasks to leverage the new reconciliation service.

The existing configurations for reconciliation setup in earlier Oracle Identity Manager releases continues to function after upgrading to 11g Release 2 (11.1.2.3.0). As part of the upgrade, corresponding reconciliation event tables are created for each of the existing object types being reconciled.

14.2.11 Reconciliation Event Management

The reconciliation events are managed by using the Event Management section of Oracle Identity System Administration. The Event Management section lets you view and manage reconciliation events generated by Oracle Identity Manager reconciliation engine. These events are generated through scheduled reconciliation runs. The Event Management section provides search capabilities on reconciliation runs as well as events. Users can use the Event Management section to perform reconciliation manually on generated events.

See Also:

"Managing Reconciliation Events" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for more information about the managing reconciliation events in the Oracle Identity System Administration

Figure 14-2 shows the various stages in the lifecycle of a reconciliation event.

Figure 14-2 Reconciliation Event Lifecycle

Description of Figure 14-2 follows
Description of ''Figure 14-2 Reconciliation Event Lifecycle''

14.3 Defining Reconciliation Rules

You can define reconciliation rules that are invoked at the following instances:

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

The Reconciliation Rules form in the Design Console is used to create and manage reconciliation rules in Oracle Identity Manager. This form is located in the Development Tools folder. Figure 14-3 shows the Reconciliation Rules form.

Figure 14-3 Reconciliation Rules Form

Description of Figure 14-3 follows
Description of ''Figure 14-3 Reconciliation Rules 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:

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

14.3.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 14-4.

    Table 14-4 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.

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

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

14.4 Developing Reconciliation Scheduled Tasks

Oracle Identity Manager provides connectors for reconciliation of users/accounts from various target systems, such as Microsoft Active Directory, Sun Java System Directory, Oracle Internet Directory, and Oracle E-Business Suite. For information about these connectors, see Oracle Identity Manager Connectors Documentation in the Oracle Technology Network (OTN) Web site at the following URL:

http://www.oracle.com/technetwork/indexes/documentation/index.html

However, to create a custom connector, you must develop a new scheduled task that performs the following:

  1. Retrieve user/account information from the target system.

  2. Use reconciliation APIs to create reconciliation events to submit event data.

  3. Create events for creating, modifying, or deleting an entity.

See Also:

Chapter 16, "Developing Scheduled Tasks" for information about developing a scheduled task

To connect to a specific target system, you must:

  • Create a new IT resource type

  • Define a new IT resource

  • Use the IT resource as an input parameter for the scheduled task

See Also:

Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for information about the APIs to lookup IT resource definition

In Oracle Identity Manager, a provisioning process and a process instance is associated with activities related to users or accounts. This provides a hook or point to add customizations upon various actions.

Changes to the user state or the account state can occur via direct APIs or reconciliation. The changes can be of many types, such as:

See Also:

"Understanding Reconciliation APIs" for information about the reconciliation APIs
  • Data change in the user or account profile

  • Status change, such as enable or disable

  • Organization change

  • Attribute propagation

  • Password propagation

For each of these changes, the process definition provides a facility to add hooks to be run upon any of these changes. For reconciliation, the process definition provides the hooks in the form of the following conditional tasks:

  • Reconciliation Insert Received: This conditional task is inserted when an account is created via reconciliation.

  • Reconciliation Update Received: This conditional task is inserted when an existing account linked to a user is updated via reconciliation. Data in the process form or status of the account are updated.

  • Reconciliation Delete Received: This conditional task is inserted when an existing account is revoked via reconciliation.

These tasks provide starting points for the workflows. You can create custom workflows in the provisioning process, and create a dependency between the reconciliation trigger tasks and the workflows. This causes the workflows to be run upon the respective triggers.

Every reconciliation event that is successfully linked to a user or an account inserts a single trigger from the conditional tasks. All the data in the user profile and the account profile is available as context-sensitive data for any adapter that is attached to one of these dependant tasks.

See Also:

Part II, "Connectors" and Part III, "Workflows" for details about creating conditional tasks, adapters, and dependencies

14.5 Updating Reconciliation Profiles Manually

This section describes updating reconciliation profiles manually in the following sections:

14.5.1 Creating and Updating Reconciliation Profiles

For reconciliation based on resource objects, the profile name is the same as that of the resource object. For example, if resource object name is testresource, then the default profile name is also testresource. The corresponding reconciliation staging table name is available in the profile. If the resource has Multi-Language Support (MLS) data, then the MLS staging and Oracle Identity Manager table names are also available in the profile. See Table 14-1, "Elements in the Reconciliation Profile XML" for information about the structure and the elements in the reconciliation profile.

If the resource object has child forms, then for each child form, the Oracle Identity Manager table name and staging table name are available in the profile. Each staging table has a corresponding entity definition XML file, the name is same as staging table name with dot xml extension (.xml), which is stored in the MDS.

To change a anything in a reconciliation profile, for instance attribute batch size, either the profile can be updated manually or by using the Design Console. To update a reconciliation profile:

Note:

If a reconciliation profile is changed by using the Design Console, the reconciliation profile must be regenerated by clicking the Create Reconciliation Profile button in the Object Reconciliation tab of the Design Console.
  1. Export the /db/PROFILE_NAME profile document from MDS.

  2. Make changes in the XML file, for example, change the batch size value.

  3. Set the value of the configure attribute to true. For information about this attribute, Table 14-1, "Elements in the Reconciliation Profile XML".

  4. Import the updated profile into MDS. See "Migrating User Modifiable Metadata Files" for information about exporting and importing metadata to and from MDS.

    This automatically updates the staging tables and the corresponding staging table entity definitions.

14.5.2 Changing the Profile Mode

You can use one of the following methods to change the profile mode property from CHANGELOG to REGULAR:

See Also:

"Mode of Reconciliation" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about changelog and regular reconciliation modes
  • Change the value of the changeType attribute in the profile, for example:

    <profile xmlns="http://www.oracle.com/oracle/iam/reconciliation/config/" changeType="REGULAR" batchSize="500" resourceType="Organization" name="Xellerate Organization">
    
  • Change the attribute during event creation:

    The event creation API, introduced in Oracle Identity Manager 11g Release 2 (11.1.2.3.0), contains three parameters. The first two parameters are same as those used in previous create event APIs. The third parameter can have attributes such as dateFormat, changeType, eventFinished, and actionDate. The following is the constructor for the third parameter:

    EventAttributes(boolean eventFinished, java.lang.String dateFormat, ChangeType changeType, java.util.Date actionDate)
    

    See Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for more information about the third parameter.

    You can use this API to set the changeType as follows:

    public long createReconciliationEvent(String objName, Map<String, Object>inputData, EventAttributes eventAttribs);
    

    Note:

    Using the API to set the changeType attribute overrides the value of the changeType attribute set in the profile.

14.6 Understanding Reconciliation APIs

The reconciliation APIs are a set of published APIs that can be used to create reconciliation events with single-valued and multi-valued attribute data and other features.

Reconciliation connector developers must use these APIs to push data to the reconciliation event repository.

See Also:

Chapter 20, "Using APIs" for more information about using APIs in Oracle Identity Manager

Most of these APIs existed in earlier versions of Oracle Identity Manager. However, in 11g Release 2 (11.1.2.3.0), the implementation has changed and is based on the new reconciliation architecture introduced in the release.

Existing standard connectors also use these APIs; since the earlier APIs continue to be supported, no changes are necessary to those connectors.

callingEndOfJobAPI is the only new reconciliation API in 11g Release 2 (11.1.2.3.0).

Each run of a connector is known as a job. In 11g Release 2 (11.1.2.3.0), reconciliation events are submitted to the reconciliation engine in batches. At the end of a job, the scheduler (which executes the connector scheduled task) executes a listener, which in turn invokes the callingEndOfJobAPI. This API submits any open batch for processing to the reconciliation engine.

The API calls are similar for Multilanguage Supported (MLS) and non-MLS data. The connector passes in data to be reconciled as a HashMap. The difference is that if an attribute is MLS-enabled, then the key is the attribute name, while the value is another HashMap of MLS data. The keys of this MLS-specific HashMap are language codes, and the values are the corresponding locale-specific data obtained from target system. If there is any MLS data that does not have a locale defined with it in the target system, that data is passed with key "base" in the MLS input data HashMap.

14.6.1 The ReconOperationsService API

The APIs in oracle.iam.reconciliation.api.ReconOperationsService are required for the following tasks:

  • Ignore Event

  • Create Event (single/bulk)

  • Process Event

  • Deletion Detection

See Also:

Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for details about the APIs in oracle.iam.reconciliation.api.ReconOperationsService

The preferred API and the order of invocation of these APIs is as follows:

  1. Ignore Event: This is a way to prevent event creation and processing of target system data that already exists in Oracle Identity Manager. The API invocation is as follows:

    boolean ignoreEvent(String resourceObjectName, Map inputData, String dateFormat) throws tcObjectNotFoundException, tcAPIException
    

    This API is used to validate whether or not the reconciliation create event needs to be raised for the specified object. If this API returns true, then you can skip the event creation, which saves extra event creation in the database.

    Similar to the ignoreEvent API, the ignoreEventAttributeData method can be used to validate whether or not the reconciliation create event flow needs to be raised for single and multivalued data coming from the target system. In this release, only the account entity type has such data. The API is as shown:

    boolean ignoreEventAttributeData(String resourceObjectName, Map inputData, String multiValueFieldName, Map[] childDataList, String dateFormat) throws tcAPIException, tcObjectNotFoundException
    

    Note:

    Either ignoreEvent or ignoreEventAttributeData must be invoked; both the APIs are not required to be invoked.
  2. Create Event: This can happen via single event creation or bulk event creation APIs. This flow simply stores target system data in staging tables. The processing of this data asynchronously takes place later on.

    Create Event (Single): This consists of the following APIs:

    • Use the createReconciliationEvent method to provide the data for creating reconciliation events. If there is child or multivalued data, then set the value of the eventAttribs.eventFinished flag to false. Otherwise, set this value to true. It returns the eventId of the created Event.

      long createReconciliationEvent(String resourceObjectName, Map<String, Object> inputData, EventAttributes eventAttribs)
      
    • The child data is provided using the addMultiAttributeData method. If there is no child data or the eventAttribs.eventFinished flag is set to true, then this API must not be invoked.

      long addMultiAttributeData(long plReconciliationEventKey, java.lang.String psFieldName, java.util.Map poData) throws tcAPIException, tcEventNotFoundException, tcEventDataReceivedException,tcAttributeNotFoundException
      

      Note:

      For better performance with bulk multivalued attributes or the data for multiple child records instead of a single child record, use the following API:
      void addDirectBulkMultiAttributeData(long reconciliationEventKey, long reconciliationAttributeKey, String tableFieldName, List dataList,String dateFormat) throws tcAPIException, tcEventNotFoundException, tcAttributeNotFoundException, tcEventDataReceivedException,tcInvalidAttributeException
      
    • The providingAllMultiAttributeData method specifies whether the multivalued data being provided is the entire list of data, or only changeset that has been added/updated. By default, the value of the pbFlag is false. If there is no child data or the eventAttribs.eventFinished flag is set to true, then this API must not be invoked.

      public void providingAllMultiAttributeData(long plReconciliationEventKey, String psFieldName, boolean pbFlag) throws tcAPIException;
      
    • The finishReconciliationEvent method is used to mark the end of event creation flow. Particular event status is updated to Data Received, which means that all the data for the particular event, including the child data if any, has been provided. If the eventAttribs.eventFinished flag is set to true, then this API must not be invoked.

      void finishReconciliationEvent(long eventId) throws tcAPIException, tcEventNotFoundException, tcEventDataReceivedException
      
    • The callingEndOfJobAPI method processes all the reconciliation batches in the job. For a scheduled job, this API is automatically called when the job ends. This API must be explicitly called for a nonscheduled job API invocation.

      void callingEndOfJobAPI() throws tcAPIException
      

    Create Event (Bulk): This consists of the following API:

    ReconciliationResult createReconciliationEvents(BatchAttributes batchAttribs, InputData... input)
    

    This is the bulk create API. It creates bulk reconciliation events for the data passed in input data. It accepts all the data including multivalued attributes, and submits it for processing as one batch if the size of data is less then or equals to the batch size. Otherwise, it submits the data in multiple batches. There is no need to call any other API after this.

  3. Process Event: This is a way to force the backend processing of an already created event. The processReconciliationEvent(eventId) API is invoked after create event flow has finished and an already created event needs to be processed as well. This API processes only a particular event, it does not update the batch or job status. If batch status needs to be updated as well, then invoke the callingEndOfJobAPI API after this. Using this API is not recommended because it is synchronous and processes data one at a time, rather than in batch.

    Note:

    If the processReconciliationEvent API is used for processing, then set the reconciliation batch size (batchSize parameter) to 0 in the reconciliation profile of the resource object. See Table 14-5 for more information about this step.
  4. Deletion Detection: This is a way to delete extra data in Oracle Identity Manager that does not exist in the target system. This consists of the following APIs:

    • The provideDeletionDetectionData method takes the list of all the existing target system data for a resource object as input, and then returns a list of matching data found in Oracle Identity Manager.

      Set provideDeletionDetectionData(String resourceObjectName, Map[] inputData) throws tcAPIException, tcIDNotFoundException, tcMultipleMatchesFoundException
      
    • The getMissingAccounts method takes the list keys of already found data in Oracle Identity Manager, and returns a list of extra data that is in Oracle Identity Manager but not in the target system. It retrieves all keys from Oracle Identity Manager and compares them with the keys present in the set returned by the provideDeletionDetectionData method.

      Thor.API.tcResultSet getMissingAccounts(String objectName, Set accountsFound) throws tcAPIException, tcIDNotFoundException, tcDataNotProvidedException
      
    • The deleteDetectedAccounts method takes a list of data found only in Oracle Identity Manager as input, and invokes a delete type create reconciliation event API call, one at a time. The tcResultSet returned by the getMissingAccounts method is passed as parameter to this API.

      long[] deleteDetectedAccounts(Thor.API.tcResultSet poDetectedAccounts) throws tcAPIException, tcAPIException
      

14.6.2 Invoking Non-scheduled Task-Based Reconciliation in a Multithreaded Environment

Example 14-2 shows the sample code to invoke non-scheduled task-based reconciliation in a multithreaded environment:

Example 14-2 Invoking Non-scheduled Task-based Reconciliation in a Multithreaded Environment

public class UserNonSTBasedRecon{
 
     private AtomicInteger threadCount =new AtomicInteger(0);
 
public Long getRandomLong(int maxValue) {
        Random random = new Random();
        long token = random.nextInt(maxValue);
        return token;
    }
     @Test
     public void testCreateUsersUsingNonScheduleTaskConnectorWithThreads() throws Exception {
 
         Thread t = new CreateEvent();
         t.start();
         Thread t2 = new CreateEvent();
         t2.start();
 
     while (true) {
             Thread.currentThread().sleep(5000);
             if (threadCount.get() == 2){
             OIMClient oimClient = null;             ReconOperationsService reconServ = oimClient.getService(ReconOperationsService.class);
                 reconServ.callingEndOfJobAPI();
                 break;
             }
         }
     }
 
     public class CreateEvent extends Thread {
 
         @Override
         public void run() {
 
         String ctxFactory = "weblogic.jndi.WLInitialContextFactory";
             OIMProfileReader reader = new OIMProfileReader();
             String appServerType = reader.getString("appserver.type");
             String hostName = reader.getString("weblogic.host");
             String port = reader.getString("weblogic.port");
             String serverURL = "t3://" + hostName + ":" + port;
             System.out.println("Server URL is : " + serverURL);
             System.out.println("Context Factory is : " + ctxFactory);
             Hashtable<String, String> env = new Hashtable<String, String>();
             env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);
             env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL, ctxFactory);
 
             OIMClient client = new OIMClient(env);
             String username = "xelsysadm";
             String password = "Welcome1";
             try {
                 client.login(username , password.toCharArray());
             } catch (LoginException e1) {
                 throw new SuperRuntimeException(e1.getMessage(), e1);
             }
 
             String uniq2 = getRandomLong(10000).toString();
             long jobId = getRandomLong(10000);
             ContextManager.setValue(Constants.JOB_HISTORY_ID, new ContextAwareNumber(jobId));
             ContextManager.setValue(Constants.JOB_NAME_CONTEXT, new ContextAwareString(jobId +""));
             ReconOperationsService recon;           
             try {
                 recon = client.getService(ReconOperationsService.class);
                 int count = 50;
                 HashMap<String, String> hm = new HashMap<String, String>();
                 ArrayList<Long> eventKeys = new ArrayList<Long>();
                 for (int i = 0; i < count; i++) {
                     hm.put("UserLogin", uniq2 + "ThreadTest" + i);
                     hm.put("FirstName", uniq2 + "Thread" + i);
                     hm.put("lastname", "Test");
                     hm.put("Type", "End-User");
                     hm.put("OrganizationName", "Xellerate Users");
                     hm.put("EmpType", "Full-Time");
                     hm.put("Middlename", "MID");
                     System.out.println("Creating Recon event i ="+ i);
                     long rceKey = recon.createReconciliationEvent("Xellerate User", hm, true);
                     eventKeys.add(rceKey);
                 }
                 assertEquals(count, eventKeys.size());               
             } catch (Exception e) {
                 throw new SuperRuntimeException(e.getMessage(), e);
             } finally {
                 threadCount.set(threadCount.get()+1);
                 ContextManager.popContext();
             }
         }
     }
 }

14.7 Postprocessing for Trusted Reconciliation

If the user login is not passed for trusted reconciliation, then the login handler generates the user login. The password is generated in postprocessing event handler. You can configure Oracle Identity Manager to send notification for the same.

Notification is sent only when the value of the Recon.SEND_NOTIFICATION system property is set to true. See "System Properties in Oracle Identity Manager" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about the Recon.SEND_NOTIFICATION system property.

In SSO disabled environment, for user creation via reconciliation, both the user login and password are generated in postprocess handlers and a single notification is sent for both user login and password.

In SSO enabled environment, because the password is not to be generated, if login is generated in postprocess handler, then notification is sent only for the user login.

14.8 Reconciliation FAQs

This section provides the following FAQs about reconciliation:

What should be performed after reconciliation configuration and before reconciliation run?

After all the reconciliation configuration are done either by importing a connector or via the Design Console, before triggering the scheduled job to start the reconciliation run:

  1. Make sure that IT resource details are correct and you are able to connect to the target system.

  2. Validate if all the reconciliation configurations are correct. This can be done by validating the reconciliation profile using the ProfileValidator mbean available on the Enterprise Manager. For information about various profile configuration issues, see "Troubleshooting Reconciliation Profile Configuration Failures".

How to handle data issues while event generation?

To handle data issues while event generation (when reconciliation events are not getting generated):

  • Enable INFO level logs, as described in "Troubleshooting General Reconciliation Issues".

  • Check INFO levels logs to see if createReconciliationEvent() is getting invoked, which confirms the call to reconciliation engine. Look for log: createEvent Input Data. This also prints the data being passed from the connector to the reconciliation engine.

  • Analyze the logs to check if the event is ignored if the same data already exists in Oracle Identity Manager, thereby not generating the event again, which is expected behavior.

  • If no logs are displayed related to createEvent and ignoreEvent, then the issue is most likely in connector area, even before call is made to the reconciliation engine.

How to handle processing failures?

To handle processing failures:

  • Know if the connector being used is a listener-based connector (push-based connector) such as PSFT or RACF, or is it a pull-based connector. Knowing this is important as push and pull-based connectors follow different processing paths.

  • Check if processing is happening via single event flow, which is end-to-end orchestration, or is it bulk processing using SPs. Single event processing happens mostly with push-based connectors, which invokes the processReconciliationEvent() API or when a failed event is retried/re-evaluated.

  • As mentioned in "Troubleshooting Reconciliation", check the exception if any in the RE_NOTE/RB_NOTE. Complete exception details can be further checked in the Oracle Identity Manager server logs.

  • See "Troubleshooting Reconciliation" for other common failures and resolutions during processing.

How to handle post-processing failures?

To handle post-processing failures:

  • As mentioned in "Troubleshooting Reconciliation", get the orchestration IDs from RB_NOTE/RE_NOTE columns for bulk and single event processing respectively.

  • You can also validate the event by using the EventDiagnostic Mbean, which provides all details related to event processing along with post processing details, such as what is the orchestration status, which all handlers got executed, and failure details if any.

  • If there is some custom event handler not getting executed only in reconciliation flow, then check if the bulk implementation exists or not. The orchestration-related info is available only in the logs and cannot be diagnosed by using above steps.

How to do performance-related analysis?

For performance-related analysis for reconciliation, see "Monitoring Reconciliation Performance Using DMS". In addition, refer to the technote "Oracle Identity Manager 11g Reconciliation Performance Tuning" with Doc ID 1484808.1 at My Oracle Support web site at:

https://support.oracle.com

14.9 Troubleshooting Reconciliation

Before troubleshooting issues related to reconciliation, change the reconciliation logging level to INFO. To do so, add the following logger by using Oracle Enterprise Manager:

  • Name: oracle.iam.reconciliation

  • Oracle Diagnostic Logging Level (Java Level): NOTIFICATION:1(INFO)

For detailed steps of adding a logger, see "Configuring Logging" in Administering Oracle Identity Manager.

Note:

To change the logging level, you can also modify the /domains/DOMAIN_NAME/config/fmwconfig/servers/OIM_SERVER/logging.xml file. To do so:
  1. In the logging.xml file, add a new logger, as shown:

    <LOGGER NAME="oracle.iam.reconciliation" LEVEL="INFO"/>
    
  2. Change the logging level of the 'console-handler' log_handler to INFO.

  3. Restart Oracle Identity Manager.

This section describes troubleshooting reconciliation issues in the following sections:

14.9.1 Troubleshooting General Reconciliation Issues

Table 14-5 lists the troubleshooting steps that you can perform if you encounter reconciliation errors:

Table 14-5 Troubleshooting Reconciliation

Problem Solution

Failure in processing events

The error details can be obtained from the reconciliation tables, such as:

  • For batch processing, the exception is stored in RECON_BATCHES.RB_NOTE column

  • For single event processing, the exception is stored in RECON_EVENTS.RE_NOTE column

Various data corruption issues resulting due to duplicate processing (both single and bulk processing) in case of push-based connectors when they are processing reconciliation using the processReconciliationEvent API

For example, duplicate account creation, status unexpectedly getting changed, and so on.

Set the reconciliation batch size (batchSize parameter) to 0 in the reconciliation profile of the affected resource object.

Failure occurring in kernel orchestration handler

The orchestration ID can be tracked from the reconciliation table, which can further be used to check the status of related handlers, such as:

  • For batch processing, the postprocess only orchestration ID can be read from the RECON_BATCHES.RB_NOTE column

  • For single event processing, end-to-end orchestration ID can be read from the RECON_EVENTS.RE_NOTE column

There is no UI that displays LDAP synchronization during reconciliation. Therefore, you can only track LDAP success or failure by checking the status of LDAP sync event handlers in orchestration based on the ID available in RB_NOTE/RE_NOTE columns.

After a job run, a lot of events are in the Data Received status.

Check if related batches are in Ready For Processing status by using the following statement:

select rb_batch_status, rb_note from recon_batches where rb_batch_status = 'Ready For Processing' and rj_key = JOB_ID_ON_UI

In addition, in the RECON_BATCHES.RB_NOTE, there is some generic exception, such as Connection issue. Fix the issue, and then perform any one of the following:

  • If there is a lot of data, then rerun the reconciliation job.

  • There is a scheduled task provided for manual retry of such failed batches Retry Reconciliation Batch. This can be used for retrying specific batches only. Multiple comma-separated batches are supported.There is no predefined job associated with this schedule task. A job can be created as required.

Race Condition - Events are in failed status because some dependent attribute is still not reconciled, for example, user's manager/organization needs to be reconciled before user.

  • If the size of the data is small, then retry reconciliation automatically handles the race condition, but it is slow.

  • If the size of the data is large, then perform the reconciliation two times. Remove the mapping for the dependent field for the first full reconciliation, and then add the dependent field mapping and perform the full reconciliation second time.

The following error is generated when performing user update for trusted source reconciliation:

ORA Error Code =>ORA-00001: unique constraint (.) violated

For of trusted source reconciliation, if the matching rule is based on Usr_login, then the matching rule must not be case-sensitive. Otherwise, updating users work as creating users, and the error might be generated.

Recon events skipped/not created error is generated with the following SQLException in the logs:

<oracle.iam.reconciliation.dao.event> <BEA-000000> <Generic Information: {0} java.sql.SQLException: ORA-12899: value too large for column "DEV_OIM"."RA_LDAPUSER9504ECC4"."RA_BUSINESSPHONE" (actual: 26, maximum: 20) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:462) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:405)

This issue is because the data passed for the fields from the target is of greater size than the column size in the database table. To resolve this you should either:

  • Modify the data in the target for these fields, as per the column size in the database table, or

  • Modify the field length for these columns from the console and then recreate the recon profile


Note:

The oracle.iam:type=Reconciliation,name=EventDiagnostic MBean with method 'diagnose' can be used to diagnose end-to-end reconciliation event flow. This MBean can be accessed by using Oracle Enterprise Manager. The diagnose method takes reconciliation EventID as input, and shows the following information about the event:
  • Event, batch, job, and history details. This includes the RE_NOTE and the RB_NOTE values, and therefore, indicates the reason for failure, if any, or else the associated orchestration IDs.

  • Old state table data, which is relevant for audit.

  • Staging table data, which is data coming to reconciliation from the target system.

  • Orchestration details, which includes all the event handlers that executed along with their status and reason for failure, if any.

14.9.2 Troubleshooting Database-Related Reconciliation Issues

This section the describes the following database-related issues for reconciliation:

Missing Critical Oracle Database 11g Release 1 Interim Patches

When the RDBMS interim patch# 7614692 is missing, the following error is logged:

ORA-02291: INTEGRITY CONSTRAINT (FK_RECON_EVENTS_USR) VIOLATED - PARENT KEY NOT FOUND
[EXEC] ORA-06512: AT "OIM_SP_RECONBLKUSERCRUD"
[EXEC] ORA-06512: AT "OIM_SP_RECONBLKUSRMLSWRAPPER"
[EXEC] ORA-06512:

To resolve this issue, the following patches must be installed on Oracle Database 11g Release 1 (11.1.0.7.0):

  • p7614692_111070

  • p7000281_111070

  • p8327137_111070

  • p8617824_111070

Note:

You can download all interim patches from the following URL:

http://support.oracle.com

Missing Critical Oracle Database 11g Release 2 Interim Patches

Running some SQL scripts might generate incorrect or inconsistent results on Oracle Database 11g Release 2 (11.2.0.2.0), which do not cause problems in earlier release of Oracle Database.

To resolve this issue, patch# 10259620 for Oracle Database 11g Release 2 must be installed.

Slow Reconciliation and Similar Traces in Error Log

When the SQL scripts having matching rules involving large volume, the entity tables are slow probably because of FULL table scans or unoptimized SQL plans in the database.

Reconciliation can be slow when the matching rule columns are not properly indexed or schema statistics is outdated. The slowness results in error logs similar to the following:

oracle.iam.platform.utils.SuperRuntimeException: java.sql.SQLException:
ORA-01013: user requested cancel of current operation
ORA-06512: at "XL_SP_RECONBLKROLEMATCH"
ORA-06512: at "OIM_SP_RECONBLKROLEMLSWRAPPER"
ORA-06512:
 
at weblogic.jms.client.JMSSession$UseForRunnable.run(JMSSession.java)
at weblogic.work.SelfTuningWorkManagerImpl$WorkAdapterImpl.run(SelfTuningWorkMana gerImpl.java)
at weblogic.work.ExecuteThread.execute(ExecuteThread.java)
at weblogic.work.ExecuteThread.run(ExecuteThread.java)
Caused by: java.sql.SQLException: ORA-01013: user requested cancel of current operation
ORA-06512: at "XL_SP_RECONBLKROLEMATCH"
ORA-06512: at "OIM_SP_RECONBLKROLEMLSWRAPPER"
ORA-06512: 
.
at oracle.jdbc.driver.SQLStateMapping.newSQLException(SQLStateMapping.java)
at oracle.jdbc.driver.DatabaseError.newSQLException(DatabaseError.java)
at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java)
at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java)
at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java)

To resolve this issue:

  1. Verify that all the appropriate indexes are created over matching rule columns.

  2. Verify that the database schema statistics are collected according to the guidelines.

    See Also:

    "Reconciliation Best Practices" for information about creating indexes for reconciliation and collecting database statistics

Reconciliation Event Does Not Process With Error

The reconciliation event does not process with the following error trace (ORA-31061 error):

java.sql.SQLException: ORA-20001: Error occured in XL_SP_ReconBlkChildMthAcntCRUD while processing Batch ID - 48 XL_SP_ReconBlkChildMthAcntCRUD failed e_xlSpReconBlkChildMthAcntCRUD - FORMAT_ERROR_BACKTRACE: ORA-06512: at "SYS.DBMS_XMLGEN", line 7
ORA-06512: at "SYS.DBMS_XMLGEN", line 147
ORA-06512: at "OGD_OIM.OIM_SP_RECONBLKACCOUNTCHGLOG", line 305
ORA-06512: at "OGD_OIM.XL_SP_RECONBLKCHILDMTHACNTCRUD", line 3528
 
FORMAT_ERROR_STACK: ORA-31061: XDB error: special char to escaped char conversion failed.
 -31061 -ERROR- ORA-31061: XDB error: special char to escaped char conversion failed.
ORA-06512: at "OGD_OIM.XL_SP_RECONBLKCHILDMTHACNTCRUD", line 3617
ORA-06512: at "OGD_OIM.XL_SP_RECONBLKACNTRQDCMTCHCRUD", line 91
ORA-06512: at line 1
at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:462)
.
.
.
.
.
.
at weblogic.jdbc.wrapper.PreparedStatement.execute(PreparedStatement.java:99)
at oracle.iam.reconciliation.dao.ReconActionDao$1ReconDBCall$1.process(ReconActionDao.java:1489)
at oracle.iam.reconciliation.dao.ReconActionDao$1ReconDBCall$1.process(ReconActionDao.java:1472)
at oracle.iam.platform.tx.OIMTransactionCallback.doInTransaction(OIMTransactionCallback.java:13)
at oracle.iam.platform.tx.OIMTransactionCallback.doInTransaction(OIMTransactionCallback.java:6)
at org.springframework.transaction.support.TransactionTemplate.execute(TransactionTemplate.java:128)

This is a database-related issue. For a description of this issue, see technote "XDB reports ORA-31011 if content contains illegal characters (Doc ID 8246403.8)" at My Oracle Support web site at:

https://support.oracle.com

The fix for this enhancement is available in Database version 11.2 onwards, but it is disabled by default. To fix this issue, the enhancement must be enabled.

To workaround this issue, remove the special character in the data.

14.9.3 Troubleshooting Reconciliation Profile Configuration Failures

For any issues related to profile configuration failures, validate the profile by using the ProfileValidator Mbean available in Oracle Enterprise Manager. If the profile is invalid, then the profile is displayed along with the cause of the invalid profile.

Table 14-6 lists the troubleshooting steps that you can perform if you encounter reconciliation errors.

Table 14-6 Troubleshooting Reconciliation Profile Configuration Failures

Problem Solution

The profile is invalid, and it fails to load with the following exceptions:

oracle.iam.reconciliation.exception.ConfigNotFoundException OR

oracle.iam.reconciliation.exception.Config with internal exception org.xml.sax.SAXParseException

Perform any one of the following:

  • The exact problem can be diagnosed and fixed by checking the schema validation message.

  • Validate the reconciliation profile XML by using the MBean in Oracle Enterprise Manager.

  • Validate the reconciliation profile by importing the profile and the XSD into an XML schema-aware editor and validate against that schema in that editor, which can point to the exact cause of the failure.

Importing a valid reconciliation profile XML into a system fails to create the necessary configurations.

Check the profile.configure attribute. The value of this attribute must be true.

Check the profile.active attribute. The value of this must be true. Or if the attribute is not present, then it means that profile.active is true.

The following error is generated:

oracle.iam.reconciliation.exception.ReconciliationException: Exception occurred while inserting data into table STAGING_TABLE_NAME due to STAGING_TABLE_NAME

This means that a valid reconciliation profile is loaded, but it has not created any configuration in Oracle Identity Manager.

Check the profile.configure and profile.active attributes.


Note:

The ProfileValidator Mbean is available for validating the reconciliation profile. This MBean can be accessed by using Oracle Enterprise Manager.

14.9.4 Troubleshooting LDAP Reconciliation Issues

This section describes the following issue related to LDAP reconciliation:

LDAP User Create and Update Reconciliation Scheduled Job Fails With Error

In an integrated environment of Oracle Identity Manager with Oracle Unified Directory (OUD) and libOVD, the LDAP User Create and Update Reconciliation scheduled job fails with the following error:

"Invalid syntax of the provided cookie"

This error occurs when a numeric change number value, for example 0, is being passed to libOVD when OUD is used as LDAP, and External Change Log (ECL) is enabled in the libOVD adapter. In the scheduled job page, the numeric value, for example 0, is set in the Last Change Number field. This attribute is used to specify the last changelog identifier processed by this scheduled job.

For OUD, when ECL mode is on, the value of the Last Change Number field must not be a numeric value but a string value, such as:

"dc=us,dc=oracle,dc=com:00000142b752f5cf473900000ce1;"

The following is an example command to get the expected value:

ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w welcome1 -b "" -s base "objectclass=*" lastExternalChangelogCookie
dn: lastExternalChangelogCookie: dc=us,dc=oracle,dc=com:00000142b752f5cf473900000ce1;

External Changelog Cookie Expiration Issue When Performing Reconciliation with OUD

For a description of the issue and troubleshooting information, see "Fixing External Changelog Cookie Expiration Issue When Performing Reconciliation with OUD" in the Oracle Fusion Middleware Integration Guide for Identity Management Suite.

14.10 Populating Data in the RECON_EXCEPTIONS Table

The RECON_EXCEPTIONS table in Oracle Identity Manager database is used to capture error messages generated during account reconciliation. This data is collected for the purpose of generating reports.

See Also:

"Account Reconciliation" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about account reconciliation

If a reconciliation match is found to a deleted user, then you must insert USER_DELETED in the REX_EXCEPTION column and the key of the deleted user in the USR_KEY column of the RECON_EXCEPTIONS table.

If no match is found, then insert USER_NOT_FOUND in the REX_EXCEPTION column.

If account match is found, then check if the account is already deprovisioned. Then insert into RECON_EXCEPTIONS table with the value RESOURCE_DEPROVISIONED in the REX_EXCEPTION column for the user who is to be provisioned.

To populate the RECON_EXEPTIONS table with exception data:

  1. Fetch all the events with the change type != ('Modify' , 'Delete') and event status as ('Single User Match Found', 'Single Org Match Found').

  2. Provision the resource object for the entities by performing the following:

    1. Collect the exception data from RECON_EXCEPTION DB table. To do so, perform any one of the following:

      • Check if the value of the XL.EnableExceptionReports property is TRUE. If it is set to TRUE, then continue to the next step. Otherwise, do not collect the exception data.

      • Select the obj_initial_recon_date in the obj table for the resource object being provisioned, and check if it is earlier than today's date. If an earlier date is displayed, then continue to the next step. Otherwise, do not collect the exception data.

    2. While provisioning the resource object to the user, check if the resource object has already been deprovisioned in Oracle Identity Manager:

      • If the resource object is already deprovisioned, then insert into RECON_EXCEPTIONS table the value RESOURCE_DEPROVISIONED in the REX_EXCEPTION column for the user who is to be provisioned.

      • If the resource object is not deprovisioned, then insert into RECON_EXCEPTIONS table the value RESOURCE_NEVER_PROVISIONED in the REX_EXCEPTION column for the user who is to be provisioned.

14.11 Reconciliation Best Practices

This section describes how to improve performance by identifying indexes that are required for connector tables and reconciliation tables. It contains the following topics:

Note:

Oracle recommends configuring both the entitlement attribute and the key attribute for the child data in reconciliation field mappings to enable effective duplicate entitlement or child data validation. See "Duplicate Validation for Entitlement or Child Data" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about duplicate validation for entitlements or child data.

14.11.1 Additional Indexes Requirement for Matching Module

When Oracle Identity Manager is installed, the necessary indexes are created in the Oracle Identity Manager database schema. However, there can be additional indexes required because of dynamic nature of some of the features in Oracle Identity Manager. This is especially true for reconciliation.

Reconciliation uses matching algorithm to find if the user/account/role/organization for which the change is requested is already existing in Oracle Identity Manager or not. The matching algorithm compares the data in set of columns in Oracle Identity Manager with the data in target horizontal table columns. The columns that contains the matching rules are defined in the reconciliation profile. To improve the performance of the matching operation quickly, there must be correct indexes created on the matching rule columns.

To illustrate the recommended method of identifying the appropriate indexes, a sample Active Directory (ADUser) profile present in the Meta Data Store (MDS) repository is taken as an example.

Selecting Indexes for Reconciliation

To select indexes based on the matching rule criteria:

  1. Open the AD profile file in a text editor.

    Note:

    The AD user profile must be imported from the MDS by using the Oracle Enterprise Manager, as described in "Migrating User Modifiable Metadata Files".
  2. Search for all occurrences of <matchingRule> tag element in the AD profile, as shown in Figure 14-4:

    Figure 14-4 The <matchingRule> Tag Element

    Description of Figure 14-4 follows
    Description of ''Figure 14-4 The <matchingRule> Tag Element''

  3. After identifying the columns constituting each matching rule, create the indexes accordingly.

Note:

  • If any key field is defined in Oracle Identity Manager as case-insensitive, then a function-based index on that key field must be created. For example, if the connector code internally performs a search for the first name, assuming that FIRST_NAME is a key, then appropriate indexing must be done.

  • If multiple or composite keys are used for looking up a user, then choose between individual or composite indexes.

  • Pointers for required indexes can also be taken by monitoring the real-time running of reconciliation process from the database side by using a performance-monitoring tool, such as Oracle Enterprise Manager, or through the Automatic Workload Repository (AWR) Reports available in Oracle Database 11g.

  • To some extent, index creation is automated for profiles created or updated via the Design Console or Deployment Manager import. Validate the automatically created indexes per the rules defined in this section. You must rectify the indexes manually if there are any issues. For profiles created or updated manually, the indexes are not automated and must be created manually. In addition, there is no automation for dropping the indexes if the matching rule field has changed. Dropping indexes must be done manually.

  • The list of existing indexes can be viewed on Oracle Enterprise Manager by using the ProfileValidator Mbean.

  • Index names starting with RDX are reserved for default reconciliation indexes and must not be used for any custom index creation.

14.11.2 Collecting Database Schema Statistics for Reconciliation Performance

Database statistics is essential for the Oracle optimizer to select an optimal plan in running the SQL queries. Oracle recommends that the statistics are collected regularly for Oracle Identity Manager schema. Because Oracle Identity Manager 11g Release 2 (11.1.2.3.0) uses lot of database SQL features for reconciliation process, make sure that the schema statistics are updated before running the reconciliation.

Note:

  • Other options with DBMS_STATS.GATHER_SCHEMA_STATS API can be used as required, such as DEGREE,ESTIMATE_PERCENT based on the environment, data profile, Oracle DB Edition and underlying hardware capabilities.

  • See "Database Performance Monitoring" in the Oracle Fusion Middleware Performance and Tuning Guide for more information about collecting database schema statistics.

Because Oracle Identity Manager reconciliation process is a data-intensive process and quickly brings in large volume of data, database statistics must also be able to represent the underlying data correctly. To achieve this, refer to the following guidelines:

  • Make sure that statistics is collected for reconciliation on a fresh setup or with a low volume with no or negligible existing data in the Oracle Identity Manager schema. Maximum row count in relevant Oracle Identity Manager tables must be between 100 and 1000 rows. Examples of tables are USR table for trusted source reconciliation and parent account table for target resource reconciliation.

  • For the statistics to be a proper representative of data distribution after reconciliation has started and is expected to bring in a large volume of data, such as more than 20000 users or accounts, collect Oracle Identity Manager schema statistics in the following manner:

    1. Plan to gather statistics after the initial collection only after reconciliation has started successfully and has been running for a while. To verify this, check the counts of a few key tables from the Oracle Identity Manager schema, such as USR table for trusted source reconciliation and parent account (UD_*) tables for target resource reconciliation.

    2. After reconciliation has brought in almost 20000 to 25000 rows in the USR table or in the parent account tables, statistics can be collected.

      Note:

      • Statistics can be gathered concurrently with reconciliation running.

      • The row counts specified in the guidelines are examples and you can determine any other row count for collecting statistics.

  • After the statistics is collected, the performance might not improve immediately. However, as older SQL Plans are cleared from the shared pool of the Oracle Database, new and more efficient plans are created and performance improves.

14.12 Monitoring Reconciliation Performance Using DMS

Dynamic Monitoring Service (DMS) commands are used to view performance metrics and configure event tracing. The following DMS matrices are relevant for monitoring reconciliation performance:

  • OIM_ScheduledJob: The time taken by a particular scheduled job run.

  • Reconciliation Service (ReconOperationsService Or tcReconciliationOpIntf): The time taken by each API on the reconciliation service for creating an event. Connector throughput can be calculated as 'Total Scheduled Job time – Total time for creating the events.

  • OIM_JMS: ActionTask shows the consolidated time taken for processing both by the Stored Procedure and the Post Processing done via Orchestration. XLAuditMessage provides information about actual audit processing.

  • OIM_EventHandlers: Time taken by each eventhandler within an orchestration.

  • DMS Dump: If unable to resolve performance and functional issues, then DMS dumps should be provided for analysis. The command is:

    ${mwhome}/oracle_common/common/bin/wlst>>dms.log
    Connect('adminusername','adminpassword');
    dumpMetrics(format='xml');
    Exit();
    

    For detailed information about the command, see the "dumpMetrics" section in "DMS Custom WLST Commands" of the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.