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 Target Resource Reconciliation

Note:

This section describes an optional procedure. You need not perform this procedure if you do not want to add new attributes for reconciliation.

By default, the attributes listed in User Fields for Target Resource Reconciliation are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can add new attributes for target resource reconciliation.

To add a new attribute for target resource reconciliation, perform the following procedures:

Note:

You must ensure the new attributes that you add for reconciliation contain data in string-format only. Binary attributes must not be introduced into Oracle Identity Manager natively.

Adding the New Attribute on the OIM User Process Form

To add the new attribute on the OIM User process form:

  1. Log in to the Oracle Identity Manager Design Console.

  2. Expand Development Tools.

  3. Double-click Form Designer.

  4. Search for and open the UD_JDE process form.

  5. Click Create New Version.

  6. In the Label field, enter the version name. For example, version#1.

  7. Click the Save icon.

  8. Select the current version created in Step e from the Current Version list.

  9. Click Add to create a new attribute, and provide the values for that attribute.

    For example, if you are adding the address number attribute, then enter the following values in the Additional Columns tab:

    Field Value

    Name

    AddressNumber

    Variant Type

    String

    Length

    100

    Field Label

    AddressNumber

    Order

    14

  10. Click the Save icon.

  11. Click Make Version Active.

  12. If you are using Oracle Identity Manager release 11.1.2.x or later, then all changes made to the Form Designer of the Design Console must be done in a new UI form as follows:

    1. Log in to Oracle Identity System Administration.

    2. Create and active a sandbox. See Creating and Activating a Sandbox for more information.

    3. Create a new UI form to view the newly added field along with the rest of the fields. See Creating a New UI Form for more information about creating a UI form.

    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 (created in Step 5.c), and then save the application instance.

    5. Publish the sandbox. See Publishing a Sandbox for more information.

Adding the New Attribute to the list of Reconciliation Fields

Add the new attribute 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 JDE Resource Object resource object.
  4. On the Object Reconciliation tab, click Add Field, and then enter the following values:

    Field Name: AddressNumber

    Field Type: String

  5. Click the Save icon and then close the dialog box.

Creating a Reconciliation Field Mapping for the New Attribute

Create a reconciliation field mapping for the new attribute in the process definition form as follows:

  1. Expand Process Management.
  2. Double-click Process Definition.
  3. Search for and open the JDE Process process definition.
  4. On the Reconciliation Field Mappings tab, click Add Field Map, and then select the following values:

    Field Name: AddressNumber

    Field Type: String

    Process Data Field: AddressNumber

  5. Click the Save icon.
  6. Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.

Creating an Entry for the Attribute in the Reconciliation Lookup Definition

Create an entry for the attribute in the lookup definition for reconciliation as follows:

  1. Expand Administration.
  2. Double-click Lookup Definition.
  3. Search for and open the Lookup.JDE.ReconAttrMap lookup definition.
  4. Click Add and enter the Code Key and Decode values for the attribute. The Code Key value must be the name of the attribute given in the resource object. The Decode value is the name of the attribute in the target system, prefixed with the table name. The following is the format in which you must enter the Decode value:

    TABLE_NAME.ATTR_NAME

    In this format, TABLE_NAME is the name of the table in the target system database in which the attribute is present. ATTR_NAME is the name of the attribute in the target system.

    For example, enter AddressNumber in the Code Key field and then enter F00921.AddressNumber in the Decode field. Note that both Code Key and Decode values are the same.

  5. Click the Save icon.

Adding New Attributes for Provisioning

Note:

  • This section describes an optional procedure. You need not perform this procedure if you do not want to add new attributes for provisioning.

  • You can add only attributes (for provisioning) that are declared in the data structure of the 'AddUserIDToProfileAndPreference' API of the target system.

  • Before starting the following procedure, perform Steps 1 through 12 as described in Adding New Attributes for Target Resource Reconciliation. If these steps have been performed while adding new attributes for target resource reconciliation, then you need not repeat the steps.

By default, the attributes listed in User Fields for Target Resource Reconciliation are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning.

To add a new attribute for provisioning, perform the following procedures:

Creating an Entry for the Attribute in the Lookup Definition for Provisioning

Create an entry for the attribute in the lookup definition for provisioning as follows:

  1. Log in to the Oracle Identity Manager Design Console.
  2. Expand Administration.
  3. Double-click Lookup Definition.
  4. Search for and open the Lookup.JDE.UM.ProvAttrMap lookup definition.
  5. Click Add and enter the Code Key and Decode values for the attribute. The Code Key value must be the value of the Field Label created in Step 9 in Adding the New Attribute on the OIM User Process Form. The Decode value is the name of the attribute in the target system.

    For example, enter Address Number in the Code Key field and then enter mnAddressNumber in the Decode field.

  6. Click the Save icon.

Updating the Request Dataset

When you add an attribute on the process form, you also update the XML file containing the request dataset definitions. To update a request dataset:

Note:

Perform the steps provided in this topic only if you want to perform request-based provisioning.

  1. In a text editor, open the xml/JDE-Datasets.xml file located on the installation media for editing.
  2. Add the AttributeReference element and specify values for the mandatory attributes of this element.

    For example, if you added Address Number as an attribute on the process form, then enter the following line:

    <AttributeReference
name = "Address Number"
attr-ref = "Address Number"
type = "String"
widget = "text"
length = "50"
available-in-bulk = "false"/>

    In this AttributeReference element:

    • For the name attribute, enter the value in the Name column of the process form without the tablename prefix.

      For example, if UD_JDE_ADDRESS_NUMBER is the value in the Name column of the process form, then you must specify Address Number as the value of the name attribute in the AttributeReference element.

    • For the attr-ref attribute, enter the value that you entered in the Field Label column of the process form.

    • For the type attribute, enter the value that you entered in the Variant Type column of the process form.

    • For the widget attribute, enter the value that you entered in the Field Type column of the process form.

    • For the length attribute, enter the value that you entered in the Length column of the process form.

    • For the available-in-bulk attribute, specify true if the attribute must be available during bulk request creation or modification. Otherwise, specify false.

    If you added more than one attribute on the process form, then repeat this step for each attribute added.

  3. Save and close the XML file.
  4. Run the PurgeCache utility to clear content related to request datasets from the server cache.

    See Oracle Fusion Middleware System Administering Oracle Identity Manager for more information about the PurgeCache utility.

  5. Import into MDS the request dataset definitions in XML format.

    See Importing Request Datasets for detailed information about the procedure.

Enabling Update of New Attributes for Provisioning

After you add an attribute for provisioning, you must enable update operations on the attribute. If you do not perform this procedure, then you will not be able to modify the value of the attribute after you set a value for it during the Create User provisioning operation.

To enable the update of a new attribute for provisioning a user:

  1. Expand Process Management.

  2. Double-click Process Definition and open the JDE Process process definition.

  3. In the process definition, add a new task for updating the field as follows:

    1. Click Add and enter the task name, for example, AddressNumber Updated and the task description.

    2. In the Task Properties section, select the following fields:

      • Conditional

      • Allow Cancellation while Pending

      • Allow Multiple Instances

    3. Click on the Save icon.

  4. On the Integration tab, click Add, and then click Adapter.

  5. Select the adpJDEUPDATEUSER adapter, click Save, and then click OK in the message that is displayed.

  6. To map the adapter variables listed in this table, select the adapter, click Map, and then specify the data given in the following table:

    Note:

    Some of the values in this table are specific to Address Number (mnAddressNumber value in the target system). These values must be replaced with values relevant to the attributes that you require.

    Variable Name Data Type Map To Qualifier Literal Value

    processKeyInstance

    Long

    Process Data

    Process Instance

    NA

    Adapter return value

    Object

    Response Code

    NA

    NA

    objectType

    String

    Literal

    String

    User

    attrFieldName

    String

    Literal

    String

    mnAddressNumber

    itResourceFieldName

    String

    Literal

    String

    UD_JDE_RESOURCETYPE

  7. Click the Save icon and then close the dialog box.

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

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

    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 Lookup.JDE.UM.ReconValidation lookup definition.

      Note:

      If you do not find this lookup definition, then create it.

    3. In the Code Key column, enter the resource object field name that you want to validate For example, Username. In the Decode column, enter the class name. For example, org.identityconnectors.jde.extension.JDEValidator.

    4. Save the changes to the lookup definition.

    5. Search for and open the Lookup.JDE.UM.Configuration lookup definition.

    6. In the Code Key column, enter Recon Validation Lookup. In the Decode column, enter Lookup.JDE.UM.ReconValidation.

    7. Save the changes to the lookup definition.

  5. If you created the Java class for validating a process form field for provisioning, then:

    1. Log in to the Design Console.

    2. Search for and open the Lookup.JDE.UM.ProvValidation lookup definition.

    3. In the Code Key column, enter the process form 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.JDE.UM.Configuration lookup definition.

    6. In the Code Key column, enter Provisioning Validation Lookup. In the Decode column, enter Lookup.JDE.UM.ProvValidation.

    7. Save the changes to the lookup definition.

  6. Purge the cache to get the changes reflected in Oracle Identity Manager. See Purging Cache in Oracle Fusion Middleware Administering Oracle Identity Manager for more information.

Configuring Transformation of Data During Reconciliation

Note:

This section describes an optional procedure. Perform this procedure only if you want to configure transformation of data during reconciliation.

You can configure the transformation of reconciled single-valued 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 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

    This transformation class must implement the transform method. The following sample transformation class modifies the Username attribute by using values fetched from the __NAME__ attribute 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 sUserName = (String) hmUserDetails.get("__NAME__");
        return sUserName + "@example.com";
        }
}

  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. Create a new lookup definition by the name Lookup.JDE.UM.ReconTransformations and then add the following entry:

    1. Log in to the Design Console.

    2. Expand Administration, and then double-click Lookup Definition.

    3. In the Code field, enter Lookup.JDE.UM.ReconTransformations as the name of the lookup definition.

    4. In the Field field, enter the name of the table column of the Oracle Identity Manager or user-created form or tab, from which the text field, lookup field, or box field will be accessible.

    5. Select the Lookup Type option.

    6. On the Lookup Code Information tab, click Add.

    7. In the Code Key column, enter the name of the attribute on which you want to apply the transformation. For example: FirstName.

    8. In the Decode column, enter the name of the class file. For example: oracle.iam.connectors.jde.Transformation.

    9. Save the lookup definition.

  5. Purge the cache to get the changes reflected in Oracle Identity Manager. See Oracle Fusion Middleware Administering Oracle Identity Manager for information on purging cache.

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

To configure the connector for multiple installations of the target system:

  1. Obtain the jdbj.ini, jdeinterop.ini, jdelog.properties and tnsnames.ora files for the second instance of the target system and configure it to suit your deployment requirements. See Configuring the JDE Property Files for more information.

  2. Create a JDE connector bundle with a different version. To do so:

    1. Extract the contents of the bundle/org.identityconnectors.jde-1.0.1115.jar file on the installation media to a temporary directory.

    2. In a text editor, open the MANIFEST.MF file located in the META-INF directory for editing.

    3. Specify a new value for the ConnectorBundle-Version attribute. For example, specify 1.0.1117 as the new value.

    4. Save and close the file.

    5. Update the JAR file by performing the procedure described in Step 2 of Modifying the Connector Bundle.

    6. Rename the connector bundle to reflect the new version. For example, org.identityconnectors.jde-1.0.1117.jar.

  3. Run the Oracle Identity Manager Upload JARs utility to upload the newly created JAR file (for example, org.identityconnectors.jde-1.0.1117.jar file) to the 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 4 (ICFBundle) as the value of the JAR type.

    See Also:

    Migrating JARs and Resource Bundle in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for detailed information about the Upload JARs utility

  4. Create a configuration lookup definition for this instance of the target system. For example, create a lookup definition by the name Lookup.JDE.Configuration1.

  5. Add the following entries to this lookup definition and specify the corresponding values in the Decode column:

    • Connector Name

    • Bundle Version

    • User Configuration Lookup

    • Bundle Name

    Note:

    Ensure that the Decode value of Bundle Version is the latest version specified in Step 2. For example, 1.0.1117. For all entries other than Bundle Version, you can specify the same values as those present in the Lookup.JDE.Configuration lookup definition.

  6. Create an IT resource of the JDE IT Resource type. Ensure that the value of the Configuration Lookup parameter in this newly created IT resource contains the name of the lookup definition created in Step 4.

  7. If you are using the connector server, then repeat steps 1 through 7 of this section with the following difference:

    While performing Step 3 of this procedure, instead of uploading the new created JAR file to Oracle Identity Manager database, copy it to the CONNECTOR_SERVER_DIR/bundles directory.