Chapter 3 Data Loading and Synchronization

This chapter presents an overview of the techniques that can be used to load and synchronize account information from a resource into Identity Manager.

It is important to clearly distinguish between Identity Manager users and resource accounts. The following definitions make it easier to understand the topic:

• User. A virtual identity that is managed by Identity Manager. An Identity Manager user may refer to any number of accounts.

• Account. A concrete identity that is managed by a resource (or, more precisely, by an external system or application that is represented as a Resource object in Identity Manager). For example, an entry in /etc/passwd on a UNIX system, an entry in the SAM database on a Windows system, and a UserProfile in RACF all represent accounts.

• Administrator. A person with responsibility for configuring and maintaining the Identity Manager system.

Identity Manager stores information about known resource accounts and users in the account index. At a minimum, each entry in the account index contains an account ID and an Identity Manager resource ID. An entry might also contain additional information, such as the native GUID or the status (enabled/disabled) of an account. An entry might also record the ID of an Identity Manager user as the owner of the account, or it might record a list of possible owners.

Topics discussed in this chapter include:

• Types of Data Loading

• Load Operation Context

• Managing Reconciliation

• Managing Active Sync

Types of Data Loading

Data loading is the process of importing account information from resources into Identity Manager and assigning these accounts to Identity Manager users. Identity Manager supports the following features that load account data from resources:

• Discovery. Provides basic functions that initially load resource accounts into Identity Manager.

• Reconciliation. Periodically loads resource account information into Identity Manager, taking action on each account according to configured policy.

• Active Sync. Allows information that is stored in an “authoritative” external resource (such as an application or database) to synchronize with Identity Manager user data. An Active Sync-enabled adapter “listens” or polls for changes to the authoritative resource.

Each of these concepts is discussed in detail. A table comparing the types of data loading can be found in Summary of Data Loading Types.

Discovery

The discovery processes are designed to be used when a resource is being deployed for the first time. They provide a means to load account information into Identity Manager quickly. As a result, they do not provide all the features found in reconciliation or Active Sync. For example, the discovery process does not add entries to the Account Index. Nor can you run workflows before or after discovery. However, the discovery processes allow you to determine more quickly whether correlation rules are working as expected.

When you begin a discovery process, Identity Manager determines whether an input account matches (or correlates with) an existing user. If it does, the discovery process merges the account into the user. The process will create a new Identity Manager user from any input account that does not match.

Identity Manager provides the following discovery functions:

• Load From File. Reads accounts listed in a file and loads them into Identity Manager.

• Load From Resource. Extracts accounts from a resource and loads them directly into Identity Manager.

• Create Bulk Action. Executes user creation commands listed in a file.

See the following sections for more information about these discovery processes.

Load from File

The Load from File discovery process reads account information that has been written into an XML or CSV (comma-separated values) file.

Some resources, such as Active Directory, have the ability to export native account information into a comma-separated values (CSV) format. These CSV files can be used to create Identity Manager accounts. See Business Administrator's Guide for more information about CSV formatting.

When you load from a file, you must specify which account correlation and confirmation rules to use. See Correlation and Confirmation Rules for more information.

Load from Resource

The Load from Resource feature scans a target system and returns information on all users. Identity Manager then creates and updates users. An adapter must have been configured for the resource before you can load from the resource.

When you load from a resource, you must specify which account correlation and confirmation rules to use. See Correlation and Confirmation Rules for more information.

Create Bulk Action

Bulk actions allow you to act on multiple accounts at the same time. You can use bulk actions to create, update, and delete Identity Manager and resource accounts, but this discussion will be limited to Identity Manager creating accounts. See Business Administrator's Guide for a full description of bulk actions.

Bulk actions are specified using comma-separated values (CSV). The structure of these values differs from those specified in a Load from File process.

The CSV format consists of two or more input lines. Each line consists of a list of values separated by commas. The first line contains field names. The remaining lines each correspond to an action to be performed on an Identity Manager user, the user’s resource accounts, or both. Each line should contain the same number of values. Empty values will leave the corresponding field value unchanged.

Two fields are required in any bulk action CSV input:

• user. Contains the name of the Identity Manager user.

• command. Contains the action taken on the Identity Manager user. For creating Identity Manager users, this value must be Create.

The third and subsequent fields are from the User view. The field names used are the path expressions for the attributes in the views. See Understanding the User View in Deployment Reference for information on the attributes that are available in the User View. If you are using a customized User Form, then the field names in the form contain some of the path expressions that you can use.

Following is a list of some of the more common path expressions used in bulk actions:

• waveset.roles. A list of one or more role names to assign to the Identity Manager account.

• waveset.resources. A list of one or more resource names to assign to the Identity Manager account.

• waveset.applications. A list of one or more resource groups to assign to the Identity Manager account.

• waveset.organization. The organization name in which to place the Identity Manager account.

• accounts[resource_name].attribute_name. A resource account attribute. The names of the attributes are listed in the schema for the resource.

Some fields can have multiple values. For example, the waveset.resources field can be used to assign multiple resources to a user. You can use the vertical bar (|) character (also known as the “pipe” character), to separate multiple values in a field. The syntax for multiple values can be specified like this:

value0 | value1 [ | value2 ... ]

The following example illustrates Create bulk actions:

command,user,waveset.resources,password.password,password.confirmPassword,accounts[AD].description
,accounts[Solaris].comment
Create,John Doe,AD|Solaris,changeit,changeit,John Doe,John Doe
Create,Jane Smith,AD,changeit,changeit,Jane Smith,

The Create bulk action is more versatile than the from Load from File process. Bulk actions can work with multiple resources, while Load from File loads information from one resource at a time.

Reconciliation

Reconciliation compares the contents of the account index to what each resource currently contains. Reconciliation can perform the following functions:

• Detect new and deleted accounts

• Detect changes in account attribute values

• Correlate accounts with Identity Manager users

• Detect accounts that are not associated with Identity Manager users

• Run a workflow in response to each account situation that it detects

• Detect when a user has been moved from one container on a resource to another container on a resource

An adapter must have been configured for the resource before you can reconcile. See Resource Reference for more information about adapters.

There are two types of reconciliation: full and incremental.

Full Reconciliation

Full reconciliation recalculates the existence, ownership, and situation for each account ID listed by the adapter. It examines each Identity Manager user that claims the resource to recalculate ownership.

An Identity Manager user can claim a resource by:

• Having a role that implies the resource

• Having a direct resource assignment

• Referring to an account on that resource

• Having a resource group

For each account, reconciliation process confirms that any Identity Manager owner recorded in the Account Index still exists and still claims the account. Any account that does not have an owner is correlated with Identity Manager users (as long as reconciliation policy for that resource specifies a correlation rule). If a correlation rule suggests one or more possible owners, then each of them will be double-checked in a confirmation rule (if one is specified). See Correlation and Confirmation Rulesfor more information about rules.

Once a situation has been determined for the account, reconciliation will perform any response that is configured in the reconciliation policy for that resource. If the reconciliation policy specifies a workflow to be performed per-account, full reconciliation will perform this for each account that is reconciled, after the situation action is performed. See Reconciliation Workflows for more information about workflows.

Incremental Reconciliation

Incremental reconciliation is analogous to incremental backup: it is faster than full reconciliation, and does most of what you need, but is not as complete as full reconciliation.

Incremental reconciliation trusts that the information maintained in the account index is correct. Trusting that the list of known account IDs is correct, and that ownership of the account by any Identity Manager owner is correctly recorded, allows incremental reconciliation to skip or shorten several processing phases.

Incremental reconciliation skips the step of examining Identity Manager users that claim the resource. Incremental reconciliation also calculates a situation only for accounts that have been added or deleted since the resource was last reconciled. It does this by comparing the list of account IDs in the account index for that resource to the list of account IDs returned by the resource adapter. New accounts are recorded as existing, deleted accounts are recorded as no longer existing, and only these two sets of accounts are processed further.

Because incremental reconciliation is much faster and uses fewer processing cycles than full reconciliation, you may want to schedule incremental reconciliation more frequently and schedule full reconciliation less often.

Active Sync

Active Sync “listens” or polls for changes to a resource, detecting incremental changes in real time. Because Active Sync is designed to detect changes, it should not be used to load account information into Identity Manager for the first time. Instead, use reconciliation or a discovery process.

In general, you run reconciliation on an Active Sync resource in the following circumstances:

• To perform an initial load on the resource.

• To detect any attributes that have not been updated in Identity Manager because Active Sync has been configured to ignore or filter out the attributes.

Active Sync differs from reconciliation in the following ways:

• Active Sync allows an administrator to specify a user form that ensures attributes across multiple accounts are kept synchronized.

• A process rule can be implemented that fully controls all Active Sync processing. This is typically enabled when extraordinary actions need to be performed when an account on a resource changes, such as editing multiple objects in the repository.

Active Sync requires the use of an Active Sync-enabled adapter that has been properly configured. See Business Administrator's Guide for more information about configuring a resource to implement Active Sync.

Summary of Data Loading Types

The following table compares the capabilities of discovery and reconciliation.

Load Operation Context

The following table provides information about the common Identity Manager processes or tasks related to the load operations category.

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>

Managing Active Sync

Active Sync-enabled adapters can be managed in the Administrator Interface. This interface contains a wizard that allows an administrator to fully configure most aspects of Active Sync on a single adapter. The wizard also allows the administrator to construct a resource, or input, form, without using the Sun Identity Manager Integrated Development Environment. For more details about the Active Sync wizard, see Business Administrator's Guide.

How Active Sync-Enabled Adapters Work

This section describes:

• Overview of the basic steps of adapter processing

• Active Sync variable context

• Using rules

• Using forms

• Launching workflow processes

Basic Steps of Adapter Processing

All Active Sync-enabled adapters follow the following basic steps when listening or polling for changes to the resource defined in Identity Manager. When the adapter detects that a resource has changed, the Active Sync-enabled adapter:

1. Extracts the changed information from the resource.

2. Determines which Identity Manager object is affected.

3. Builds a map of user attributes to pass to the system, along with a reference to the adapter and a map of any additional options, which creates an Identity Application Programming Interface (IAPI) object.

4. Submits the IAPI object to the ActiveSync Manager.

5. ActiveSync Manager processes the object and returns to the adapter a WavesetResult object that informs the Active Sync-enabled adapter if the operation succeeds. This object can contain many results from the various steps that the Identity Manager system uses to update the identity. Typically, a workflow also handles errors within Identity Manager, often ending up as an Approval for a managing administrator.

Active Sync Namespace

The following table provides information about the common Identity Manager processes or tasks related to the Active Sync category.

Using Rules

When the Active Sync-enabled adapter detects a change to an account on a resource, it either maps the incoming attributes to an Identity Manager user, or creates an Identity Manager user account if none can be matched and if the Active Sync resource has been configured to do so.

The Active Sync wizard allows you to specify rules to control what happens when various conditions occur. The following table describes each type of rule.

If the Adapter Does Not Find the User

If Identity Manager cannot find a match with an existing Identity Manager user, it turns an update operation into a create operation if the Create Unmatched Accounts setting is true, or the Resolve Process workflow indicates a feedOp of create.

The feedOp field is available to forms that contain logic to create, delete, or update users. You can use this field to disable or enable fields that are specific to one kind of event (for example, the generation of a password when the feedOp field is set to create).

This example feedOp field creates a password only when the Active Sync-enabled adapter detects a user on the resource that is not matched by a user in Identity Manager, and creates the user in Identity Manager.

Example 3–2 Example feedOp Field

<Field name=’waveset.password’> 
   <Disable> 
      <neq> 
         <ref>feedOp</ref> 
         <s>create</s> 
      </neq> 
   </Disable> 
   <expression> 
      <cond> 
         <notnull> 
            <ref>activeSync.password</ref> 
         </notnull> 
         <ref>activeSync.password</ref> 
         <s>change12345</s> 
      </cond> 
   </expression> 
</Field>

Using Forms

Active Sync-enabled adapters typically use two types of forms during processing: a resource form and a user form.

Form processing occurs in three steps:

1. Active Sync fields are filled in with attribute and resource information. Use the activeSync namespace to retrieve and set attributes on the resource.

2. The resource form is expanded and derived. During this expansion, all user view attributes are available.

3. The user form is expanded and derived.

   The $WSHOME/sample/forms directory provides sample forms that end with ActiveSyncForm.xml. They include logic for handling the cases of new and existing users, as well as logic for disabling or deleting the Identity Manager user when a deletion is detected on the resource.

Place only resource-specific logic in the resource form and include common logic in the user form, possibly enabled when the feedop field is not null. If the resource form is set to none, all of the Active Sync attributes (except accountId) are named global and will propagate automatically.

Resource Form

The resource form is the form that the administrator selects from a pull-down menu when the resource is created or edited. A reference to a selected form is stored in the resource object.

Resource forms are used with Active Sync-enabled adapters in the following ways:

• Translate incoming attributes from the schema map.

• Generate fields such as password, role, and organization.

• Provide simple control logic for custom processing, including logic for handling the cases of new and existing users, as well as logic for disabling or deleting the Identity Manager user when a deletion has been detected.

• Copy and optionally transform attributes from activeSync to fields that the user form takes as inputs. The required fields for a creation operation are waveset.accountId and waveset.password. Other field can be set, too, (for example, accounts[AD].email or waveset.resources).

• Cancel the processing of the user by setting IAPI.cancel to true. This is often used to ignore updates to certain users.

  The following example shows a simple field that will ignore all users with the last name Doe.

Example 3–3 Field Ignores All Users with Last Name Doe

<Field name=’IAPI.cancel’>
   <Disable>
      <neq>
         <ref>activeSync.lastName</ref>
         <s>Doe</s>
      </neq>
   </Disable>
   <expression>
      <s>true</s>
   </expression>
</Field>

Resource forms include logic for handling the cases of new and existing users, as well as logic for disabling or deleting the Identity Manager user when a deletion has been detected.

User Form

The user form is used for editing from the Identity Manager interface. You assign it by assigning a proxy administrator to the adapter. If the proxy administrator has a user form associated with him, this form is applied to the user view at processing time.

Proxy Administrator and the User Form

You set a proxy administrator for an adapter through the ProxyAdministrator attribute, which you can set to any Identity Manager administrator. All Active Sync-enabled adapter operations are performed as though the Proxy Administrator was performing them. If no proxy administrator is assigned, the default user form is specified.

Alternative Form to Process Attributes

Best practice suggests keeping common changes, such as deriving a fullname from the first and last name, in the user form. The resource form should contain resource-specific changes, such as disabling the user when their HR status changes. However, you can alternatively place it in an included form after the desired attributes are placed in a common path, such as incoming.

<Form>
   <Field name=’incoming.lastname’>
      <ref>activeSync.lastname</ref>
   </Field>
   <Field name=’incoming.firstname’>
      <ref>activeSync.firstname</ref>
   </Field>
</Form>

Subsequently, in the common form, reference incoming.xxx for the common logic:

<Form>
   <Field name=’fullname’>
       <concat>
           <ref>incoming.firstname</ref>
          <s> </s>
          <ref>incoming.lastname</ref>
       </concat>
    </Field>
</Form>

Process Cancel Action

To cancel the processing of a user, set IAPI.cancel to true in the resource form. You can use this to ignore updates to certain users.

If IAPI.cancel is set to a value of true in an Active Sync form, then the process associated with an IAPIUser or IAPIProcess event will not be launched.

The following example shows a simple field in the resource form that ignores all users with the last name Doe.

<Field name=’IAPI.cancel’>
    <Disable>
      <eq><ref>activeSync.lastName</ref><s>Doe</s></eq>
   </Disable>
    <Expansion>
       <s>true</s>
    </Expansion>
 </Field>

Launching Workflow Processes

The Active Sync wizard allows an administrator to specify a pre-poll and post-poll workflow. These workflows are similar in concept to the workflows discussed in Reconciliation Workflows.

Some Active Sync-enabled adapters support a resource attribute that runs a specified workflow instead of checking the pulled changes into the user view. This workflow is run with an input variable of only the Active Sync data. For adapters that do not support a separate process, or one where you want to use the standard user form and then launch a process, you can override the process by setting options.

<Form>
    <Field name=’sourceOptions.Process’>
       <Expansion>
          <s>My workflow process name</s>
       </Expansion>
    </Field>
 </Form>

The workflow specified through the form is called just like a standard provisioning workflow. Sun strongly recommends that you base your custom workflow on the standard create and update workflow. Consult the create and update user workflows in workflow.xml.

Example: Disabling Accounts through Active Sync-Enabled Adapters

In this example, the resource (an HR database) can be updated with an employee’s current status at the company. Based on the input from this HR database, the Active Sync-enabled adapter can disable, delete, create, or perform other actions on the user’s accounts across the enterprise by updating the Identity Manager repository.

The following code example disables all accounts for an employee if there is an incoming attribute called Status and it is not active (“A”). The following table identifies the four states of this attribute.

Based on the value of the Status attribute, the account can be disabled or enabled.

Example 3–4 Disabling Accounts for Incoming, Inactive Status Attribute

<?xml version=’1.0’ encoding=’UTF-8’?> 
<!DOCTYPE Configuration PUBLIC ’waveset.dtd’ ’waveset.dtd’> 
<Configuration wstype=’UserForm’ name=’PeopleSoft ActiveSync Form’> 
   <Extension> 
      <Form> 
<!-- this is a sample of how to map the accountID to a different field than the 
one from the schema map 
Commented out because we want to use the default account ID mapped from the resource 
Schema Map. 
<Field name=’waveset.accountId’> 
   <Disable>
      <neq>
         <ref>feedOp</ref>
         <s>create</s>
      </neq>
   </Disable> 
   <Expansion> 
      <concat>
         <s>ps</s>
         <ref>waveset.accountId</ref>
      </concat> 
   </Expansion> 
</Field> -->

 <!-- this is the real one, limited to create --> 
<Field name=’waveset.accountId’> 
   <Disable>
      <neq>
         <ref>feedOp</ref>
         <s>create</s>
      </neq>
   </Disable> 
   <Expansion> 
      <ref>activeSync.EMPLID</ref> 
   </Expansion> 
</Field> 

<!-- we need to make up a password for accounts that are being created. This picks 
the last six digits of the SSN. --> 
<Field name=’waveset.password’> 
   <Disable>
      <neq>
         <ref>feedOp</ref>
         <s>create</s>
      </neq>
   </Disable> 
   <expression> 
      <s>change123456</s> 
   </expression> 
</Field> 

<Field name=’waveset.resources’> 
<!-- <Disable><neq><ref>feedOp</ref><s>create</s></neq></Disable> --> 
<!-- Don’t change the resources list if it already contains peoplesoft --> 
   <Disable> 
      <member> 
         <ref>activeSync.resourceName</ref> 
         <ref>waveset.resources</ref> 
      </member> 
   </Disable> 
   <expression> 
      <appendAll> 
         <ref>waveset.resources</ref> 
         <ref>activeSync.resourceName</ref> 
      </appendAll> 
   </expression> 
</Field> 

<!-- Status is mapped by the schema map to PS_JOB.EMPL_STATUS which has at least 
four states - 
A for active, 
T terminated, 
L laid off, and 
S which is a pending change. 
The audit data tells us what the state was, and the global data tells us what 
it is. Based on the change we can disable or enable the account Note that this 
can happen on a create also! --> 

<Field> 
   <Disable>
      <eq>
         <ref>activeSync.Status</ref>
         <s>A</s>
      </eq>
   </Disable> 
   <Field name=’waveset.disabled’> 
      <Expansion> 
         <s>true</s> 
      </Expansion> 
   </Field> 
   <FieldLoop for=’name’ in=’waveset.accounts[*].name’> 
      <Field name=’accounts[$(name)].disable’> 
         <expression> 
            <s>true</s> 
         </expression> 
      </Field> 
   </FieldLoop> 
</Field> 

<!-- Status is mapped by the schema map to PS_JOB.EMPL_STATUS which has at least 
four states - 
A for active, 
T terminated, 
L laid off, and 
S which is a pending change. 
This is the enable logic. It is disabled if the account status is <> A or is 
already enabled --> 

<Field> 
   <Disable> 
      <neq> 
         <ref>activeSync.Status</ref> 
         <s>A</s> 
      </neq> 
   </Disable> 
   <Field name=’waveset.disabled’> 
      <Disable>
         <eq>
            <ref>waveset.disabled</ref>
            <s>false</s>
         </eq>
      </Disable> 
      <Expansion> 
         <s>false</s> 
      </Expansion> 
   </Field> 
   <FieldLoop for=’name’ in=’waveset.accounts[*].name’> 
      <Field name=’accounts[$(name)].disable’> 
         <Expansion> 
            <s>false</s> 
         </Expansion> 
      </Field> 
   </FieldLoop> 
</Field> 
</Form> 
</Extension> 
<MemberObjectGroups> 
<ObjectRef type=’ObjectGroup’ id=’#ID#Top’ name=’Top’/> 
</MemberObjectGroups> 
</Configuration>