What Are Active Sync-Enabled Resource Adapters? (Sun Identity Manager Deployment Guide)

Sun Identity Manager Deployment Guide

What Are Active Sync-Enabled Resource Adapters?

Active Sync-enabled adapters are an extension of a standard resource adapter and they are used to implement the Active Sync interface for some common resources, such as Active Directory. These adapters pull data changes directly from the resource to initiate the following activities in Identity Manager:

Polling or receiving change event notification
Issuing actions to create, update, or delete resource accounts
Editing or creating users with a custom form
Saving the resource changes
Logging progress information and errors

Active Sync-enabled adapters are particularly suitable for supporting the following resource types:

Applications with audit or notification interfaces

Some applications, such as Microsoft Active Directory and PeopleSoft, have external interfaces. You can configure these application interfaces to add events to an audit log or to notify other applications when certain changes occur.

For example, you can configure the interface to record an transaction in the audit log whenever a user account is modified natively on the Active Directory server. You can configure the Identity Manager Active Directory resource to review this log every 30 minutes and trigger events in Identity Manager when any changes occur. You can register other Active Sync-enabled adapters with the resource through an API, and use event messages to notify the adapter when changes occur. These event messages can reference the item that changed, the information that was updated, and frequently the user who made the change.
Databases populated with update information

You can manage database resources by generating a table of deltas and generate this table in several different ways. For example, you can compare a snapshot of the database to current values and create a new table with the differences. The adapter pulls rows from the table of deltas, processes them, and subsequently marks them when completed.
Databases with modification timestamps

You can create Active Sync-enabled queries for database entries that have been modified after a particular time. The adapters run updates and then poll for new queries. By storing the last successfully processed row, Identity Manager can perform a “starts with” query to minimize the polling impact. Only those changes made to the resource since the previous set of modifications were made are returned for processing.
Resources with change-log entries

Most LDAP servers provide a change-log mechanism that you can use to track changes, optionally constrained to sections of interest in the DIT. By periodically querying the change-log entries, the LDAP resource adapter can update Identity Manager with detected changes; including creates, deletes, and updates.

Active Sync-enabled adapters generally follow these steps when listening or polling for changes to the resource managed by Identity Manager. When the adapter detects that a resource has changed, the Active Sync-enabled adapter:

Extracts the changed information from the resource.
Determines which Identity Manager object is affected.
Builds a map of user attributes to pass to the IAPIFactory.getIAPI method, along with a reference to the adapter and a map of any additional options, which creates an Identity Application Programming Interface (IAPI) object.
Sets the logger on the IAPI event to the adapter’s Active Sync logger.
Submits the IAPI object to the Active Sync Manager.
Active Sync Manager processes the IAPI object and returns a WavesetResult object to the adapter. The WavesetResult object informs the Active Sync-enabled adapter if the operation succeeds.

The WavesetResult object might contain many results from the various steps the Identity Manager system used to update the identity. Typically, a workflow also handles errors within Identity Manager, often ending up as an Approval for a managing administrator.
Exceptions are logged in the Active Sync and Identity Manager tracing logs with the ActiveSyncUtil.logResourceException method.

When Active Sync-enabled adapters detect a change to an account on a resource, the adapter maps the incoming attributes to an Identity Manager user or, if the adapter cannot match the user account, creates an Identity Manager user account.

The following rules and parameters determine what happens when a change is detected.

Parameter	Description
Confirmation Rule	Rule that is evaluated for all users returned by a correlation rule. For each user, the full User view of the correlation Identity Manager identity and the resource account information (placed under the “account.” namespace) are passed to the confirmation rule. The confirmation rule is then expected to return a value which may be expressed like a Boolean value. For example, “true” or “1” or “yes” and “false” or “0” or null. For the Database Table, Flat File, and PeopleSoft Component Active Sync adapters, the default confirmation rule is inherited from the reconciliation policy on the resource. The same confirmation rule can be used for reconciliation and Active Sync.
Correlation Rule	If no Identity Manager user’s resource information is determined to own the resource account, the Correlation Rule is invoked to determine a list of potentially matching users/accountIDs or attribute conditions, used to match the user, based on the resource account attributes (in the account namespace). Returns one of the following types of information that can be used to correlate the entry with an existing Identity Manager account: Identity Manager user name `WSAttributes` object (used for attribute-based search) List of `AttributeCondition` or `WSAttribute`-type items (`AND`-ed attribute-based search) List of `String-`type items (each item is the Identity Manager ID or the user name of an Identity Manager account) If more than one Identity Manager account can be identified by the correlation rule, a confirmation rule or resolve process rule is required to handle the matches. For the Database Table, Flat File, and PeopleSoft Component Active Sync adapters, the default correlation rule is inherited from the reconciliation policy on the resource. The same correlation rule can be used for reconciliation and Active Sync.
Create Unmatched Accounts	If set to `true`, creates an account on the resource when no matching Identity Manager user is found. If `false`, the account is not created unless the process rule is set and the workflow it identifies determines that a new account is warranted. The default is `true`.
Delete Rule	A rule that can expect a map of all values with keys of the form `activeSync.` or `account.` pulled from an entry or line in the flat file. A LighthouseContext object (`display.session`) based on the proxy administrator’s session is made available to the context of the rule. The rule is then expected to return a value which may be expressed like a Boolean value. For example, “true” or “1” or “yes” and “false” or “0” or null. If the rule returns true for an entry, the account deletion request will be processed through forms and workflow, depending on how the adapter is configured.
Populate Global	If set to `true`, populates the global namespace in addition to the ActiveSync namespace. The default value is `false`.
Process Rule	Either the name of a TaskDefinition or a rule that returns the name of a TaskDefinition, to run for every record in the feed. The Process rule gets the resource account attributes in the Active Sync namespace, as well as the resource ID and name. A Process rule controls all functionality that occurs when the system detects any change on the resource. It is used when full control of the account processing is required. As a result, a process rule overrides all other rules. If a Process rule is specified, the process will be run for every row regardless of any other settings on this adapter. At minimum, a process rule must perform the following functions: Query for a matching User view. If the User exists, checkout the view. If not, create the User. Update or populate the view. Checkin the User view. It is possible to synchronize objects other than User, such as LDAP Roles.
Resolve Process Rule	Name of the TaskDefinition or a rule that returns the name of a TaskDefinition to run in case of multiple matches to a record in the feed. The Resolve Process rule gets the resource account attributes as well as the resource ID and name. This rule is also needed if there were no matches and Create Unmatched Accounts was not selected. This workflow can be a process that prompts an administrator for manual action.

Note –

If present, a Process rule determines whether the adapter uses IAPIProcess or attempts to use IAPIUser. If the adapter cannot use IAPIUser because a Correlation or Confirmation rule does not uniquely identify an Identity Manager user for the event (given the other parameter settings), and a Resolve Process rule is configured, the adapter uses the Resolve Process rule to create an IAPIProcess event. Otherwise, the adapter reports an error condition.

IAPIUser checks out a view and makes this view available to the User form.

For creates and updates, IAPIUser checks out the User view.
For deletes, IAPIUser checks out the Deprovision view.

However, a User view is not checked out or available with IAPIProcess. Either a Process rule has been set or a Resolve Process rule is invoked.