test

Sun Identity Manager Deployment Guide

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:

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.

Process or Task Running  

How it is Used  

Namespace  

ActiveSync IAPIUser

  • Processes user-related changes on a particular resource.

  • Performs actions directly on the full User view before launching the designated workflow process.

Merges attributes from the ActiveSync event into the User view. 

Typical attributes on the Input Form include: 

  • accounts[*].*

  • waveset.*

  • accountInfo.*

  • activeSync.<LHS Attr Name>

  • activeSync.resourceName

  • activeSync.resourceId

  • activeSync.resource

  • display.session (session for Proxy Admin)

  • global.<LHS Attr Name> (if set globals flag is set on resource)

ActiveSync IAPIProcess

  • Processes generic events on a resource by creating a Process view.

  • Top-level fields in Process view are arbitrary inputs to the task.

  • Collects attributes related to launching the task under the global attribute.

  • Writes the workflow to retrieve inputs from under global rather than as top-level attributes.

Launches the specified task with ActiveSync poll attributes dumped into top-level workflow global attribute.

Workflow attributes assume the form:global.<LHS Attr Name>

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.

Table 3–4 Rule Types

Parameter  

Description  

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

Correlation Rule 

If no Identity Manager user’s resource info is determined to own the resource account, Identity Manager invokes the Correlation Rule 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). 

The rule returns one of the following pieces 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 items of type AttributeCondition or WSAttribute (AND-ed attribute-based search)

  • List of items of type String (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, you need a confirmation rule or resolve process rule 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. See Correlation and Confirmation Rules for more information.

Confirmation Rule 

Rule that is evaluated for all users that are 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 that can 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. See Correlation and Confirmation Rules for more information.

Delete Rule 

A rule that can expect a map of all values with keys of the form activeSync. or account. 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 that can 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. 

Resolve Process Rule 

Either the 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 is not selected.

This workflow could be a process that prompts an administrator for manual action. 

Create Unmatched Accounts 

If set to true, creates an account on the resource when no matching Identity Manager user is found. If false, Identity Manager does not create the account unless the process rule is set and the workflow it identifies determines that a new account is warranted. The default is true. 

Populate Global 

If set to true, populates the global namespace in addition to the activeSync namespace. The default value is false. 

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.

Note –

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:

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.

Note –

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.

Table 3–5 Attribute States

State  

Description  

A 

active 

T 

terminated 

L 

laid off 

S 

pending change 

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>