7 Using Prepopulate Adapters

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

• "Overview"

• "Attaching Prepopulate Adapters to Form Fields"

• "Removing Prepopulate Adapters from Form Fields"

7.1 Overview

Sometimes, a user-created form contains fields that can 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. When 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 prepopulate adapter can appear automatically or manually entering it. Oracle Identity Manager displays this information automatically when the Auto-prepopulate check box is selected for a provisioning process. When this check box is cleared, an Oracle Identity Manager user must manually generate the displaying of the data that is generated by the prepopulate adapter. To do this, click the prepopulate button on the form section of the Direct Provisioning wizard in the Web client, while provisioning the form to a user.

You can repeatedly use a prepopulate adapter for different form fields. In addition, you can designate multiple prepopulate adapters to be associated with a particular field. As a result, Oracle Identity Manager must know which prepopulate adapter it must select for the form field. This occurs by using the prepopulate rules.

prepopulate rules are criteria. These rules enable Oracle Identity Manager to select one prepopulate adapter, which is associated with a form field, when this prepopulate adapter is assigned to the field.

Each prepopulate adapter has a prepopulate 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 prepopulate 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.

7.2 Attaching Prepopulate Adapters to Form Fields

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

1. Select the field to which a prepopulate adapter will be attached.

2. Select the rule that will determine if the adapter will be used to populate the designated field with information.

3. Select the adapter that will be associated with the designated field.

4. Set the priority number of the selected rule.

5. Map the adapter variables of the prepopulate adapter to their proper locations.

   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.

6. Open the Form Designer form.

7. Query for the form to which you want to attach a prepopulate adapter (for example, Solaris).

8. Click the prepopulate 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.

9. Click Add.

   The prepopulate Adapters dialog box is displayed.

   The following table lists and describes the fields of the Prepopulate 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 field, 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.

   
   

10. From the Field Name combo box, select the form field, such as User ID, to which the prepopulate adapter will be attached.

11. 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).

12. 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 10, for example, Display Lowercase Letters for User ID.

13. In the Order field, enter the priority number of the rule you selected in Step 11, for example, 2.

14. On the prepopulate Adapters window toolbar, click Save.

15. 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 can be mapped to their proper locations. Otherwise, the adapter will not work.

16. Set the mappings for each variable that appears in the Adapter Variables region of the prepopulate 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 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 grayed out.
    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.

    
    

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

    Note:

    For more information about which mappings to select, refer to the "Adapter Mapping Information" section in Oracle Identity Manager Reference.

18. On the Map Adapter Variable window toolbar, click Save. Then, click Close.

    The Map Adapter Variables window disappears. The prepopulate 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).

19. On the prepopulate Adapters window toolbar, click Close.

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

After 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 prepopulate rule, which has the highest priority, is valid. If so, then Oracle Identity Manager will assign the associated prepopulate adapter to the designated field (User ID), and execute it. At this point, one of the following actions occur:

• If the Auto-prepopulate check box is selected for the provisioning process, Oracle Identity Manager will display the data that is generated by the prepopulate adapter automatically.

• If the Auto-prepopulate check box is cleared, an Oracle Identity Manager user must manually trigger the displaying of the data that is generated by the prepopulate adapter. To do this, the administrator must click the prepopulate 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 prepopulate adapter to a form field, and assign a prepopulate 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.

7.3 Removing Prepopulate 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.

Note:

Before removing the prepopulate adapter from a form field, you must create a new version of the form.

To remove a prepopulate adapter from a form field:

1. Select the prepopulate adapter that you want to remove.

2. Click Delete. The prepopulate adapter is removed from the form field. It cannot be triggered when the form is launched.

3. After removing the adapter, you must activate the form.