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 Oracle Waveset Integrated Development Environment. For more details about the Active Sync wizard, see Business Administrator's Guide.
This section describes:
Overview of the basic steps of adapter processing
Active Sync variable context
Using rules
Using forms
Launching workflow processes
All Active Sync-enabled adapters follow the following basic steps when listening or polling for changes to the resource defined in Waveset. When the adapter detects that a resource has changed, the Active Sync-enabled adapter:
Extracts the changed information from the resource.
Determines which Waveset object is affected.
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.
Submits the IAPI object to the ActiveSync Manager.
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 Waveset system uses to update the identity. Typically, a workflow also handles errors within Waveset, often ending up as an Approval for a managing administrator.
The following table provides information about the common Waveset processes or tasks related to the Active Sync category.
When the Active Sync-enabled adapter detects a change to an account on a resource, it either maps the incoming attributes to an Waveset user, or creates an Waveset 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
If Waveset cannot find a match with an existing Waveset 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 Waveset, and creates the user in Waveset.
<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> |
Active Sync-enabled adapters typically use two types of forms during processing: a input 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 input 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 Waveset user when a deletion is detected on the resource.
Place only resource-specific logic in the input form and include common logic in the user form, possibly enabled when the feedop field is not null. If the input form is set to none, all of the Active Sync attributes (except accountId) are named global and will propagate automatically.
The input 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.
Input 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 Waveset 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.
<Field name=’IAPI.cancel’> <Disable> <neq> <ref>activeSync.lastName</ref> <s>Doe</s> </neq> </Disable> <expression> <s>true</s> </expression> </Field> |
Input forms include logic for handling the cases of new and existing users, as well as logic for disabling or deleting the Waveset user when a deletion has been detected.
The user form is used for editing from the Waveset 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.
You set a proxy administrator for an adapter through the ProxyAdministrator attribute, which you can set to any Waveset 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.
Best practice suggests keeping common changes, such as deriving a fullname from the first and last name, in the user form. The input 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> |
To cancel the processing of a user, set IAPI.cancel to true in the input 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 input 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> |
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.
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 Waveset 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.
<?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> |