Managing Reconciliation

The reconciliation process is primarily managed through the Administrator Interface. However, there are some aspects of reconciliation that cannot be accomplished from this interface. For example, you might need to create new correlation and confirmation rules, reconciliation workflows, or edit the Reconcile configuration object. The following sections describe these features, and others. For general information about defining reconciliation policy, see Business Administrator's Guide.

Reconciliation Policy

Reconciliation policies allow you to establish a set of responses, by resource, for each reconciliation task. Within a policy, you select the server to run reconciliation, determine how often and when reconciliation takes place, and set responses to each situation encountered during reconciliation. You can also configure reconciliation to detect changes made natively (not made through Identity Manager) to account attributes.

Each of these policy settings can be defined at several scopes:

• Globally (for all resource types)

• For a specific resource type

• For an individual resource instance

The value at each scope becomes the default for each sub-scope. Thus, reconciliation policy defines an inheritance tree:

• The global value becomes the default for every resource type.

• Each resource type can inherit the global value or specify a value.

• The resource type value is the default for every resource instance of that type.

• Each resource instance can inherit value of its parent resource type, or specify a value.

Inheritance makes it easier to manage policy for a large number of resources (especially if many of them will have the same settings).

For example, if you want to treat all resources in the same way, you need to manage only one set of policy settings, at the global level. If you want to treat all Windows resources one way and all Solaris resources another way, you need to manage policy settings at only two scopes: one for each of these two resource types. If there are exceptions to the policy defined at the resource type level for a few specific resource instances, the necessary policy settings can be overridden (specified) for those individual resources. Since each policy setting is inherited separately, only the settings that differ need to be specified; the other policy settings may still inherit their values from above.

Correlation and Confirmation Rules

Identity Manager matches resource accounts that are not linked to a user with Identity Manager users in two phases:

• Correlation. Finding potential owners

• Confirmation. Testing each potential owner

A correlation rule looks for Identity Manager users that might own an account. A confirmation rule tests an Identity Manager user against an account to determine whether the user actually does own the account. This two-stage approach allows Identity Manager to optimize correlation, by quickly finding possible owners (based on name or attributes), and by performing expensive checks only on the possible owners.

Reconciliation policy allows you to select a correlation rule and a confirmation rule for each resource. (You may also specify No Confirmation Rule.) The default correlation rule is to look for a user with a name that exactly matches the account ID of the input account. By default, no confirmation rule is used.

Correlation and confirmation rules are also used for discovery and Active Sync.

Identity Manager predefines a number of correlation and confirmation rules in sample/reconRules.xml. You can also write your own correlation and confirmation rules. Any rule object with a subtype of SUBTYPE_ACCOUNT_CORRELATION_RULE or SUBTYPE_ACCOUNT_CONFIRMATION_RULE automatically appears in the appropriate Reconciliation Policy selection list.

Correlation Rules

A correlation rule can generate a list of user names based on values of the attributes of the resource account. A correlation rule may also generate a list of attribute conditions (referring to queryable attributes of a user object) that will be used to select users.

A correlation rule is run once for each unclaimed account.

A correlation rule should be relatively “inexpensive” but as selective as possible. If possible, defer expensive processing to a confirmation rule.

Identity Manager predefines several correlation rules in sample/reconRules.xml:

• User Name Matches AccountId. Returns the value of the accountId attribute. It selects as a possible owner any Identity Manager user with a name that matches the resource account ID. This is the default correlation rule.

• User Owns Matching AccountId. Returns a list of attribute conditions. This will select as a possible owner any Identity Manager user that owns a resource account that matches the same accountId value.

• User Email Matches Account Email. Returns a list of attribute conditions that will select Identity Manager users based on the account’s email attribute.

Input for any correlation rule is a map of the account attributes. Output must be one of:

• String (containing user name or ID)

• List of String elements (each a user name or ID)

• List of WSAttribute elements

• List of AttributeCondition elements

A more complicated rule might combine or manipulate account attribute values to generate a list of names or a list of attribute conditions.

Attribute conditions must refer to queryable attributes, which are configured as QueryableAttrNames in the UserUIConfig object.

For example, reconRules.xml contains a fourth sample correlation rule, User FullName Matches Account FullName. XML comments disable this rule, because it will not work correctly without additional configuration. This rule looks for Identity Manager users based on fullname, but this attribute is not queryable by default.

Correlating on an extended attribute requires special configuration:

• The extended attribute must be specified as queryable in UserUIConfig (added to the list of QueryableAttrNames).

• The Identity Manager application (or the application server) may need to be restarted for the UserUIConfig change to take effect.

Confirmation Rules

A confirmation rule is run once for each matching user returned by the correlation rule.

A typical confirmation rule compares internal values from the user view to the values of account attributes. As an optional second stage in correlation processing, the confirmation rule performs checks that cannot be expressed in a correlation rule (or that are too expensive to evaluate in a correlation rule). In general, you need a confirmation rule only in the following circumstances:

• The correlation rule may return more than one matching user

• User values that must be compared are not queryable

Identity Manager predefines two confirmation rules in sample/reconRules.xml:

• User Email Matches Account Email. Returns a value of true if the user’s email matches the account’s email. This illustrates the fact that many ownership decisions could be expressed with either a correlation rule or a confirmation rule. However, since the email attribute of an Identity Manager user is automatically queryable, it would almost always be more efficient to express this as a correlation rule.

• User First And Last Names Match Account. Uses the XPRESS language to compare the user’s first and last name to the same values of the account.

Inputs to any confirmation rule are:

• userview. Full view of an Identity Manager user.

• account. Map of resource account attributes.

A confirmation rule returns a string-form Boolean value of true if the user owns the account; otherwise, it returns a value of false.

The default confirmation rule is No Confirmation Rule. This assumes that the correlation rule is selective enough to find at most one user for each account. If the correlation rule selects more than one user, the account situation will be DISPUTED.

CorrelationPlan Objects

Correlation logic can indicate a resource account's type. During reconciliation, the automatic link must know about account type because no form is used to perform this action.

When reconciliation performs a LINK response for a resource account, it typically assigns the account to the user as the default account type. However, on a resource that is configured for multiple accounts per user, this may not always be appropriate. Specifically, discovered accounts can belong to a specific account type and should be linked to the user as such. To assign the appropriate account type, reconciliation must be informed of the account type to use. Identity Manager accomplishes by returning this information as part of the result of the correlation rule.

A CorrelationPlan object extends the result of a correlation rule to allow the account type to be identified. Therefore, a correlation rule must return a CorrelationPlan if the account is of a specific account type. However, a CorrelationPlan can also be used for standard resources as well. Unless specifically set, a CorrelationPlan indicates the default account type.

Refer to sample/correlationRules.xml and the Javadoc for examples and details on using a CorrelationPlan as the result of a correlation rule.

Reconciliation Workflows

You can extend typical reconciliation processing by exposing a number of attachment points for user-defined workflows.

If you are using expensive (that is, long running) per-account workflows, consider modifying your default workflow configuration as described in the Configuring Workflow Properties section of Deployment Reference.

Pre-Resource Workflow

A pre-resource workflow can be launched before any other reconciliation processing is started. The Notify Reconcile Start workflow is an example of a pre-resource workflow.

The Notify Reconcile Start workflow e-mails an administrator with notice that a reconcile has started for a resource. You must configure the Notify Reconcile Start e-mail template before running this workflow.

The following parameters are passed to the pre-resource workflow:

• resourceName. Name of the resource that will be reconciled.

• resourceId. Object ID of the resource that will be reconciled.

Per-Account Workflow

The per-account workflow is launched for each account processed by reconciliation, after the response (if any) has completed. The type of response and the response result do not affect this workflow.

The Notify Reconcile Response workflow is an example of a per-account workflow. It e-mails an administrator when the reconcile process attempts to automatically respond to a discovered situation. You must configure the Notify Reconcile Response e-mail template before running this workflow.

The following parameters are passed to the per-account workflow:

• accountId. Name of the resource account that was reconciled.

• resourceId. Object ID of the resource being reconciled.

• resourceName. Name of the resource being reconciled.

• userID. Object ID of the Identity Manager user identified as the account owner (by claim or correlation, depending on the situation). If no user is associated with the account, this is null.

• userName. Name of the Identity Manager user identified as the account owner (by claim or correlation, depending on the situation). If no user is associated with the account, this is null.

• initialSituation. The situation that was initially discovered for the account, triggering the response. The value is a valid message key.

• responseSuccess. Boolean value indicating whether the response completed successfully. If no response was performed, this is null.

• finalSituation. Reconciliation situation the account was in after applying the response. If the account no longer exists and Identity Manager contains no references to it, this is null.

Post-Resource Workflow

A post-resource workflow can be launched after all other reconciliation processing is complete. The Notify Reconcile Finish workflow is an example post-resource workflow.

The Notify Reconcile Finish workflow e-mails an administrator with notice that a reconcile has finished for a resource. You must configure the Notify Reconcile Finish e-mail template before running this workflow.

The following parameters are passed into the post-resource workflow:

• resourceName. Name of the resource that was reconciled.

• resourceId. Object ID of the resource just reconciled.

Auditing Native Changes

The Audit Native Change To Account Attributes workflow is launched when reconciliation or the provisioner detects a change to the attributes of a resource account that was not initiated through Identity Manager. Only user-specified attributes are monitored for changes. By default, no attributes are monitored.

The following parameters are passed to the workflow:

• resource. Resource object where the account was changed natively.

• accountID. Name of the resource account that was changed natively.

• prevAttributes. Map containing the monitored resource account attributes recorded by Identity Manager.

• newAttributes. Map containing the monitored resource account attributes currently set on the resource.

• attributeChanges. Map containing the List of generic objects that indicate which attributes have changed. Each object contains the previous and new values.

• formattedChanges. String representing the attribute changes in compact format, suitable for an audit record.

To audit native changes, you must do the following:

• On the Edit Reconciliation Policy page, select the Detect native changes to account attributes option from the Attribute-level reconciliation drop-down menu. You might need to uncheck the Inherit resource type policy check box to display a list of attributes. Select the attributes to audit.

• Add Changes Outside Identity Manager to the list of audit events. To do this, select the Configure tab, then Audit Events on the left.

Resource Scheduling

Reconciliation maintains two separate schedules for each resource: one for incremental reconciliation, and another for full reconciliation.

Each resource is scheduled by a separate “requester” task. Configuring a reconciliation schedule for a resource in the reconciliation policy GUI configures the TaskSchedule for the requester task. This allows reconciliation to be controlled by an external task scheduler, if desired. It also minimizes the overhead of the reconciliation task. A reconciliation daemon that is not doing anything consumes very few resources, since it periodically polls an in-memory queue (rather than querying the database for resources that are ready to reconcile).

Reconciliation accesses each resource through a resource adapter. Reconciliation calls the adapter directly to list accounts, iterate accounts, or fetch an individual resource account. Reconciliation also accesses resources indirectly through Provisioner, and uses Provisioner to create a resource account or Identity Manager user from a resource account.

Reconciliation and Provisioner both maintain the account index. Also, reconciling a resource prunes the Account Index each time. The reconciliation task automatically removes any entry for an account that no longer exists on the resource, unless that account is owned by an Identity Manager user. Therefore, it should not be necessary to attempt to manually clear the Account Index for a resource.

Each Identity Manager server runs reconciliation as a daemon task. This means that the Identity Manager scheduler starts the reconciliation task immediately and automatically restarts the task if it dies.

Resource reconciliation is not automatically restarted. The ReconTask daemon itself is automatically restarted, which enables it to respond to any new request; but any request in process when the host server dies (or when the application server is shut down) is lost. The daemon does not restart resource reconciliation because it may be inappropriate to reconcile the resource at a time other than when requested.

Reconcile Configuration Object

The ReconcileConfiguration object contains several attributes that cannot be edited from the Edit Reconciliation Policy page.

The following table defines the reconciliation attributes. Use the debug pages to edit the attribute values in the ReconcileConfiguration object (#ID#Configuration:ReconcileConfiguration)

The following example shows the default values for the ReconcileConfiguration object.

Example 3–1 Default Values for the ReconcileConfiguration Object

<Configuration id=’#ID#Configuration:ReconcileConfiguration’ name=’Reconcile Configuration’> 
   <Extension> 
      <Object> 
         <Attribute name=’listTimeout’ value=’600000’ /> 
         <Attribute name=’fetchTimeout’ value=’60000’ /> 
         <Attribute name=’maxConcurrentResources’ value=’3’ /> 
         <Attribute name=’maxQueueSize’ value=’1000’ /> 
      </Object> 
   </Extension> 
   <MemberObjectGroups> 
      <ObjectRef type=’ObjectGroup’ id=’#ID#All’ name=’All’/> 
   </MemberObjectGroups>
</Configuration>