4 Extending the Functionality of the Connector

You can extend the functionality of the connector to address your specific business requirements.

This chapter discusses the following optional procedures:

• See Removing or Adding Attributes for Reconciliation if you want to modify the default field mappings between Oracle Identity Manager and the target system.

• See Modifying Field Lengths on the OIM User Form if you want to modify lengths of fields on the process form.

• Configuring the Connector for Multiple Installations of the Target System describes the procedure to configure the connector for multiple installations of the target system.

• See Configuring Validation of Data During Reconciliation if you want to configure validation of reconciled data.

• See Configuring Transformation of Data During User Reconciliation if you want configure transformation of reconciled data.

4.1 Removing or Adding Attributes for Reconciliation

The Lookup.SAP.HRMS.AttributeMapping lookup definition holds the default attribute mappings.

Table 1-5 lists the default attribute mappings stored in this lookup definition. If required, you can modify or add to this predefined set of attribute mappings. This section discusses the following procedures:

• Removing Attributes
• Adding Attribute Mapping

4.1.1 Removing Attributes

Before you begin connector operations, you can remove any attribute that is not marked as a mandatory attribute in Table 1-5.

Note:

If required, you can also reconfigure segment filtering to exclude the segment containing the attribute that you remove. See Configuring Segment Filtering for instructions.

To remove an attribute mapping:

1. Log in to the Design Console.
2. Expand Administration, and double-click Lookup Definition.
3. Search for and open the Lookup.SAP.HRMS.AttributeMapping lookup definition.
4. Click the row that you want to delete.
5. Click Delete.
6. Click the Save icon.

4.1.2 Adding Attribute Mapping

To add an attribute mapping:

Note:

The names of attributes are case-sensitive. The spelling and case (uppercase and lowercase) of an attribute must be the same in all the connector objects. See existing attribute mappings for examples.

1. Determine the Decode column entry for the attribute that you want to add from the target system.
2. Add the attribute mapping in the Lookup.SAP.HRMS.AttributeMapping lookup definition as follows:

   For Oracle Identity Manager prior to 11.1.2.1.x or later:

   1. Log in to the Design Console.
   2. Expand Administration, and double-click Lookup Definition.
   3. Search for and open the Lookup.SAP.HRMS.AttributeMapping lookup definition.
   4. Click Add.

      An empty row is added.

   5. In the Code Key column of the new row, add the name of the OIM User attribute.
   6. In the Decode column of the new row, add the entry that you determine for the target system attribute by performing Step 1.

      The Decode column entry for an attribute is in the following format:

      SEGMENT_NAME;SUB_TYPE;SAP_ATTRIBUTE_NAME;START_POSITION;END_POSITION;[Text|Date]

      Note:

      Append Date at the end of the Decode value if the attribute holds date values. For all other data types, append Text at the end of the Decode value.
   7. Click the Save icon.

   For Oracle Identity Manager 11.1.2.1.0 or later:

   1. Log in to Oracle Identity System Administration.
   2. In the left pane, under System Configuration, click Lookups.
   3. Search for and open the Lookup.SAP.HRMS.AttributeMapping lookup definition.
   4. Click Edit Lookup Type and then Action Create Lookup Type.

      A row is added.

   5. In the Code Key column of the new row, add the name of the OIM User attribute.
3. Create a UDF for the field.
4. Add the new attribute to the list of reconciliation fields in the resource object as follows:
   1. Expand Resource Management, and double-click Resource Objects.
   2. Search for and open the SAP HRMS resource object.
   3. On the Object Reconciliation tab, click Add Field.
   4. Enter the details of the field.

      For example, enter the new attribute name in the Field Name field and select String from the Field Type list.

      Later in this procedure, you will enter the field name as the Code value of the entry that you create in the lookup definition for reconciliation.

   5. Click the Save icon. The following screenshot shows the new reconciliation field added to the resource object:

      Figure 4-1 New reconciliation field added to the resource object

      
      Description of "Figure 4-1 New reconciliation field added to the resource object"
   6. If you are using Oracle Identity Manager release 11.1.x, then click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
5. Create a reconciliation field mapping for the new attribute in the process definition as follows:
   1. Expand Process Management, and double-click Process Definition.
   2. Search for and open the SAP HRMS Trusted User process definition.
   3. On the Reconciliation Field Mappings tab of the SAP HRMS Trusted User process definition, click Add Field Map.
   4. In the Field Name field, select the value for the field that you want to add.
   5. Double-click the Process Data Field field, and then select the UDF added in Step 3.
   6. Click the Save icon. The following screenshot shows the new reconciliation field mapped to a process data field in the process definition:

      Figure 4-2 New reconciliation field mapped to a process data field

      
      Description of "Figure 4-2 New reconciliation field mapped to a process data field"
6. On the target system, add the attribute to the segment filter that you create by performing the procedure described in Configuring Segment Filtering.

4.2 Modifying Field Lengths on the OIM User Form

You might want to modify the lengths of fields (attributes) on the OIM User form. For example, if you use the Japanese locale, then you might want to increase the lengths of OIM User 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 OIM User form.

To modify the length of a field on the OIM User form, do the following:

1. Log in to the Design Console.
2. Expand Administration, and double-click User Defined Field Definition.
3. Search for and open the Users form.
4. Modify the length of the required field.
5. Click the Save icon.

For Oracle Identity Manager 11.1.2.1.0 or later:

1. Log in to Oracle Identity System Administration.
2. Create and activate a sandbox.
3. In the left pane, under System Entities, click User.
4. Modify the length of the required field.
5. Click the Save icon.

4.3 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.HRMS.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 HR IT Resource	SAP HRMS Employee Type Lookup Recon (scheduled task) SAP HRMS Manager Lookup Recon (scheduled task) SAP HRMS User Recon (scheduled task) SAP HRMS Listener (scheduled task)	Create a copy of the IT resource.
Resource object	SAP HRMS Resource Object	SAP HRMS Update Manager (scheduled task) SAP HRMS User Recon (scheduled task) SAP HRMS Listener (scheduled task)	Create copies of the resource object only if there are differences in attributes between the various installations of the target system and if the same user ID exists in different target systems.
Process Definition	SAP HRMS Trusted User	NA	Create copies of this process definition only if there are differences in attributes between the various installations of the target system and if the same user ID exists in different target systems.
Attribute mapping lookup definition	Lookup.SAP.HRMS.AttributeMapping	NA	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.
Configuration lookup definition	Lookup.SAP.HRMS.Configuration	SAP HRMS Update Manager (scheduled task) SAP HRMS Employee Type Lookup Recon (scheduled task) SAP HRMS User Recon (scheduled task) SAP HRMS Manager Lookup Recon (scheduled task) SAP HRMS Listener (scheduled task)	Create copies of this lookup definition only if there are differences in attributes between the two 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 HRMS 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 Configuring Validation of Data During Reconciliation

You can configure validation of reconciled 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 (#).

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

.

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)
            * 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 in the following directory:

   For Oracle Identity Manager release 11.1.x:

   Oracle Identity Manager database

   Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

   Note:

   Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

   For Microsoft Windows:

   OIM_HOME/server/bin/UploadJars.bat

   For UNIX:

   OIM_HOME/server/bin/UploadJars.sh

   When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 1 as the value of the JAR type.

   Note:

   See Download JAR Utility of Oracle Fusion Middleware Deveoping and Customizing Applications for Oracle Identity Manager for detailed information about the Upload JARs utility
4. If you created the Java class for validating a user attribute for reconciliation, then:
   1. Log in to the Design Console.
   2. Search for and open the Lookup.SAP.HRMS.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.HRMS.Configuration lookup definition.
   6. Set the value of the Use Validation For Recon entry to yes.
   7. Save the changes to the lookup definition.

4.5 Configuring Transformation of Data During User Reconciliation

You can configure transformation of reconciled 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.

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").
          * 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 in the following directory:

   For Oracle Identity Manager release 11.1.x:

   Oracle Identity Manager database

   Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

   Note:

   Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

   For Microsoft Windows:

   OIM_HOME/server/bin/UploadJars.bat

   For UNIX:

   OIM_HOME/server/bin/UploadJars.sh

   When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 1 as the value of the JAR type.

   See Also:

   See Download JAR Utility of Oracle Fusion Middleware Deveoping and Customizing Applications for Oracle Identity Manager for detailed information about the Upload JARs utility
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.HRMS.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.HRMS.Configuration lookup definition.
   6. Set the value of the Use Transformation For Recon entry to yes.
   7. Save the changes to the lookup definition.