4 Extending the Functionality of the Connector

This chapter discusses the following optional procedures:

• Section 4.1, "Configuring Validation of Data During Reconciliation and Provisioning"

• Section 4.2, "Configuring Transformation of Data During User Reconciliation"

• Section 4.3, "Modifying Field Lengths on the Process Form"

• Section 4.4, "Configuring the Connector for Multiple Installations of the Target System"

4.1 Configuring Validation of Data During Reconciliation and Provisioning

You can configure validation of reconciled and provisioned single-valued data according to your requirements. For example, you can validate data fetched from the First Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.

For data that fails the validation check, the following message is displayed or recorded in the log file:

Value returned for field FIELD_NAME is false.

Note: This feature cannot be applied to the Locked/Unlocked status attribute of the target system.

To configure validation of data:

1. Write code that implements the required validation logic in a Java class.

   This validation class must implement the oracle.iam.connectors.common.validate.Validator interface and the validate method.

   
   

   See Also: The Javadocs shipped with the connector for more information about this interface

   
   

   The following sample validation class checks if the value in the First Name attribute contains the number sign (#):

   public boolean validate(HashMap hmUserDetails,
                 HashMap hmEntitlementDetails, String field) {
               /*
            * You must write code to validate attributes. Parent
            * data values can be fetched by using hmUserDetails.get(field)
            * For child data values, loop through the
            * ArrayList/Vector fetched by hmEntitlementDetails.get("Child Table")
            * Depending on the outcome of the validation operation, 
            * the code must return true or false.
            */
            /*
            * In this sample code, the value "false" is returned if the field
            * contains the number sign (#). Otherwise, the value "true" is
            * returned.
            */
               boolean valid=true;
               String sFirstName=(String) hmUserDetails.get(field);
               for(int i=0;i<sFirstName.length();i++){
                 if (sFirstName.charAt(i) == '#'){
                       valid=false; 
                       break;
                 } 
               }
               return valid;
         }
   

2. Create a JAR file to hold the Java class.

3. Copy the JAR file into the JavaTasks or ScheduleTask directory.

4. If you created the Java class for validating a process form field for reconciliation, then:

   1. Log in to the Design Console.

   2. Search for and open the Lookup.SAP.UME.ReconValidation lookup definition.

   3. In the Code Key, enter the resource object field name. In the Decode, enter the class name.

   4. Save the changes to the lookup definition.

   5. Search for and open the Lookup.SAP.UME.Configuration lookup definition.

   6. Set the value of the Use Validation For Recon entry to yes.

   7. Save the changes to the lookup definition.

5. If you created the Java class for validating a process form field for provisioning, then:

   1. Log in to the Design Console.

   2. Search for and open the Lookup.SAP.UME.ProvValidation lookup definition.

   3. In the Code Key column, enter the process form field name. In the Decode column, enter the class name.

   4. Save the changes to the lookup definition.

   5. Search for and open the Lookup.SAP.UME.Configuration lookup definition.

   6. Set the value of the Use Validation For Prov entry to yes.

   7. Save the changes to the lookup definition.

4.2 Configuring Transformation of Data During User Reconciliation

You can configure transformation of reconciled single-valued user data according to your requirements. For example, you can use First Name and Last Name values to create a value for the Full Name field in Oracle Identity Manager.

Note: This feature cannot be applied to the Locked/Unlocked status attribute of the target system.

To configure transformation of single-valued user data fetched during reconciliation:

1. Write code that implements the required transformation logic in a Java class.

   This transformation class must implement the oracle.iam.connectors.common.transform.Transformation interface and the transform method.

   
   

   See Also: The Javadocs shipped with the connector for more information about this interface

   
   

   The following sample transformation class creates a value for the Full Name attribute by using values fetched from the First Name and Last Name attributes of the target system:

   package oracle.iam.connectors.common.transform;
    
   import java.util.HashMap;
    
   public class TransformAttribute implements Transformation {
    
         /*
         Description:Abstract method for transforming the attributes
         
         param hmUserDetails<String,Object> 
    
         HashMap containing parent data details
    
         param hmEntitlementDetails <String,Object> 
    
         HashMap containing child data details 
         
         */
         public Object transform(HashMap hmUserDetails, HashMap       hmEntitlementDetails,String sField) {
         /*
          * You must write code to transform the attributes.
          Parent data attribute values can be fetched by 
          using hmUserDetails.get("Field Name").
          *To fetch child data values, loop through the
          * ArrayList/Vector fetched by hmEntitlementDetails.get("Child          Table")
          * Return the transformed attribute.
          */
         String sFirstName= (String)hmUserDetails.get("First Name");
         String sLastName= (String)hmUserDetails.get("Last Name");
         String sFullName=sFirstName+"."+sLastName;
         return sFullName;
         }
   }
   

2. Create a JAR file to hold the Java class.

3. Copy the JAR file into the JavaTasks or ScheduleTask directory.

4. If you created the Java class for transforming a process form field for reconciliation, then:

   1. Log in to the Design Console.

   2. Search for and open the Lookup.SAP.UME.ReconTransformation lookup definition.

   3. In the Code Key column, enter the resource object field name. In the Decode column, enter the class name.

   4. Save the changes to the lookup definition.

   5. Search for and open the Lookup.SAP.UME.Configuration lookup definition.

   6. Set the value of the Use Transformation For Recon entry to yes.

   7. Save the changes to the lookup definition.

4.3 Modifying Field Lengths on the Process Form

You might want to modify the lengths of fields (attributes) on the process form. For example, if you use the Japanese locale, then you might want to increase the lengths of process form fields to accommodate multibyte data from the target system.

Note: On mySAP ERP 2005 (ECC 6.0 running on WAS 7.0), the default length of the password field is 40 characters. The default length of the password field on the process form is 8 characters. If you are using mySAP ERP 2005, then you must increase the length of the password field on the process form.

If you want to modify the length of a field on the process form, then:

1. Log in to the Design Console.

2. Expand Development Tools, and double-click Form Designer.

3. Search for and open the UD_UME process form.

4. Click Create New Version.

5. Enter a label for the new version, click the Save icon, and then close the dialog box.

6. From the Current Version list, select the version that you create.

7. Modify the length of the required field.

8. Click the Save icon.

9. Click Make Version Active.

4.4 Configuring the Connector for Multiple Installations of the Target System

You might want to configure the connector for multiple installations of the target system. The following example illustrates this requirement:

The London and New York offices of Example Multinational Inc. have their own installations of the target system. The company has recently installed Oracle Identity Manager, and they want to configure Oracle Identity Manager to link all the installations of the target system.

To meet the requirement posed by such a scenario, you can create copies of connector objects, such as the IT resource and resource object.

The decision to create a copy of a connector object might be based on a requirement. For example, an IT resource can hold connection information for one target system installation. Therefore, it is mandatory to create a copy of the IT resource for each target system installation.

With some other connector objects, you do not need to create copies at all. For example, a single attribute-mapping lookup definition can be used for all installations of the target system.

All connector objects are linked. For example, a scheduled task holds the name of the IT resource. Similarly, the IT resource holds the name of the configuration lookup definition, Lookup.SAP.UME.Configuration. If you create a copy of an object, then you must specify the name of the copy in associated connector objects. Table 4-1 lists associations between connector objects whose copies can be created and the other objects that reference these objects. When you create a copy of a connector object, use this information to change the associations of that object with other objects.

Note: On a particular Oracle Identity Manager installation, if you create a copy of a connector object, then you must set a unique name for it.

Table 4-1 Connector Objects and Their Associations

Connector Object	Name	Referenced By	Comments on Creating a Copy
IT resource	SAP UME IT Resource	SAP UME User Recon (scheduled task) SAP UME Delete Recon (scheduled task) SAP UME Lookup Recon (scheduled task)	Create a copy of the IT resource. See Section 2.3.9, "Configuring the IT Resource" for more information.
Resource object	SAP UME Resource Object	SAP UME User Recon (scheduled task) SAP UME Delete Recon (scheduled task) SAP UME Lookup Recon (scheduled task)	It is optional to create a copy of the resource object. If you are reconciling the same set of attributes from all installations of the target system, then you need not create a copy of the resource object. In other words, create copies of the resource object only if there are differences in attributes between the various installations of the target system. See Section 3.5.3, "Reconciliation Scheduled Tasks" for more information.
Process definition	SAP UME Process Form	NA	Create copies of this process definition only if there are difference in attributes between the installations of the target system.
Attribute Mapping Lookup Definition	Lookup.SAP.CUP.ProvAttrMap Lookup.SAP.CUP.ProvisionRoleAttrMap	NA	Create copies of these lookup definitions only if you want to map a different set of attributes for the various installations of the target system. See the following sections for more information: Section 1.6, "Connector Objects Used During Reconciliation" Section 1.7, "Connector Objects Used During Provisioning"
Process form	UD_UME	NA	It is optional to create a copy of a process form. If you are provisioning different sets of attributes, then you need to create a copy of this connector object.
Configuration lookup definition	Lookup.SAP.UME.Configuration	SAP UME IT Resource (IT resource)	Create copies of this lookup definition only if you want to use a different set of configuration values for the various installations of the target system. See Section 2.3.1, "Setting Values in the Lookup.SAP.UME.Configuration Lookup Definition" for more information.
Lookup mappings lookup definitions	Lookup.SAP.UME.LookupMappings	SAP UME Lookup Recon (scheduled task)	Create copies of these lookup definition only if you want to use a different set of lookup mappings for the various installations of the target system.

When you configure reconciliation:

To reconcile data from a particular target system installation, specify the name of the IT resource for that target system installation as the value of the scheduled task attribute that holds the IT resource name. For example, you enter the name of the IT resource as the value of the IT resource attribute of the SAP UME User Recon scheduled task.

When you perform provisioning operations:

When you use the Administrative and User Console to perform provisioning, you can specify the IT resource corresponding to the target system installation to which you want to provision the user.

4.4.1 Enabling the Dependent Lookup Fields Feature

When you perform a provisioning operation, lookup fields on the Administrative and User Console allow you to select values from lists. Some of these lookup fields are populated with values copied from the target system.

In earlier releases of the connector, if you had multiple installations of the target system, then entries in the lookup field were linked with the target system installation from which the entries were copied. This allowed you to select lookup field values that were specific to the target system installation on which the provisioning operation was to be performed.

For release 9.1.2 of the connector, the Dependent Lookup Fields feature is disabled by default. You can enable this feature after you deploy the Oracle Identity Manager release 9.1.0.2 bundle patch that addresses Bug 9181280.

Note: The bundle patch that addressed Bug 9181280 had not been released at the time of release of this connector.

To enable the Dependent Lookup Fields feature after you deploy the bundle patch that addresses Bug 9181280, you must make changes in the forms listed in Table 4-2. This table lists the forms, the lookup fields on the forms, and the lookup query that you must use for each lookup field. The procedure is described after the table.

Table 4-2 SQL Queries for Lookup Fields

Form	Lookup Field	Oracle Database Query for the Lookup Field	Microsoft SQL Server Query for the Lookup Field
UD_UMEGRP	Group Name	select lkv_encoded,lkv_decoded from lkv lkv,lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.SAP.UME.Groups' and instr(lkv_encoded,concat('$Form data.UD_UME_ITRESOURCE$','~'))>0	select lkv_encoded,lkv_decoded from lkv lkv,lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.SAP.UME.Groups' and CHARINDEX('$Form data.UD_UME_ITRESOURCE$' + '~' ,lkv_encoded)>0
UD_UMERL	Role Name	select lkv_encoded,lkv_decoded from lkv lkv,lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.SAP.UME.Roles' and instr(lkv_encoded,concat('$Form data.UD_UME_ITRESOURCE$','~'))>0	select lkv_encoded,lkv_decoded from lkv lkv,lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.SAP.UME.Roles' and CHARINDEX('$Form data.UD_UME_ITRESOURCE$' + '~' ,lkv_encoded)>0

To enable lookup fields on each form:

Note: You must enable lookup fields in the order given in Table 4-2.

1. On the Design Console, expand Development Tools and double-click Form Designer.

2. Search for and open the form. For example, open the UD_UME form.

3. Click Create New Version, enter a new version number, and then save the version.

4. From the Current Version list, select the version that you created.

5. Open the Properties tab, and expand Components.

6. Add properties for each lookup field on the form as follows:

   1. Select the Lookup Code property, and then click Delete Property.

   2. Select the first lookup field on the form, and then click Add Property. For example, select Profile System Name on the UD_UME form.

   3. In the Add Property dialog box:

      From the Property Name list, select Lookup Column Name.

      In the Property Value field, enter lkv_encoded.

      Click the Save icon, and then close the dialog box.

   4. Select the lookup field, and then click Add Property.

   5. In the Add Property dialog box:

      From the Property Name list, select Column Names.

      In the Property Value field, enter lkv_encoded.

      Click the Save icon, and then close the dialog box.

   6. Select the lookup field, and then click Add Property.

   7. In the Add Property dialog box:

      From the Property Name list, select Column Widths.

      In the Property Value field, enter 234.

   8. Select the lookup field, and then click Add Property.

   9. In the Add Property dialog box:

      From the Property Name list, select Column Captions.

      In the Property Value field, enter lkv_decoded.

      Click the Save icon, and then close the dialog box.

   10. Select the lookup field, and then click Add Property.

   11. In the Add Property dialog box:

       From the Property Name list, select Lookup Query.

       In the Property Value field, enter the query given in Table 4-2.

       Click the Save icon, and then close the dialog box.

7. Repeat Step 6 for each lookup field on the form.

8. Click the Save icon to save the changes to the form.

9. Click Make Version Active.