4 Extending the Functionality of the Connector

This chapter discusses the following optional procedures:

Note:

From Oracle Identity Manager Release 11.1.2 onward, lookup queries are not supported. See Managing Lookups in Oracle Fusion Middleware Administering Oracle Identity Manager for information about managing lookups by using the Form Designer in the Oracle Identity Manager System Administration console.

• Adding New Attributes for Full Reconciliation

• Adding New Attributes for Incremental Reconciliation

• Modifying Field Lengths on the OIM User Form

• Configuring Validation of Data During Reconciliation

• Configuring Transformation of Data During Reconciliation

• Setting Up the Lookup.PSFT.HRMS.CustomQuery Lookup Definition

• Setting Up the Lookup.PSFT.HRMS.WorkForceSync.EmpStatus Lookup Definition

• Configuring the Connector for Multiple Installations of the Target System

4.1 Adding New Attributes for Full Reconciliation

This section contains the following topics:

• About New Attributes for Full Reconciliation

• Adding New Attributes for Full Reconciliation

4.1.1 About New Attributes for Full Reconciliation

You can modify the default field mappings between Oracle Identity Manager and the PeopleSoft target system. For example, the Lookup.PSFT.HRMS.PersonBasicSync.AttributeMapping lookup definition for the PERSON_BASIC_FULLSYNC message holds the default attribute mappings. If required, you can add to this predefined set of attribute mappings.

By default, the Employee ID field in the target system is mapped to the User Login field in Oracle Identity Manager. Suppose you change this mapping, for example, Employee ID is mapped to PS_EMPLID. To match profiles based on this field, you must also change the reconciliation rule before creating a new reconciliation profile. For the described example, see the following screenshot of the sample reconciliation:

4.1.2 Adding New Attributes for Full Reconciliation

To add a new attribute for full reconciliation:

Note:

If you do not want to add new attributes for full reconciliation, then you need not perform this procedure.

1. In Oracle Identity Manager Design Console, make the required changes as follows:

   See Also:

   Adding Target System Attributes for Target Reconciliation in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for detailed instructions on performing the following steps

   1. Create a new user-defined field. For the procedure to create a user-defined field, see step 5 of Adding New Attributes for Incremental Reconciliation.

   2. Add a reconciliation field corresponding to the new attribute in the Peoplesoft HRMS resource object. For example, you can add the Employee ID reconciliation field.

      

   3. Modify the PeopleSoft HRMS Person process definition to include the mapping between the newly added field and the corresponding reconciliation field. For the example described earlier, the mapping is as follows:

      Employee ID = Employee ID
      

   4. On the Object Reconciliation tab, click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.

2. Add the new attribute in the message-specific attribute mapping lookup definition. For example, the Lookup.PSFT.HRMS.PersonBasicSync.AttributeMapping lookup definition for the PERSON_BASIC_FULLSYNC message.

   The following is the format of the values stored in this table:

   Code Key	Decode
   AttributeName	NODE~PARENT NODE~NODE TYPE=Value~EFFECTIVE DATED NODE~PRIMARY

   For example:

   Code Key: Empl ID

   Decode: EMPLID~PERSON

   In this example, Empl ID is the reconciliation field and its equivalent target system field is EMPLID.

   The mapping is shown in the following screenshot:

   

3. Add the new attribute in the Resource Object attribute reconciliation lookup definition. For example, the Lookup.PSFT.HRMS.PersonBasicSync.Recon lookup for the PERSON_BASIC_FULLSYNC message.

   The following is the format of the values stored in this table:

   Code Key	Decode
   RO Attribute	ATTRIBUTE FIELD~LOOKUP NAME

   For example:

   Code Key: Employee ID

   Decode: Empl ID

   The following screenshot displays the mapping:

   

   In this example, RO Attribute refers to the resource object attribute name added in the preceding steps. The decode value is the code key value in the message-specific attribute mapping lookup definition.

4. Add the new attribute in the Custom Query lookup definition. See Setting Up the Lookup.PSFT.HRMS.CustomQuery Lookup Definition for more information.

4.2 Adding New Attributes for Incremental Reconciliation

Standard incremental reconciliation involves the reconciliation of predefined attributes. If required, you can add new attributes to the list of attributes that are reconciled.

Note:

If you do not want to add new attributes for incremental reconciliation, then you can skip this section.

To add a new attribute for incremental reconciliation:

1. In Oracle Identity Manager Design Console, make the required changes as follows:

   See Also:

   Adding Target System Attributes for Target Reconciliation in Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed instructions on performing the following steps

   1. Create a new user-defined field. For the procedure to create a user-defined field, see step 5 in this procedure.

   2. Add a reconciliation field corresponding to the new attribute in the Peoplesoft HRMS resource object. For the example described earlier, you can add the Employee ID reconciliation field.

   3. Modify the PeopleSoft HRMS Person process definition to include the mapping between the newly added field and the corresponding reconciliation field. For the example described earlier, the mapping is as follows:

      Employee ID = Employee ID
      

   4. On the Object Reconciliation tab, click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.

2. Add the new attribute in the message-specific attribute mapping lookup definition, for example, the Lookup.PSFT.HRMS.PersonBasicSync.AttributeMapping lookup definition for the PERSON_BASIC_SYNC message.

   The following is the format of the values stored in this table:

   Code Key	Decode
   AttributeName	NODE~PARENT NODE~NODE TYPE=Value~EFFECTIVE DATED NODE~PRIMARY

   For example:

   Code Key: Empl ID

   Decode: EMPLID~PERSON

   In this example, Empl ID is the reconciliation field and its equivalent target system field is EMPLID.

3. Add the new attribute in the Resource Object attribute reconciliation lookup definition, for example the Lookup.PSFT.HRMS.PersonBasicSync.Recon lookup for the PERSON_BASIC_SYNC message.

   The following is the format of the values stored in this table:

   Code Key	Decode
   RO Attribute	ATTRIBUTE FIELD~LOOKUP NAME

   For example:

   Code Key: Employee ID

   Decode: Empl ID

   In this example, RO Attribute refers to the resource object attribute name added in the preceding steps. The Decode value is the Code Key value defined in the message-specific attribute mapping lookup definition.

4. Add the new attribute in the Custom Query lookup definition. See Setting Up the Lookup.PSFT.HRMS.CustomQuery Lookup Definition for more information.

5. To create a user-defined field (UDF) on Oracle Identity Manager:

   1. Log in to the Oracle Identity Management Administration Console.

   2. Click Advanced.

   3. On the Configuration tab, click User Configuration.

   4. From the Actions menu, select User Attributes.

   5. Click Create Attribute.

   6. Enter details of the attribute (UDF) that you want to create. From the Category list, select Custom Attributes.

   7. Set values for the attribute properties.

   8. Review the data that you have entered, and then save the attribute.

4.3 Modifying Field Lengths on the OIM User Form

You might want to modify the lengths of the 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.

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

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.

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 (#). In addition, you can validate data entered in the First Name field on the user form so that the number sign (#) is not sent to Oracle Identity Manager during reconciliation 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.

To configure validation of data:

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

   See Also:

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

   You must create a class with the following signature:

   public boolean validate(HashMap arg0, HashMap arg1, String arg2)

   In this signature code:

   • arg0 contains primary table field values

   • arg1 contains child table field values

   • arg2 is the field on which validation needs to be done

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

   package com.validate;
   import java.util.*;
   public class MyValidation {
   
   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;
           }
         } /* End */
   

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

3. Run the Oracle Identity Manager Upload JARs utility to post the JAR file created in Step 2 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.

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 message-specific configuration lookup definition.

      For example, locate the Lookup.PSFT.Message.WorkForceSync.Configuration lookup definition for the WORKFORCE_SYNC message. See Lookup.PSFT.Message.WorkForceSync.Configuration for information about this lookup definition. Check for the parameter Validation Lookup Definition in this lookup definition. The Decode value specifies the name of the validation lookup. In this example, the Decode value is Lookup.PSFT.HRMS.WorkForceSync.Validation.

   3. Search for and open the Lookup.PSFT.HRMS.WorkForceSync.Validation lookup definition.

   4. In the Code Key column, enter First Name. In the Decode column, enter com.validate.MyValidation.

      Here, the Code Key value specifies the column name of the field you want to validate. The Decode value is the complete package name of the Java class that has the validation logic.

   5. Save the changes to the lookup definition.

   6. Search for and open the message-specific configuration lookup definition, in this example, the Lookup.PSFT.Message.WorkForceSync.Configuration lookup definition.

   7. Set the value of the Use Validation entry to yes.

   8. Save the changes to the lookup definition.

5. Remove the PeopleSoftOIMListener.ear file from the application server.

6. Copy the validation JAR file created in Step 2 to the following directory:

   CONN_HOME/listener/deployable-archive/PeoplSoftOIMListener.ear/PeoplSoftOIMListener.war/WEB-INF/lib

7. Redeploy the PeopleSoftOIMListener.ear file on the application server. To do so, run the following command:

   ant redeploy
   

   See Deploying the PeopleSoft Listener for information about the deployment tool.

4.5 Configuring Transformation of Data During Reconciliation

You can configure the transformation of reconciled single-valued data according to your requirements. For example, you can use the Currency Code value to create a value for the Currency Code field in Oracle Identity Manager.

To configure the transformation of data:

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

   See Also:

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

   The following sample transformation class modifies a value for the Currency Code attribute by prefixing a dollar sign ($) in the Currency Code value received from the target system:

   package com.transform;
   import java.util.*;
   public class MyTransform {
   
         /*
         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.
          */
         System.out.println("sfield =" + sField);
         String sCurrencyCode= (String)hmUserDetails.get(sField);
         sCurrencyCode = "$"+sCurrencyCode;
         return sCurrencyCode;
         }
   } /* End */
   

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

3. Run the Oracle Identity Manager Upload JARs utility to post the JAR file created in Step 2 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.

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 message-specific configuration lookup definition, in this example, the Lookup.PSFT.Message.WorkForceSync.Configuration lookup definition for the WORKFORCE_SYNC message.

      See Lookup.PSFT.Message.WorkForceSync.Configuration for information about this lookup definition. Check for the parameter Transformation Lookup Definition in this lookup definition. The Decode value specifies the name of the transformation lookup. In this example, the Decode value is Lookup.PSFT.HRMS.WorkForceSync.Transformation.

   3. Search for and open the Lookup.PSFT.HRMS.WorkForceSync.Transformation lookup definition.

   4. In the Code Key column, enter Currency Code. In the Decode column, enter com.transform.MyTransform.

      Here, the Code Key value specifies the column name of the field you want to validate. The Decode value is the complete package name of the Java class that has the transformation logic.

   5. Save the changes to the lookup definition.

   6. Search for and open the message-specific configuration lookup definition, in this example, the Lookup.PSFT.Message.WorkForceSync.Configuration lookup definition.

   7. Set the value of the Use Transformation entry to yes.

   8. Save the changes to the lookup definition.

5. Remove the PeopleSoftOIMListener.ear file from the application server.

6. Copy the transformation JAR file created in Step 2 to the following directory:

   CONN_HOME/listener/deployable-archive/PeoplSoftOIMListener.ear/PeoplSoftOIMListener.war/WEB-INF/lib

7. Redeploy the PeopleSoftOIMListener.ear file on the application server. To do so, run the following command:

   ant redeploy
   

   See Deploying the PeopleSoft Listener for information about the deployment tool.

4.6 Setting Up the Lookup.PSFT.HRMS.CustomQuery Lookup Definition

You configure limited reconciliation by specifying a query condition as the value of the Custom Query attribute in the message-specific configuration lookup. See Lookup.PSFT.HRMS.CustomQuery for more information about this lookup definition.

You must ensure that the OIM User attribute to use in the query exists in the Lookup.PSFT.HRMS.CustomQuery lookup definition. You must add a row in this lookup definition whenever you add a UDF in the user form.

To add a new UDF to this lookup definition:

1. On the Design Console, expand Administration and then double-click Lookup Definition.
2. Search for and open the Lookup.PSFT.HRMS.CustomQuery lookup definition.
3. Click Add.

   Note:

   The Code Key value represents the resource object field name and the Decode value specifies the column name of the USR table.

4. In the Code Key and Decode columns, enter the values for the UDF.

   The following is the format of the values stored in this table:

   Code Key	Decode
   RO Attribute Name	Column name of the USR table

   If you have added a UDF Empl ID with column name as USR_UDF_EMPLOYEE_ID, then define the following entry in this lookup definition:

   Code Key: Empl ID

   Decode: USR_UDF_EMPLOYEE_ID

5. Click the Save icon.

4.7 Setting Up the Lookup.PSFT.HRMS.WorkForceSync.EmpStatus Lookup Definition

The Lookup.PSFT.HRMS.WorkForceSync.EmpStatus lookup definition maps the value retrieved from the ACTION node in the WORKFORCE_SYNC message XML with the status to be shown on Oracle Identity Manager for the employee. See Lookup.PSFT.HRMS.WorkForceSync.EmpStatus for more information about this lookup definition.

The following section describes how to add an action, for example Suspension in this lookup definition.

To add an action in the Lookup.PSFT.HRMS.WorkForceSync.EmpStats lookup definition:

1. Obtain the Code Key and the description for the action to be added from your PeopleSoft functional resource.

   The Code Key is usually a three-character string.

   The path to obtain the Action values and its description in PeopleSoft HRMS 9.0 is as follows:

   From the Main Menu, select Set Up HRMS, Product Related, Workforce Administration, and then Actions.

2. Log in to the Design Console of Oracle Identity Manager.
3. Expand Administration, and then double-click Lookup Definition.
4. Search for and open the Lookup.PSFT.HRMS.WorkForceSync.EmpStats lookup definition.
5. Click Add.

   Note:

   The following is the format of the values stored in this lookup definition:

   Code Key: ACTION value retrieved from the WORKFORCE_SYNC message XML

   Decode: Active or Disabled in Oracle Identity Manager

6. In the Code Key and Decode columns, enter the values for the following values:

   Code Key: SUS

   Decode: Disabled

   In this example, SUS is retrieved from the ACTION node of the WORKFORCE_SYNC message XML for the action suspension. The corresponding mapping for this action is defined as Disabled in Oracle Identity Manager.

   Note:

   You must define the mapping for all Actions to be performed on the target system in this lookup definition.

7. Click the Save icon.

4.8 Configuring the Connector for Multiple Installations of the Target System

This section contains the following topics:

• Connector Objects and Their Associations

• Creating Copies of the Connector Objects

4.8.1 Connector Objects and Their Associations

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 is 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.

Note:

A single listener is sufficient for multiple installations of the target system. You can configure the nodes to point to the same listener with different IT resource names.

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 common configuration lookup definition, which is Lookup.PSFT.HRMS.Configuration. If you create a copy of an object, then you must specify the name of the copy in other connector object. Table 4-1 lists association between connector objects whose copies can be created and the other objects that reference these objects. When you create a copy of an object, use this information to change the associations of that object with other objects.

Table 4-1 Connector Objects and Their Associations

Connector Object	Name	Referenced By	Description
IT Resource	PSFT HRMS	Scheduled Task: Peoplesoft HRMS Trusted Reconciliation Resource Object: Peoplesoft HRMS	You need to create a copy of IT Resource with a different name.
Resource Object	Peoplesoft HRMS	Message-specific configuration lookup definitions: Lookup.PSFT.Message.PersonBasicSync.Configuration Lookup. PSFT.Message.WorkForceSync.Configuration	It is optional to create a copy of a resource object. If you are reconciling the same set of attributes from the other target system, then you need not create a new resource object. Note: Create copies of this resource object only if there are differences in attributes between the two installations of the target system.
Common Configuration Lookup Definition	Lookup.PSFT.HRMS.Configuration	Message-specific configuration lookup definitions: Lookup.PSFT.Message.PersonBasicSync.Configuration Lookup. PSFT.Message.WorkForceSync.Configuration	It is optional to create a copy of the common configuration lookup definition. Note: Create copies of this lookup definition only if there are differences in attributes between the two installations of the target system.
Message-specific Configuration Lookup Definition	Lookup.PSFT.Message.PersonBasicSync.Configuration Lookup. PSFT.Message.WorkForceSync.Configuration	Attribute mapping lookup definitions: Lookup.PSFT.HRMS.PersonBasicSync.AttributeMapping Lookup.PSFT.HRMS.WorkForceSync.AttributeMapping	It is optional to create a copy of the message-specific lookup definitions. Note: Create copies of this lookup definition only if there are differences in attributes between the two installations of the target system.
Attribute Mapping Lookup Definition	Lookup.PSFT.HRMS.PersonBasicSync.AttributeMapping Lookup.PSFT.HRMS.WorkForceSync.AttributeMapping	NA	This lookup definition holds the information of the attributes reconciled from the XML message file from the target system. Note: Create copies of this lookup definition only if there are differences in attributes between the two installations of the target system.
Recon Map Lookup Definition	Lookup.PSFT.HRMS.PersonBasicSync.Recon Lookup.PSFT.HRMS.WorkForceSync.Recon	NA	This lookup definition maps the resource object field with the data reconciled from the message. Note: Create copies of this lookup definition only if there are differences in attributes between the two installations of the target system.

4.8.2 Creating Copies of the Connector Objects

To create copies of the connector objects:

Note:

See Cloning Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed information about the steps in this procedure.

1. Create a copy of the IT resource. See Configuring the IT Resource for information about this IT resource.
2. Create a copy of the Peoplesoft HRMS resource object.
3. Create copy of the PERSON_BASIC_SYNC and WORKFORCE_SYNC message-specific configuration lookup.
4. Create a copy of the Lookup.PSFT.HRMS.Configuration lookup definition. Add the new lookup to the Configuration Lookup parameter of the new IT resource created in Step 1. See Lookup.PSFT.HRMS.Configuration for information about this lookup definition.
5. Create a copy of the message-specific attribute mapping and Recon lookup definition, for example, the Lookup.PSFT.HRMS.PersonBasicSync.AttributeMapping and the Lookup.PSFT.HRMS.PersonBasicSync.Recon for PERSON_BASIC_SYNC message. Similarly, the Lookup.PSFT.HRMS.WorkForceSync.AttributeMapping and the Lookup.PSFT.HRMS.WorkForceSync.Recon for WORKFORCE_SYNC message.
6. Create a copy of the Peoplesoft HRMS Trusted Reconciliation scheduled task. See Configuring the Scheduled Task for Person Data Reconciliation for information about this scheduled task.

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 ITResource scheduled task attribute.