7 Using Prepopulate Adapters

This chapter describes the prepopulate adapters. It contains the following tasks:

"Overview"
"Attaching Pre-Populate Adapters to Form Fields"
"Removing Pre-Populate Adapters from Form Fields"

Overview

Sometimes, a user-created form contains two types of fields: fields that need to be populated by Oracle Identity Manager; and fields, into which an Oracle Identity Manager user must enter data. When the information that the user types into a field is contingent upon the data that appears in a system-generated field, Oracle Identity Manager must first populate this field. Then, once the form is displayed, an Oracle Identity Manager user can view the system-generated data, and, as a result, enter information into the appropriate fields.

For this to happen, you must create a specific type of rule generator. Then, by attaching it to the field that is designated to be system-generated, Oracle Identity Manager will automatically populate this field with the appropriate information, without saving this information to the Oracle Identity Manager database.

This type of rule generator is known as a prepopulate adapter. The data, which is generated by a pre-populate adapter, can appear automatically or manually entering it. Oracle Identity Manager displays this information automatically when the Auto-Pre-populate check box is checked for a provisioning process. When this check box is unchecked, an Oracle Identity Manager user must manually generate the displaying of the data that is generated by the prepopulate adapter. To do this, the administrator must click the Pre-Populate button on the form section of the Direct Provisioning wizard in the Web client, while provisioning the form to a user.

For efficiency purposes, a pre-populate adapter can be used repeatedly for different form fields. In addition, multiple pre-populate adapters can be designated to be associated with a particular field. As a result, Oracle Identity Manager must know which pre-populate adapter it needs to select for the form field. This occurs using the prepopulate rules.

Prepopulate rules are criteria. These standards enable Oracle Identity Manager to select one pre-populate adapter, which is associated with a form field, once this pre-populate adapter is assigned to the field.

Each pre-populate adapter has a pre-populate rule associated with it. In addition, every rule has a priority number, which indicates the order in which Oracle Identity Manager will trigger it.

For this example, Oracle Identity Manager will trigger the Rule for Uppercase User ID rule first (because it has the highest priority). If the condition of this rule is TRUE, then it is successful. As a result, Oracle Identity Manager will attach the related pre-populate adapter (the Display Uppercase Letters for User ID adapter) to the User ID field.

On the other hand, when the condition of a rule is FALSE, then the rule has failed. Oracle Identity Manager will then trigger the rule with the next highest priority. If this rule is successful, then Oracle Identity Manager will attach the associated adapter to the designated field.

So, in this example, if the Rule for Uppercase User ID rule fails, Oracle Identity Manager will trigger the Rule for Lowercase User ID rule. If this rule is successful, Oracle Identity Manager will attach the related prepopulate adapter (the Display Lowercase Letters for User ID adapter) to the User ID field.

After assigning a rule to a prepopulate adapter, if this type of adapter contains adapter variables, then you must map these adapter variables to their proper locations. Otherwise, the adapter will not be functional.

Finally, when a prepopulate adapter, which has been associated with a field, is no longer valid, you must remove the adapter from the field.

The following sections will show you how to attach a prepopulate adapter to a form field, and remove a prepopulate adapter from a form field.

Attaching Pre-Populate Adapters to Form Fields

To attach a prepopulate adapter to a form field, perform the following steps:

Select the field to which a prepopulate adapter will be attached.
Select the rule that will determine if the adapter will be used to populate the designated field with information.
Select the adapter that will be associated with the designated field.
Set the priority number of the selected rule.
Map the adapter variables of the prepopulate adapter to their proper locations.

The following procedure demonstrates how to complete these steps, and, as a result, attach a prepopulate adapter to a form field.

Note:

To attach a prepopulate adapter to a form field, you must ensure the following:

The form is not in an active state. Otherwise, create a new form version.
After attaching the adapter, you must activate the form to be able to use it.

To Attach a Prepopulate Adapter to a Form Field

To attach a prepopulate adapter to a Form field, perform the following steps:

Open the Form Designer form.
Query for the form to which you want to attach a pre-populate adapter (for example, Solaris).
Click the Pre-Populate tab.

The prepopulate adapters, which have already been attached to the form you queried, appear within this tab.

Note:
If no adapters have been attached to a form field, then the Prepopulate tab will be empty.

Click Add.

The Pre-Populate Adapters dialog box is displayed.

The following table lists and describes the various regions of the Pre-Populate Adapters dialog box:

Name	Description
Field Name	This combo box contains a list of all of the form fields to which a prepopulate adapter can be attached.
Rule	From this Lookup field, select the rule that will determine if the associated adapter will be used to populate the designated form field with information.
Adapter	From this Lookup field, select the adapter that will be associated with the designated field.
Order	From this text box, set the priority number of the selected rule.
Adapter Status	This field displays the mapping status of the adapter variables. To learn more about the various mapping statuses for an adapter, refer to the "Attaching Process Task Adapters to Process Tasks".
Adapter Variables	This area displays the following: Mapped. The mapping statuses of the adapter's variables. "Y" indicates that an adapter variable has been mapped properly; "N" indicates that this variable has not been mapped correctly. Name. The names of the adapter variables. Mapped to. The form fields to which the variables are mapped If an adapter variable is not yet mapped, then the corresponding cell in this column will be empty.

From the Field Name combo box, select the form field to which the prepopulate adapter will be attached. (for example, User ID).
Double-click the Rule lookup field. From the Lookup dialog box that is displayed, select the rule that will determine if the associated adapter will be used to populate the designated form field with information (for example, Rule for Lowercase User ID).
Double-click the Adapter lookup field. From the Lookup dialog box that is displayed, choose the adapter that will be associated with the field you selected in Step 5 (for example, Display Lowercase Letters for User ID).
In the Order field, enter the priority number of the rule you selected in Step 6 (for example, 2).
From the Pre-Populate Adapters window's toolbar, click Save
Mapping Incomplete appears within the Adapter Status field. This signifies that the adapter you selected contains variables that have not been mapped correctly. These variables need to be mapped to their proper locations. Otherwise, the adapter will not work.

Set the mappings for each variable that appears in the Adapter Variables region of the Pre-Populate Adapters window. To do so, double-click the row header of the variable you want to map (for example, UserID).

The Map Adapter Variables window is displayed.

The following table describes the various fields of the Map Adapter Variables window:

Field Name	Description
Variable Name	This field displays the name of the adapter variable for which you are setting a mapping (for example, UserID).
Data Type	This field shows the data type of the adapter variable (for example, String is the data type for the UserID adapter variable).
Map To	This field contains the types of mappings that you can set for the adapter variable (for example, Process Data). When you map the adapter variable to a location or a contact, Oracle Identity Manager enables the adjacent combo box. From this combo box, select the specific type of location or contact to which you are mapping the adapter variable. If you are not mapping the adapter variable to a location or contact, this combo box is disabled.
Qualifier	This field contains the qualifiers for the mapping you selected in the Map to combo box (for example, User ID).
IT Asset Type	This field enables you to select a specific IT Resource (for example, Solaris) when you map an adapter variable to an IT Resource, and this variable's data type is String. If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, this field does not appear.
IT Asset Property	This field enables you to select a specific field that will receive the results of the mapping (for example, User Name), when you map an adapter variable to an IT Resource, and this variable's data type is String. If you are not mapping the adapter variable to an IT Resource, or the variable's data type is not String, then this field does not appear. Important: The IT Asset Type and IT Asset Property fields are included within this window for backward compatibility. The preferred way is to create an adapter variable with a data type of IT Resource, in which case these fields will not appear.
Literal Value	When you map the adapter variable to a literal, use this field to specify the specific literal value. If you are not mapping the adapter variable to a literal, this field does not appear.

Complete the Map To, Qualifier, IT Asset Type, IT Asset Property, and Literal Value fields.

Note:
For more information on which mappings to select, refer to the "Adapter Variable Mapping Information".
From the Map Adapter Variable's toolbar, click Save. Then, click Close.

The Map Adapter Variables window disappears. The Pre-Populate Adapters window is active again.

The text in the Adapter Status field changes from Mapping Incomplete to Ready. In addition, the mapping statuses for the adapter's variables change from No (N) to Yes (Y).
From the Pre-Populate Adapters window's toolbar, click Close.

The Pre-Populate Adapters window disappears, and the Form Designer form is active again. The pre-populate adapter, which you attached to the User ID form field (Display Lowercase Letters for User ID), appears in the Pre-Populate tab of the Results of 1Q Sales 2003 form.

Once a process, which references this form, is provisioned to a target user or organization, the form will appear. Oracle Identity Manager will then check to see if the pre-populate rule, which has the highest priority, is valid. If so, Oracle Identity Manager will assign the associated pre-populate adapter to the designated field (User ID), and execute it. At this point, one of the following actions occur:

If the Auto-Pre-populate check box was selected for the provisioning process, Oracle Identity Manager will display the data that is generated by the pre-populate adapter automatically.
If the Auto-Pre-populate check box was unchecked, an Oracle Identity Manager user must manually trigger the displaying of the data that is generated by the pre-populate adapter. To do this, the administrator must click the Pre-Populate button on the form section of the direct provisioning wizard in the Web client, while provisioning the form to a user.

Tip:

Once you allocate a pre-populate adapter to a form field, and assign a pre-populate rule to the adapter, a quick way to see the association among the adapter, the form field, and the rule is by accessing the Usage Lookup tab of the Adapter Factory form.

Removing Pre-Populate Adapters from Form Fields

If a prepopulate adapter, which has been associated with a form field, is no longer valid, then you must remove the adapter from the field.

The following procedure will show you how to remove a pre-populate adapter from a form field.

Note:

Before removing the pre-populate adapter from a form field, you must create a new version of the form before removing the adapter.

To Remove a Prepopulate Adapter from a Form Field

To remove a prepopulate adapter from a Form Field, perform the following steps:

Highlight the prepopulate adapter that you want to remove.
Click Delete. The pre-populate adapter is removed from the form field. It cannot be triggered when the form is launched.
After removing the adapter, you must activate the form.