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 connector configuration 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 guide for information about managing lookups by using the Form Designer in the Oracle Identity Manager System Administration console.

4.1 Adding Custom Attributes for Target Resource Reconciliation

Note:

In this section, the term "attribute" refers to the identity data fields that store user data.

To add a custom attribute, you must ensure that the corresponding attribute exists on the target system. If it does not exist, then you must first add the custom attribute on the target system. Contact an administrator for information about adding a custom attribute on the target system.

By default, the attributes listed in User Attributes for Target Resource Reconciliation and Provisioning are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can also configure the connector to reconcile custom attributes or other user attributes that are not available out of the box (OOTB) with the connector.For example, if Legal Entity is a custom attribute added to the user profile on the target system, then you can configure the connector to reconcile this attribute by performing the following steps:

For the custom attribute, Legal Entity, determine the corresponding attribute name in User Generic WSDL.

You can invoke the FieldManagementRead Admin Web Service API and get the value of Generic Integration Tag for the Legal Entity user attribute.

For example, Generic Integration Tag = CustomText2
Log in to the Oracle Identity Manager Design Console.
Create a new version of the process form as follows:
1. Expand Development Tools.
2. Double-click Form Designer.
3. Search for and open the UD_CRMOD_U process form.
4. Click Create New Version.
  
  On the Create a new version dialog box, enter a new version in the Label field, and then click the save icon.
Add the new field on the process form as follows:
1. Click Add.
  
  A field is added to the list. Enter the details of the field.
  
  For example, if you are adding the Legal Entity field, enter UD_CRMOD_U_LEGALENTITY in the Name field and the remaining details of this field.
  
  To add boolean attributes, select ComboBox from the Field Type list and select String as the Variant Type.
  
  If you are adding boolean attributes, create a new lookup definition, for example, Lookup.CRMOD.AttributeName. Then, add the following entries to the lookup definition:
  
  Code Key Decode
  
  Y
  
  Y
  
  N
  
  N
  
  Open the UD_CRMOD_U process form and click Properties. Select the newly added property and click Add Property. Select Property Name as Lookup Code, and then enter the newly created lookup, Lookup.CRMOD.AttributeName as the property value.
2. Click the save icon.
3. To activate the newly created form, click Make Version Active.
  
  Figure 4-1 is a sample screenshot of the new version of process form.
  
  Figure 4-1 Adding a New Version of Process Form
  
  Description of "Figure 4-1 Adding a New Version of Process Form"
Add the new field to the list of reconciliation fields in the resource object as follows:
1. Expand Resource Management.
2. Double-click Resource Objects.
3. Search for and open the CRM On Demand resource object.
4. On the Object Reconciliation tab, click Add Field.
5. In the Add Reconciliation Field dialog box, enter the details of this field.
  
  For example, enter Legal Entity in the Field Name field and select String from the Field Type list.
6. Click the save icon.
7. On the Resource Objects form, click Create Reconciliation Profile to create reconciliation profile that would include the newly added reconciliation field.
  
  Figure 4-2 is a sample screenshot of the newly added reconciliation field.
  
  Figure 4-2 Adding a New Reconciliation Field
  
  Description of "Figure 4-2 Adding a New Reconciliation Field"
Create an entry for the field in the lookup definition for reconciliation as follows:
1. Expand Administration.
2. Double-click Lookup Definition.
3. Search for and open the Lookup.CRMOD.UM.ReconAttrMap lookup definition.
4. Click Add and enter the Code Key and Decode values for the field.
  
  The Code Key value must be the Recon Field label name. The Decode value must be the name of the attribute in the User Generic WSDL.
  
  For example, enter Legal Entity in the Code Key field and then enter CustomText2 in the Decode field.
5. Click the save icon.
  
  Figure 4-3 is a sample screenshot of the new entry added to the reconciliation lookup definition.
  
  Figure 4-3 Adding an Entry to Reconciliation Lookup
  
  Description of "Figure 4-3 Adding an Entry to Reconciliation Lookup"
Create a reconciliation field mapping for the new field on the process form as follows:
1. Expand Process Management.
2. Double-click Process Definition.
3. From the Process Definition table, select and open the CRM On Demand resource object.
4. Click Reconciliation Field Mappings and then click Add Field Map.
5. In the Field Name field, select the value for the field that you want to add.
  
  For example, select Legal Entity.
6. In the Field Type field, select the type of the field that is prepopulated.
7. Double-click the Process Data Field field.
  
  A list of process data columns is displayed. From the list, select the process data column corresponding to the process data field.
  
  For example, select Legal Entity [String] = UD_CRMOD_U_LEGALENTITY.
8. Click the save icon.
If you are using Oracle Identity Manager release 11.1.2.x or later, create a new UI form and attach it to the application instance to make this new attribute visible. See Creating a New UI Form and Updating an Existing Application Instance with a New Form for the procedures.

Code Key	Decode
Y	Y
N	N

4.2 Adding Custom Attributes for Provisioning

Note:

In this section, the term "attribute" refers to the identity data fields that store user data.

By default, the attributes listed in User Attributes for Target Resource Reconciliation and Provisioning are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can also configure the connector for provisioning after adding custom attributes or other user attributes that are not available out of the box (OOTB) with the connector.For example, if Legal Entity is a custom attribute added to the user profile on the target system, then you can configure the connector to provision this attribute by performing the following steps:

For the custom attribute, Legal Entity, determine the corresponding attribute name in User Generic WSDL.

You can invoke the FieldManagementRead Admin Web Service API and get the value of Generic Integration Tag for the Legal Entity user attribute.

For example, Generic Integration Tag = CustomText2
Log in to the Oracle Identity Manager Design Console.
Create a new version of the process form as follows:
1. Expand Development Tools.
2. Double-click Form Designer.
3. Search for and open the UD_CRMOD_U process form.
4. Click Create New Version.
  
  On the Create a new version dialog box, enter a new version in the Label field, and then click the save icon.
Add the new field on the process form as follows:
1. Click Add.
  
  A field is added to the list. Enter the details of the field.
  
  For example, if you are adding the Legal Entity field, enter UD_CRMOD_U_LEGALENTITY in the Name field, Legal Entity in the Label Name field, and the remaining details of this field.
  
  If you are adding boolean attributes, select ComboBox from the Field Type list and select String as the Variant Type.
  
  Then, create a new lookup definition, for example, Lookup.CRMOD.AttributeName. Then, add the following entries to the lookup definition:
  
  Code Key Decode
  
  Y
  
  Y
  
  N
  
  N
  
  Open the UD_CRMOD_U process form and click Properties. Select the newly added property and click Add Property. Select Property Name as Lookup Code, and then enter the newly created lookup, Lookup.CRMOD.AttributeName as the property value.
2. Click the save icon.
3. To activate the newly created form, click Make Version Active.
  
  Figure 4-4 is a sample screenshot of the new version of process form.
  
  Figure 4-4 Adding a New Version of Process Form
  
  Description of "Figure 4-4 Adding a New Version of Process Form"
Create an entry for the field in the lookup definition for provisioning as follows:
1. Expand Administration.
2. Double-click Lookup Definition.
3. Search for and open the Lookup.CRMOD.UM.ProvAttrMap lookup definition.
4. Click Add and enter the Code Key and Decode values for the field.
  
  The Code Key value must be the form field label name. The Decode value must be the attribute name in the User Generic WSDL.
  
  For example, enter Legal Entity in the Code Key field and then enter CustomText2 in the Decode field.
5. Click the save icon.
  
  Figure 4-5 is a sample screenshot of the new entry added to the provisioning lookup definition.
  
  Figure 4-5 Adding an Entry to Provisioning Lookup
  
  Description of "Figure 4-5 Adding an Entry to Provisioning Lookup"
If you are using Oracle Identity Manager release 11.1.2.x or later, create a new UI form and attach it to the application instance to make this new attribute visible. See Creating a New UI Form and Updating an Existing Application Instance with a New Form for the procedures.

Code Key	Decode
Y	Y
N	N

4.3 Configuring Validation of Data During Reconciliation and Provisioning

The Lookup.CRMOD.UM.ProvValidations and Lookup.CRMOD.UM.ReconValidations lookup definitions hold single-valued data to be validated during provisioning and reconciliation operations, respectively.

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.

Note:

The Lookup.CRMOD.UM.ProvValidations and Lookup.CRMOD.UM.ReconValidations lookup definitions are optional and do not exist by default.

You must add these lookups as decode values to the Lookup.CRMOD.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations. See Setting up the Lookup Definition for User Operations for more information.

To configure validation of data:

Write code that implements the required validation logic in a Java class with a fully qualified domain name (FQDN), such as org.identityconnectors.crmod.extension.CRMODValidator.

This validation class must implement the validate method. The following sample validation class checks if the value in the First Name attribute contains the number sign (#):

package com.validationexample;

import java.util.HashMap;
 
public class MyValidator {
    public boolean validate(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) throws ConnectorException {
 
        /* 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(sField);
        for (int i = 0; i < sFirstName.length(); i++) {
            if (sFirstName.charAt(i) == '#') {
                valid = false;
                break;
            }
        }
        return valid;
 
    }
}

Log in to the Design Console.
Create one of the following new lookup definitions:
- To configure validation of data for reconciliation:
  
  Lookup.CRMOD.UM.ReconValidations
- To configure validation of data for provisioning:
  
  Lookup.CRMOD.UM.ProvValidations
In the Code Key column, enter the resource object field name that you want to validate. For example, Alias.
In the Decode column, enter the class name. For example, org.identityconnectors.crmod.extension.CRMODValidator.
Save the changes to the lookup definition.
Search for and open the Lookup.CRMOD.UM.Configuration lookup definition.
In the Code Key column, enter one of the following entries:
- To configure validation of data for reconciliation:
  
  Recon Validation Lookup
- To configure validation of data for provisioning:
  
  Provisioning Validation Lookup
In the Decode column, enter one of the following entries:
- To configure validation of data for reconciliation:
  
  Lookup.CRMOD.UM.ReconValidations
- To configure validation of data for provisioning:
  
  Lookup.CRMOD.UM.ProvValidations
Save the changes to the lookup definition.
Create a JAR with the class and upload it to the Oracle Identity Manager database as follows:

Run the Oracle Identity Manager Upload JARs utility to post the JAR file created in Step 7 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. Select 1 as the value of the JAR type.

See Also:

Upload JARs Utility in Oracle Fusion Middleware Developig and Customizing Applications for Oracle Identity Manager for detailed information about the Upload JARs utility
Run the PurgeCache utility to clear content related to request datasets from the server cache.
Perform reconciliation or provisioning to verify validation for the field, for example, Alias.

4.4 Configuring Transformation of Data During User Reconciliation

The Lookup.CRMOD.UM.ReconTransformations lookup definition holds single-valued user data to be transformed during reconciliation operations. 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:

The Lookup.CRMOD.UM.ReconTransformations lookup definition is optional and does not exist by default.

You must add this lookup as decode value to the Lookup.CRMOD.UM.Configuration lookup definition to enable exclusions during provisioning and reconciliation operations. See Setting up the Lookup Definition for User Operations for more information.

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

Write code that implements the required transformation logic in a Java class with a fully qualified domain name (FQDN), such as org.identityconnectors.crmod.extension.CRMODTransformation.

This transformation class must implement the transform method. 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 com.transformationexample;

import java.util.HashMap;
 
 
public class MyTransformer {
    public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) throws ConnectorException {
        /*
        * 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");
        return sFirstName + "." + sLastName;
 
    }
}

Log in to the Design Console.
Create a new lookup definition, Lookup.CRMOD.UM.ReconTransformations.
In the Code Key column, enter the resource object field name you want to transform. For example, Alias.
In the Decode column, enter the class name. For example, org.identityconnectors.crmod.extension.CRMODTransformation.
Save the changes to the lookup definition.
Search for and open the Lookup.CRMOD.UM.Configuration lookup definition.
In the Code Key column, enter Recon Transformation Lookup.
In the Decode column, enter Lookup.CRMOD.UM.ReconTransformations.
Save the changes to the lookup definition.
Create a JAR with the class and upload it to the Oracle Identity Manager database as follows:

Run the Oracle Identity Manager Upload JARs utility to post the JAR file created in Step 7 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. Select 1 as the value of the JAR type.

See Also:

Upload JARs Utility in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for detailed information about the Upload JARs utility
Run the PurgeCache utility to clear content related to request datasets from the server cache.
Perform reconciliation to verify transformation of the field, for example, Alias.

4.5 Configuring Resource Exclusion Lists

The Lookup.CRMOD.UM.ProvExclusionList and Lookup.CRMOD.UM.ReconExclusionList lookup definitions hold user IDs of target system accounts for which you do not want to perform provisioning and reconciliation operations, respectively.

Note:

The Lookup.CRMOD.UM.ProvExclusionList and Lookup.CRMOD.UM.ReconExclusionList lookup definitions are optional and do not exist by default.

The following is the format of the values stored in these lookups:

Code Key Decode Sample Values

Code Key	Decode	Sample Values
User Login Id resource object field name	User ID of a user	Code Key: User Login Id Decode: User001
User Login Id resource object field name with the [PATTERN] suffix	A regular expression supported by the representation in the `java.util.regex.Pattern` class	Code Key: User Login Id[PATTERN] To exclude users matching any of the user ID 's User001, User002, User088, then: Decode: User001\|User002\|User088 To exclude users whose user ID 's start with 00012, then: Decode: 00012* See Also: For information about the supported patterns, visit `http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html`

User Login Id resource object field name

User ID of a user

Code Key: User Login Id

Decode: User001

User Login Id resource object field name with the [PATTERN] suffix

A regular expression supported by the representation in the java.util.regex.Pattern class

Code Key: User Login Id[PATTERN]

To exclude users matching any of the user ID 's User001, User002, User088, then:

Decode: User001|User002|User088

To exclude users whose user ID 's start with 00012, then:

Decode: 00012*

See Also: For information about the supported patterns, visit http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html

To add entries in the lookup for exclusions during provisioning operations:

On the Design Console, expand Administration and then double-click Lookup Definition.
Create a new lookup definition, Lookup.CRMOD.UM.ProvExclusionList.

Note:

To specify user IDs to be excluded during reconciliation operations, create a new lookup definition called Lookup.CRMOD.UM.ReconExclusionList and add entries to that lookup.
Click Add.
In the Code Key and Decode columns, enter the first user ID to exclude.

Note:

The Code Key represents the resource object field name on which the exclusion list is applied during provisioning operations.
Repeat Steps 3 and 4 for the remaining user IDs to exclude.

For example, if you do not want to provision users with user IDs User001, User002, and User088 then you must populate the lookup definition with the following values:

Code Key Decode

User Login Id

User001

User Login Id

User002

User Login Id

User088

You can also perform pattern matching to exclude user accounts. You can specify regular expressions supported by the representation in the java.util.regex.Pattern class.

See Also:

For information about the supported patterns, visit http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html

For example, if you do not want to provision users matching any of the user IDs User001, User002, and User088, then you must populate the lookup definition with the following values:

Code Key Decode

User Login Id[PATTERN]

User001|User002|User088

If you do not want to provision users whose user IDs start with 00012, then you must populate the lookup definition with the following values:

Code Key Decode

User Login Id[PATTERN]

00012*
Click the save icon.

Code Key	Decode
User Login Id	User001
User Login Id	User002
User Login Id	User088