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 topics:

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.

4.1 Adding New Attributes for Target Resource Reconciliation

Note:

You need not perform this procedure if you do not want to add new attributes for target resource reconciliation.

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

  1. Determine the Database ID for the attribute that you want to add:

    1. Open the Remedy Administrator Console. Note that in the newer versions of the target system, this console is known as BMC Remedy Developer Studio.

    2. Expand Servers. If you are using the newer versions of the target system, expand All Objects.

    3. Double-click Forms.

    4. Double-click the CTM:People form.

    5. Double-click the field whose Database ID you want to determine.

    6. On the Database tab, the Database ID of the field is displayed as the value of the ID field. If you are using newer versions of the target system, the Database ID of the field is present either in the Outline window along with the field name or in the Properties window as the value of ID Property under Database.

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

  3. Add the new attribute on the OIM User process form as follows:

    1. Expand Development Tools.

    2. Double-click Form Designer.

    3. Search for and open the UD_BMC process form.

    4. Click Create New Version.

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

    6. Click the Save icon.

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

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

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

      Field Value

      Name

      UD_BMC_DESKLOCATION

      Variant Type

      String

      Length

      50

      Field Label

      DeskLocation

      Order

      26

    9. Click the Save icon.

    10. Click Make Version Active.

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

    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 4.c), and then save the application instance.

    5. Publish the sandbox. See Publishing a Sandbox.

  5. 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 BMCRO resource object.

    4. On the Object Reconciliation tab, click Add Field, and then enter the following values:

      Field Name: UD_BMC_DESKLOCATION

      Field Type: String

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

  6. 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 BMCPROCESS process definition.

    4. On the Reconciliation Field Mappings tab, click Add Field Map, and then select the following values:

      Field Name: DeskLocation

      Field Type: String

      Process Data Field: UD_BMC_DESKLOCATION

    5. Click the Save icon.

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

  7. 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.BMC.UM.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 or ID of the target system attribute.

      For example, enter DeskLocation in the Code Key field and then enter 1000000035 in the Decode field.

    5. Click the Save icon.

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

  • Before starting the following procedure, perform Steps 1 through 3 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:

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

    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 4.c of Adding New Attributes for Target Resource Reconciliation), and then save the application instance.

    5. Publish the sandbox. See Publishing a Sandbox.

  2. 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, and then double-click Lookup Definition.

    3. Search for and open the Lookup.BMC.UM.ProvAttrMap lookup definition.

    4. 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 3.3.h in Adding New Attributes for Target Resource Reconciliation. The Decode value is the name or ID of the attribute in the target system.

      For example, enter DeskLocation in the Code Key field and then enter 1000000035 in the Decode field.

    5. Click the Save icon.

    Note:

    Perform steps 3 through 5 only if both the condition are true:

    • You are using Oracle Identity Manager release 11.1.1.x.

    • You want to perform request-based provisioning.

  3. Update 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:

    1. In a text editor, open the xml/BMCRemedy-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 = "DeskLocation"
attr-ref = "DeskLocation"
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_BMC_DESKLOCATION is the value in the Name column of the process form, then you must specify DeskLocation 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 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.

4.2.1 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 BMCPROCESS 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, DeskLocation Updated and the task description.

    2. In the Task Properties section, select the Conditional, Allow Cancellation while Pending, and Allow Multiple Instances fields.

    3. Click on the Save icon.

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

  5. Select the UpdateBMCUser 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:

    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

    DeskLocation

    itResourceFieldName

    String

    Literal

    String

    UD_BMC_IT_RESOURCE

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

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

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

    package org.identityconnectors.bmc.extension;
import java.util.*;
public class BMCValidator {

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. Create a lookup definition named Lookup.BMC.UM.ReconValidation.

    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.bmc.extension.BMCValidator.

    4. Save the changes to the lookup definition.

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

    6. In the Code Key column, enter Recon Validation Lookup. In the Decode column, enter Lookup.BMC.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. Create a lookup definition by the name Lookup.BMC.UM.ProvValidation.

    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.BMC.UM.Configuration lookup definition.

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

    7. Save the changes to the lookup definition.

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

4.4 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 append the domain name with the first name.

To configure the transformation of data:

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

    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:

    pacakge oracle.iam.connectors.bmc;
import java.util.HashMap;
public class BMCTransformation {
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.BMC.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.BMC.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.bmc.BMCTransformation.

    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.

4.5 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. Create a BMC connector bundle with a different version. To do so:

    1. Extract the contents of the bundle/org.identityconnectors.bmc-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. Rename the connector bundle to reflect the new version. For example, org.identityconnectors.bmc-1.0.1117.jar.

  2. Run the Oracle Identity Manager Upload JARs utility to upload the newly created JAR file (for example, org.identityconnectors.bmc-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.

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

  4. 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.BMC.Configuration lookup definition.

  5. Create an IT resource of the BMC 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.

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

    While performing Step 2 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.

4.6 Configuring the Connector for Performing Reconciliation and Provisioning Operations on Custom Forms

By default, this connector provisions to and reconciles data from the CTM:People form. If you want to perform reconciliation and provisioning operations on custom forms, then you must modify the Configuration lookup definition and add two lookup entries as follows:

  1. In the Design Console, expand Administration, and then double-click Lookup Definition.
  2. Depending on whether you have configured the target system as a trusted source or target resource, search for and open the following lookup definition:

    • For trusted source reconciliation: Lookup.BMC.Configuration.Trusted

    • For target resource reconciliation: Lookup.BMC.Configuration

  3. Click Add.
  4. In the new row, enter values for the Code Key and Decode columns as follows:

    • Code Key: userProvisioningFormName

    • Decode: Enter the name of the custom form in the target system against which reconciliation and provisioning operations must be performed. Users are created, updated, deleted, and searched for from this form.

      Note:

      If you do not specify a value in the Decode column, then reconciliation and provisioning operations are performed on the default form (CTM:People).

  5. If you have configured your target system as a target resource, then click Add to add one more lookup entry to the Lookup.BMC.Configuration lookup definition.
  6. In the new row, enter values for the Code Key and Decode columns as follows:

    • Code Key: supportGrpAssocFormName

    • Decode: Enter the custom form name in which association between a user and support group is created.

      Note:

      If you do not specify a value in the Decode column, then the association between users and the support group is created in default form (CTM:Support Group Association).

  7. Click Save.

4.7 Configuring the Connector for Performing Lookup Field Synchronization on Custom Forms

If you want to perform lookup field synchronization by specifying target system form names, then modify the value for the Object Type attribute of the scheduled job for lookup field synchronization in the following format:

OBJ_TYPE<FORM_NAME>

In this format, OBJ_TYPE is the type of object that is already present in the scheduled job. Suffix this object type with FORM_NAME, which is the name of the custom form on the target system against which lookup field synchronization runs must be performed.

Sample value: COMPANY<COM:Company>

Note:

  • The custom form name that you specify in the OBJ_TYPE<FORM_NAME> format must not be the same as the one being used for performing provisioning operations. In other words, the custom form name must not be the same as the one that you specify for the userProvisioningFormName Code Key in the Configuration lookup definition.

    The custom form name in the OBJ_TYPE<FORM_NAME> format must contain only the form names against which you perform lookup field synchronization.

  • If you do not specify the form name, then lookup field synchronization runs are performed against the default form associated with each lookup field.

See Also:

Scheduled Job for Lookup Field Synchronization for more information about the scheduled jobs for lookup field synchronization