4 Extending the Functionality of the Concur Connector

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

This chapter contains the following topics:

Note:

From Oracle Identity Manager Release 11.1.2 onwards, lookup queries are not supported. For information on managing lookups by using the Form Designer in Identity System Administration, see Managing Lookups in Oracle Fusion Middleware Administering Oracle Identity Manager.

• Adding User Attributes for Reconciliation

• Adding User Attributes for Provisioning

• Configuring Validation of Data During Reconciliation and Provisioning

• Configuring Transformation of Data During User Reconciliation

• Configuring the Concur Connector for Multiple Installations of the Target System

• Defining the Concur Connector

4.1 Adding User Attributes for Reconciliation

The connector provides a default set of attribute mappings for reconciliation between Oracle Identity Manager and the target system. If required, you can add new user attributes for reconciliation.

The default attribute mappings for reconciliation are listed in Table 1-12.

The following topics provide details on adding new user attributes for reconciliation:

• Adding New Attributes on the Process Form

• Adding Attributes to the Resource Object

• Creating Reconciliation Field Mapping

• Creating Entries in Lookup Definitions for Reconciliation

• Performing Changes in a New UI Form

4.1.1 Adding New Attributes on the Process Form

You can add a new attribute on the process form in the Form Designer section of Oracle Identity Manager Design Console.

To add a new attribute on the process form:

1. Log in to Oracle Identity Manager Design Console.
2. Expand Development Tools, and double-click Form Designer.
3. Search for and open the UD_Concur process form.
4. Click Create New Version, and then click Add.
5. Enter the details of the field.

   For example, if you are adding the MiddleName field, enter UD_Concur_MIDDLENAME in the Name field and then enter other details such as Variable Type, Length, Field Label, and Field Type.

6. Click the Save icon, and then click Make Version Active. The following screenshot shows the new field added to the process form.

   Figure 4-1 New Fields Added to the Concur User Form

   
   Description of "Figure 4-1 New Fields Added to the Concur User Form"

4.1.2 Adding Attributes to the Resource Object

You can add the new attribute to the resource object in the Resource Objects section of Oracle Identity Manager Design Console.

To add the new attribute to the list of reconciliation fields in the resource object:

1. Expand Resource Management, and double-click Resource Objects.
2. Search for and open the Concur User resource object.
3. On the Object Reconciliation tab, click Add Field.
4. Enter the details of the field.
   For example, enter Middle Name in the Field Name field and select String from the Field Type list. Later in this procedure, you 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-2 New Reconciliation Field added to the Resource Object

   
   Description of "Figure 4-2 New Reconciliation Field added to the Resource Object"
6. Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.

4.1.3 Creating Reconciliation Field Mapping

You can create reconciliation field mapping for the new attribute in the Process Definition section of Oracle Identity Manager Design Console.

To create reconciliation field mapping for the new attribute in the process definition:

1. Expand Process Management, and double-click Process Definition.
2. Search for and open the Concur User process definition for Users.
3. On the Reconciliation Field Mappings tab of the process definition, click Add Field Map.
4. From the Field Name list, select the field that you want to map.
5. Double-click the Process Data Field field, and then select the column for the attribute. For example, select UD_CONCUR_MIDDLENAME.
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-3 New Reconciliation Field Mapped to a Process Data Field in the Process Definition

   
   Description of "Figure 4-3 New Reconciliation Field Mapped to a Process Data Field in the Process Definition"

4.1.4 Creating Entries in Lookup Definitions for Reconciliation

You can create an entry for the newly added attribute in the lookup definition that holds attribute mappings for reconciliation.

To create an entry for the newly added attribute in the lookup definition for reconciliation:

1. Expand Administration.
2. Double-click Lookup Definition.
3. Search for and open the following lookup definition for Users:
   Lookup.Concur.UM.ReconAttrMap
4. Click Add, and enter the Code Key and Decode values for the field.
   The Code Key value must be the name of the field in the resource object. The Decode value must be the name of the target system field in Concur.
5. Click the Save icon.

   Figure 4-4 Entry Added to the Lookup Definition for Reconciliation

   
   Description of "Figure 4-4 Entry Added to the Lookup Definition for Reconciliation"

4.1.5 Performing Changes in a New UI Form

You must replicate all changes made to the Form Designer of the Design Console in a new UI form.

To perform changes in a new UI form:

1. Log in to Identity System Administration.
2. Create and activate a sandbox. See Creating a Sandbox and Activating and Deactivating a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.
3. Create a new UI form to view the newly added field along with the rest of the fields. See Creating Forms By Using the Form Designer in Oracle Fusion Middleware Administering Oracle Identity Manager.
4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form, and then save the application instance.
5. Publish the sandbox. See Publishing a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

4.2 Adding User Attributes for Provisioning

The connector provides a default set of attribute mappings for provisioning between Oracle Identity Manager and the target system. If required, you can add new user attributes for provisioning.

The default attribute mappings for provisioning are listed in Table 1-15.

The following topics provide details on adding new user attributes for provisioning:

• Adding New Attributes for Provisioning

• Creating Entries in Lookup Definitions for Provisioning

• Creating a Task to Enable Update Operations

• Replicating Form Designer Changes to a New UI Form

4.2.1 Adding New Attributes for Provisioning

You add a new attribute on the process form in the Form Designer section of Oracle Identity Manager Design Console.

Note:

If you have already added an attribute for reconciliation, then you need not repeat steps performed as part of that procedure.

To add a new attribute on the process form:

1. Log in to Oracle Identity Manager Design Console.
2. Expand Development Tools, and double-click Form Designer.
3. Search for and open the following process form for Users.
   UD_CONCUR
4. Click Create New Version, and then click Add.
5. Enter the details of the attribute.
   For example, if you are adding the Middle Name field, enter UD_CONCUR_MIDDLENAME in the Name field, and then enter the rest of the details of this field.
6. Click the Save icon, and then click Make Version Active.
   The following screenshot shows the new field added to the process form:

   Figure 4-5 New Field Added to the Concur User Form

   
   Description of "Figure 4-5 New Field Added to the Concur User Form"

4.2.2 Creating Entries in Lookup Definitions for Provisioning

You can create an entry for the newly added attribute in the lookup definition that holds attribute mappings for provisioning.

To create an entry for the newly added attribute in the lookup definition for provisioning:

1. Expand Administration.
2. Double-click Lookup Definition.
3. Search for and open the following lookup definition for Users:
   Lookup.Concur.UM.ProvAttrMap
4. Click Add, and then enter the Code Key and Decode values for the attribute.

   Note that the Decode value must be the name of the target system field.

   Figure 4-6 Entry Added to the Lookup Definition for Provisioning

   
   Description of "Figure 4-6 Entry Added to the Lookup Definition for Provisioning"

4.2.3 Creating a Task to Enable Update Operations

You create a task to enable updates on the new user or group attribute during provisioning operations. If you do not perform this procedure, you cannot modify the value of the attribute after you set a value for it during the Create User provisioning operation.

To enable the update of the attribute during provisioning operations, add a process task for updating the new user attribute as follows:

1. Expand Process Management, and double-click Process Definition.
2. Search for and open the following process definition for Users:
   Concur User
3. Click Add.
4. On the General tab of the Creating New Task dialog box, enter a name and description for the task and then select the following:
   • Conditional
   • Required for Completion
   • Allow Cancellation while Pending
   • Allow Multiple Instances
5. Click the Save icon.

   The following screenshot shows the new task added to the process definition:

   Figure 4-7 New Task Added to the Process Definition

   
   Description of "Figure 4-7 New Task Added to the Process Definition"
6. In the provisioning process, select the adapter name in the Handler Type section as follows:
   1. Go to the Integration tab, click Add.
   2. In the Handler Selection dialog box, select Adapter.
   3. From the Handler Name column, select adpCONCURUPDATEUSER.
   4. Click Save and close the dialog box.
      The list of adapter variables is displayed on the Integration tab. The following screenshot shows the list of adapter variables:

      Figure 4-8 List of Adapter Variables

      
      Description of "Figure 4-8 List of Adapter Variables"
7. In the Adapter Variables region, click the procInstanceKey variable.
8. In the dialog box that is displayed, map the adapter variable as follows:
   1. Click Map. The Data Mapping for Variable window is displayed.
   2. Complete the following fields:

      • Variable Name: procInstanceKey

      • Map To: Process Data

      • Qualifier: Process Instance

9. Click Save and close the dialog box.
   The mapping status for the adapter variable changes from N to Y. This indicates that the adapter variable has been mapped.
10. If you are enabling update provisioning operations for a User attribute, repeat Step 7 through Step 9 for the remaining variables listed in the Adapter Variables region.
    The following table lists the values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

    Variable	Map To	Qualifier	Literal Value
    Adapter Return Value	Response Code	NA	NA
    Object Type	Literal	String	User
    itResourceFieldName	Literal	String	UD_CONCUR_IT_RESOURCE
    fieldName	Literal	String	UD_CONCUR_MIDDLENAME
    fieldOldValue	Process Data	Middle Name Note: Ensure that the Old Value check box is selected.	NA
    fieldValue	Process Data	Middle Name Note: Ensure that the Old Value check box is not selected.	NA

11. On the Responses tab, click Add to add at least the SUCCESS response code, with Status C. This ensures that if the task is successfully run, then the status of the task is displayed as Completed.
12. Click the Save icon and close the dialog box, and then save the process definition.

4.2.4 Replicating Form Designer Changes to a New UI Form

You must replicate all changes made to the Form Designer of the Design Console in a new UI form.

To replicate Form Designer changes to a new UI form:

1. Log in to Identity System Administration.
2. Create and activate a sandbox. See Creating a Sandbox and Activating and Deactivating a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.
3. Create a new UI form to view the newly added field along with the rest of the fields. See Creating Forms By Using the Form Designer in Oracle Fusion Middleware Administering Oracle Identity Manager.
4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form, and then save the application instance.
5. Publish the sandbox. See Publishing a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

4.3 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 User Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the User 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: Validation failed for attribute ATTRIBUTE_NAME.

To configure validation of data:

1. Write code that implements the required validation logic in a Java class.
   The validation class must implement validate method with the following method signature:

   boolean validate(HashMap hmUserDetails, HashMap hmEntitlementDetails, String field)

   The following sample validation class checks if the value in the User 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.
           */
           String sUserName=(String) hmUserDetails.get(field); 
           if (sUserName.contains('#')){
                   valid false;
           }
           return true;
   }

2. Create a JAR file to hold the Java class.
3. Copy the JAR file to 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.

4. If you created the Java class for validating a process form field for reconciliation, then:
   1. Log in to the Design Console.
   2. Create a lookup definition named Lookup.Concur.UM.ReconValidation .
   3. Save the changes to the lookup definition.
   4. Search for and open the Lookup.Concur.UM.Configuration lookup definition.
   5. In the Code Key column, enter Recon Validation Lookup. In the Decode column, enter Lookup.Concur.UM.ReconValidation.
   6. Save the changes to the lookup definition.
5. Add an entry in the Lookup.Concur.UM.Configuration lookup definition to enable transformation as follows:
   1. Expand Administration, and then double-click Lookup Definition.
   2. Search for and open the Lookup.Concur.UM.Configuration lookup definition.
   3. In the Code Key column, enter Recon Transformation Lookup. In the Decode column, enter Lookup.Concur.UM.ReconTransformation.
   4. Save the changes to the lookup definition.

4.4 Configuring Transformation of Data During User Reconciliation

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

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

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

   The transformation class must implement the transform method with the following method signature:

   Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField)

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

   package oracle.iam.connectors.common.transform;
   import java.util.HashMap;
   public class TransformAttribute {
           /*
           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 sUserName= (String)hmUserDetails.get("User Name"); String sLastName= (String)hmUserDetails.get("Last Name"); String sFullName=sUserName+"."+sLastName;
                   return sFullName;
           }
   }

2. Create a JAR file to hold the Java class.
3. Copy the JAR file to 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.

4. If you created the Java class for transforming a process form field for reconciliation, then:
   1. Log in to the Design Console.
   2. Create a lookup definition named Lookup.Concur.UM.ReconTransformation.
   3. In the Code Key column, enter the resource object field name on which you want to apply transformation. For example, User Name. In the Decode column, enter the name of the class that implements the transformation logic. For example, oracle.iam.connectors.common.transform.TransformAttribute.
   4. Save the changes to the lookup definition.
5. Add an entry in the Lookup.Concur.UM.Configuration lookup definition to enable transformation as follows:
   1. Expand Administration, and then double-click Lookup Definition.
   2. Search for and open the Lookup.Concur.UM.Configuration lookup definition.
   3. In the Code Key column, enter Recon Transformation Lookup. In the Decode column, enter Lookup.Concur.UM.ReconTransformation.
   4. Save the changes to the lookup definition.

4.5 Configuring the Concur Connector for Multiple Installations of the Target System

You must create copies of the connector to configure it 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 Governance, and they want to configure Oracle Identity Governance to link all the installations of the target system.

To meet the requirement posed by such a scenario, you must create copies of the connector. See Cloning Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager.

4.6 Defining the Concur Connector

Defining a connector is equivalent to registering the connector with Oracle Identity Governance. You can define a customized or reconfigured connector using Oracle Identity System Administration. After you define a connector, a record representing the connector is created in the Oracle Identity Governance database.

See Defining Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager.