4 Extending the Functionality of the 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 onward, lookup queries are not supported. See Managing Lookups of Oracle Fusion Middleware Administering Oracle Identity Manager guide for information about managing lookups by using the Form Designer in Identity System Administration.

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

Note:

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

To configure validation of data:

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 Given 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 sGivenName=(String) hmUserDetails.get(field);
            for(int i=0;i<sGivenName.length();i++){
              if (sGivenName.charAt(i) == '#'){
                    valid=false; 
                    break;
              } 
            }
            return valid;
      }

Create a JAR file to hold the Java class.
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.
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.GoogleApps.UM.ReconValidation.
3. In the Code Key, enter the resource object field name that you want to validate. For example, Given Name. In the Decode, enter the class name. For example, org.identityconnectors.googleapps.extension.GAPPSValidator.
4. Save the changes to the lookup definition.
5. Search for and open the Lookup.GoogleApps.UM.Configuration lookup definition.
6. In the Code Key column, enter Recon Validation Lookup. In the Decode column, enter Lookup.GoogleApps.UM.ReconValidation.
7. Save the changes to the lookup definition.
If you created the Java class for validating a process form field for provisioning, then:
1. Log in to the Design Console.
2. Create a lookup definition named Lookup.GoogleApps.UM.ProvValidation.
3. In the Code Key column, enter the process form field name. For example, Given Name. In the Decode column, enter the class name. For example, org.identityconnectors.googleapps.extension.GAPPSValidator.
4. Save the changes to the lookup definition.
5. Search for and open the Lookup.GoogleApps.UM.Configuration lookup definition.
6. In the Code Key column, enter Provisioning Validation Lookup. In the Decode column, enter Lookup.GoogleApps.UM.ProvValidation.
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 account data according to your requirements. For example, you can use Given Name and Family 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 account data fetched during reconciliation:

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 Given Name and Family 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 sGivenName= (String)hmUserDetails.get("Given Name");
      String sFamilyName= (String)hmUserDetails.get("Family Name");
      String sFullName=sGivenName+"."+sFamilyName;
      return sFullName;
      }
}

Create a JAR file to hold the Java class.
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.
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.GoogleApps.UM.ReconTransformation.
3. In the Code Key column, enter the resource object field name on which you want to apply transformation. For example, Given 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.
Add an entry in the Lookup.GoogleApps.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.GoogleApps.UM.Configuration lookup definition.
3. In the Code Key column, enter Recon Transformation Lookup. In the Decode column, enter Lookup.GoogleApps.UM.ReconTransformation.
4. Save the changes to the lookup definition.

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 must create copies of the connector. See Cloning Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for more information.

4.4 Defining the Connector

Defining a connector is equivalent to registering the connector with Oracle Identity Manager. 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 Manager database.

A connector is automatically defined when you install it using the Install Connectors feature or when you upgrade it using the Upgrade Connectors feature. You must manually define a connector if:

You import the connector by using the Deployment Manager.
You customize or reconfigure the connector.
You upgrade Oracle Identity Manager.

The following events take place when you define a connector:

A record representing the connector is created in the Oracle Identity Manager database. If this record already exists, then it is updated:
The status of the newly defined connector is set to Active. In addition, the status of a previously installed release of the same connector automatically is set to Inactive.

See Defining Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed information.