Using Forms (Sun Identity Manager Deployment Guide)

Sun Identity Manager Deployment Guide

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:

Active Sync fields are filled in with attribute and resource information. Use the activeSync namespace to retrieve and set attributes on the resource.
The resource form is expanded and derived. During this expansion, all user view attributes are available.
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:

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.

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>