Skip Headers
Oracle® Identity Manager Connector Guide for AS400
Release 11.1.1

E20671-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

4 Extending the Functionality of the Connector

This chapter discusses the following optional procedures:

4.1 Adding Target System Attributes

Adding target system attributes includes the following subsections:

Note:

If you add an attribute with a Date type field, make sure that you add the [Date] suffix in the Lookup definition code key.

For example, if you add _LAST_PASSWORD_CHANGE_DATE_, when you make changes in the code key for Lookup.AS400.UM.ReconAttrMap or Lookup.AS400.UM.ProvAttrMap, specify the attribute as:

_LAST_PASSWORD_CHANGE_DATE_[Date]

4.1.1 Adding Target System Attributes for Provisioning

By default, the attributes listed in Section 1.5.1, "User Attributes for Target Resource Reconciliation and Provisioning" are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning by performing these steps.

Note:

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

Do not repeat steps that you have performed as part of the procedure described in Section 4.1.2, "Adding Target System Attributes for Target Reconciliation".

To add a target system attribute for provisioning, follow these steps:

  1. Add a new form field. To add a new field to the Process form:

    1. Open the Form Designer form. This form is in the Development Tools folder of the Oracle Identity Manager Design Console.

    2. Query for the UD_AS400CON form.

    3. Click Create New Version. The Create a New Version dialog box is displayed.

    4. In the Label field, enter the name of the version.

    5. Click Save and close the dialog box.

    6. From the Current Version box, select the version name that you entered in the Label field in Step 4.

    7. On the Additional Columns tab, click Add.

    8. Specify the new field name and other values.

    9. Click Save.

    10. Click Make Version Active to make the new form field visible to the user.

      Now, if you go to Oracle Identity Manager and try to provision a new user to AS400, you should see the new form field. Next, you must add the new form field to the Provisioning Mapping Lookup.

  2. Add the new field to the Provisioning Mapping Lookup. After creating a new form field, you must add that field to the Provisioning Mapping Lookup, as follows:

    1. Expand Administration and then double-click Lookup Definition.

    2. In the Lookup Definition window, search for AS400.

      The Design Console returns Lookup.AS400.UM.ProvAttrMap.

    3. Select the Lookup Definition Table tab, and select Lookup.AS400.UM.ProvAttrMap.

      The Lookup Code Information tab maps the Oracle Identity Manager form field names and the AS400 Identity Connector attributes. Where the Code Key column contains the Oracle Identity Manager field labels and the Decode column contains the attribute names supported by the AS400 identity connector.

    4. Add a new record for the new form field. Type the new form field name into the Code Key column and type the AS400 identity connector attribute name into the Decode column.

    5. Click Save.

      Now, when you create a new AS400 user, the connector will get the new attribute as part of the create operation.

      At this point, the process task only handles creates. Next, you must change the process task to also handle updates. Instructions are described in the next steps.

  3. Change the process task to handle updates, as follows:

    1. In the Design Console, expand Process Management and then double-click Process definition.

    2. Search for and select process AS400 User.

    3. In the Task column, look for an update task that is similar to the one you want to add and select that entry.

    4. Click Add.

    5. In the Creating New Task dialog, select the General tab and enter a Task Name and a Task Description.

      The Task Name is important because it will be the form name field. Be sure to include the event you want the task to handle. For example, if you add the Building field for provisioning, then add the Building Updated task. Now, this update event will be triggered when the Building field is updated.

    6. In the Task Properties section, set the following properties as noted:

      -Conditional: Enabled

      -Required for Completion: Disabled

      -Disable Manual Insert: Disabled

      -Allow Cancellation while Pending: Enabled

      -Allow Multiple Instances: Enabled

      You do not have to change any of the remaining properties.

    7. Save your changes.

    8. To add an Event Handler, select the Integration tab, and then click Add.

    9. When the Handler Select dialog box displays, select Adapter as the handler type and then perform the following steps:

      Select adapter adpAS400CONNECTORUPDATEATTRIBUTEVALUE and click Save.

      Map all of the variables that are configured for the event adapter.

      In the Adapter Variables section, double-click a variable name to open the Edit Data Mapping For Variable dialog box. Specify the following values for each variable in turn. Be sure to save your changes after each mapping.

      Variable Name Map To Qualifier Literal Value

      itResourceFieldName

      Literal

      String

      UD_AS400CON_SERVER

      processInstanceKey

      Process Data

      Process Instance

       

      Adapter return value

      Response Code

         

      objectType

      Literal

      String

      User

      attrName

      Literal

      String

      Enter your new label


    10. Save and close the Creating New Task dialog.

    11. Check the Task column on the Process Definition tab to verify that the new process task is listed. Also verify that the new form field is available and working in Oracle Identity Manager.

  4. If you are using Oracle Identity Manager release 11.1.2 or later, create a new UI form and attach it to the application instance to make this new attribute visible. See Section 2.4.1.2, "Creating a New UI Form" and Section 2.4.1.6, "Updating an Existing Application Instance with a New Form" for the procedures.

4.1.2 Adding Target System Attributes for Target Reconciliation

By default, the attributes listed in Section 1.5.1, "User Attributes for Target Resource Reconciliation and Provisioning" are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can map additional attributes for target reconciliation as described in this section.

Note:

  • Perform this procedure only if you want to add new target system attributes for reconciliation. See the Oracle Identity Manager Design Console Guide for detailed information about these steps.

  • In the following steps, a new attribute called BUILDING will be added, its connector attribute name is BUILDING, and the form field name is Building. Names are case-sensitive.

To add a new target system attribute for target reconciliation, follow these steps:

  1. In the resource object definition, add a reconciliation field corresponding to the new attribute, as follows:

    1. Open the Resource Objects form. This form is in the Resource Management folder.

    2. Click Query for Records.

    3. On the Resource Objects Table tab, double-click the AS400 User resource object to open it for editing.

    4. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.

    5. Specify a value for the field name that is the name of the new Attribute on your Form.

      For example: Building

    6. From the Field Type list, select a data type for the field.

      For example: String

    7. Save the values that you enter, and then close the dialog box.

    8. If required, repeat Steps d through g to map more fields.

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

  2. If a corresponding field does not exist in the process form, then add a new column in the process form, as follows:

    1. Open the Form Designer form. This form is in the Development tools folder.

    2. Query for the UD_AS400CON form.

    3. Click Create New Version. The Create a New Version dialog box is displayed.

    4. In the Label field, enter the name of the version.

    5. Click Save and close the dialog box.

    6. From the Current Version box, select the version name that you entered in the Label field in Step 3.

    7. On the Additional Columns tab, click Add.

    8. In the Name field, enter the name of the data field and then enter the other details of the field.

      Note: Repeat Steps g and h if you want to add more attributes.

    9. Click Save and then click Make Version Active.

  3. Modify the process definition to include the mapping between the newly added attribute and the corresponding reconciliation field:

    1. Open the Process Definition form. This form is in the Process Management folder of the Design Console.

    2. Click the Query for Records icon.

    3. On the Process Definition Table tab, double-click the AS400 User process definition.

    4. On the Reconciliation Field Mappings tab, click Add Field Map to open the Add Reconciliation Field Mapping dialog box.

    5. From the Field Name list, select the name of the resource object that you added in Step 2e.

    6. Double-click Process Data Field and select the corresponding process form field from the Lookup dialog box. Then, click OK.

    7. Click Save and close the dialog box.

    8. If required, repeat Steps c through g to map more fields.

  4. Go to the reconciliation lookup, Lookup.AS400.UM.ReconAttrMap, and add a new record for the new attribute using the following values:

    • Code Key - Name of the reconciliation field

    • Decode - Name of the AS400 attribute

  5. In the Design Console, regenerate the reconciliation profile for the Resource Object.

  6. If you are using Oracle Identity Manager release 11.1.2 or later, create a new UI form and attach it to the application instance to make this new attribute visible. See Section 2.4.1.2, "Creating a New UI Form" and Section 2.4.1.6, "Updating an Existing Application Instance with a New Form" for the procedures.

4.1.3 Adding Target System Attributes for Trusted Reconciliation

By default, the attributes listed in Section 1.5.1, "User Attributes for Target Resource Reconciliation and Provisioning" are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can map additional attributes for trusted reconciliation as described in this section.

Note:

  • Perform this procedure only if you want to add new target system attributes for reconciliation.

  • In the following steps, a new attribute called BUILDING will be added, its connector attribute name is BUILDING, and the form field name is Building. Names are case-sensitive.

To add a new target system attribute for trusted reconciliation, follow these steps:

  1. In the resource object definition, add a reconciliation field corresponding to the new attribute, as follows:

    1. Open the Resource Objects form. This form is in the Resource Management folder.

    2. Click Query for Records.

    3. On the Resource Objects Table tab, double-click the AS400 Trusted User resource object to open it for editing.

    4. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.

    5. Specify a value for the field name that is the name of the new Attribute on your Form.

      For example: Building

    6. From the Field Type list, select a data type for the field.

      For example: String

    7. Save the values that you enter, and then close the dialog box.

    8. If required, repeat Steps d through g to map more fields.

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

  2. If a corresponding field does not exist in the process form, then add a new column in the process form, as follows:

    1. Open the Form Designer form. This form is in the Development tools folder.

    2. Query for the UD_AS400CON form.

    3. Click Create New Version. The Create a New Version dialog box is displayed.

    4. In the Label field, enter the name of the version.

    5. Click Save and close the dialog box.

    6. From the Current Version box, select the version name that you entered in the Label field in Step 3.

    7. On the Additional Columns tab, click Add.

    8. In the Name field, enter the name of the data field and then enter the other details of the field.

      Note: Repeat Steps g and h if you want to add more attributes.

    9. Click Save and then click Make Version Active.

  3. Modify the process definition to include the mapping between the newly added attribute and the corresponding reconciliation field:

    1. Open the Process Definition form. This form is in the Process Management folder of the Design Console.

    2. Click the Query for Records icon.

    3. On the Process Definition Table tab, double-click the AS400 Trusted User process definition.

    4. On the Reconciliation Field Mappings tab, click Add Field Map to open the Add Reconciliation Field Mapping dialog box.

    5. From the Field Name list, select the name of the resource object that you added in Step 2e.

    6. Double-click Process Data Field and select the corresponding process form field from the Lookup dialog box. Then, click OK.

    7. Click Save and close the dialog box.

    8. If required, repeat Steps c through g to map more fields.

  4. Go to the reconciliation lookup, Lookup.AS400.UM.ReconAttrMap.Trusted, and add a new record for the new attribute using the following values:

    • Code Key - Name of the reconciliation field

    • Decode - Name of the AS400 attribute

  5. If you are using Oracle Identity Manager release 11.1.2 or later, create a new UI form and attach it to the application instance to make this new attribute visible. See Section 2.4.1.2, "Creating a New UI Form" and Section 2.4.1.6, "Updating an Existing Application Instance with a New Form" for the procedures.

4.2 Configuring Validation and Transformation

You can configure validation for provisioned and reconciled single-valued data according to your requirements. You can also configure transformation, but it is only supported for reconciliation.

Instructions for configuring validations and transformations are described in the following sections:

4.2.1 Configuring Validation for Provisioning

To configure validation for provisioned data, follow these steps:

  1. Write some custom Java class code to implement the oracle.iam.connectors.common.validate.Validator interface.
    For example:

    package com.validationexample;
    import oracle.iam.connectors.common.ConnectorException;
    import oracle.iam.connectors.common.validate.Validator;
     
    import java.util.HashMap;
     
    public class MyValidator implements Validator {
        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;
     
        }
    }
    
  2. Create a JAR file to hold the Java class.

  3. Copy the JAR file to the 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:

    For Microsoft Windows:OIM_HOME\server\bin\UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    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.

    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.

    See Also:

    Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed information about the Upload JARs utility

  4. Log in to the Design Console.

  5. Search for and open the Lookup.AS400.UM.ProvValidation (or create another custom name) lookup definition.

    Note:

    If you cannot find the Lookup.AS400.UM.ProvValidation lookup definition, create a new lookup.

  6. In the Code Key column, enter the resource object field name that you want to validate.

  7. In the Decode column, enter the class name.

    For example, com.validationexample.MyValidator.

  8. Save your changes to the lookup definition.

  9. Search for and open the Lookup.AS400.UM.Configuration lookup definition.

  10. In the Code Key column, enter Provisioning Validation Lookup.

  11. In the Decode column, enter Lookup.AS400.UM.ProvValidation or enter the name of the lookup you created in step 3.

4.2.2 Configuring Validation for Reconciliation

The steps for configuring reconciliation validation are the same as the steps described in Section 4.2.1, "Configuring Validation for Provisioning", except that the Code Key in step 8 must be Recon Validation Lookup.

4.2.3 Configuring Reconciliation Transformation

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

To configure the reconciliation transformation:

  1. Write a custom Java class to implement the Transformation interface. For example:

    package com.transformationexample;
    
      import oracle.iam.connectors.common.transform.*;
      import java.util.HashMap;
    
      public class MyTransformer implements Transformation {
    
        public Object transform(HashMap hmUserDetails, HashMap    
             hmEntitlementDetails,String sField) {
          String sFirstName= (String)hmUserDetails.get("First Name");
          String sLastName= (String)hmUserDetails.get("Last Name");
          String sFullName=sFirstName+"."+sLastName;
          return sFullName;
       }
    }
    
  2. Create a JAR file to hold the Java class.

  3. Copy the JAR file to the 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:

    For Microsoft Windows:OIM_HOME\server\bin\UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    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.

    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.

    See Also:

    Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed information about the Upload JARs utility

  4. Log in to the Design Console.

  5. Search for and open the Lookup.AS400.UM.ReconTransformation (or create another custom name) Lookup definition.

    Note:

    If you cannot find the Lookup.AS400.UM.ReconTransformation lookup definition, create a new lookup.

  6. In the Code Key column, enter the resource object field name you want to transform (AS400 User for target reconciliation and AS400 Trusted User for trusted reconciliation).

  7. In the Decode column, enter the class name.

    For example, com.transformationexample.MyTransformer.

  8. Save the changes to the lookup definition.

  9. Search for and open the Lookup.AS400.UM.Configuration lookup definition.

  10. In the Code Key column, enter Recon Transformation Lookup.

  11. In the Decode column, enter Lookup.AS400.UM.ReconTransformation or enter the name of the lookup you created in step 3.

4.3 Configuring Connection Pooling

The AS400 connector uses Identity Connector Framework (ICF) connection pooling.

Connection pooling involves the management of connector instances, so that an OS/400 connection does not have to be created each time an operation is executed. For most applications, the default connection pooling setup should be sufficient. However, the fine-tuning of connection pooling can help to increase throughput, if maximum performance is a concern.

To set up connection pooling for the AS400 connector, add the entries shown in Table 4-1 to the Lookup.Configuration.AS400 definition using the Oracle Identity Manager Design Console.

Table 4-1 Connection Pooling Parameters

Parameter Type and Values Description

Pool Max Idle

Integer, greater than or equal to 0. Should be greater than Pool Min Idle.

Maximum number of idle connector instances.

Pool Max Size

Integer, greater than or equal to 0.

Maximum number of connector instances in the pool.

Pool Max Wait

Integer, greater than or equal to 0.

Maximum time in milliseconds to wait if the pool is waiting for a free connector instance to become available. Zero means don't wait.

Max Pool Evict Time

Integer, greater than or equal to 0.

Maximum time in milliseconds to wait before evicting an idle connector instance.

Pool Min Evict Idle Time

Integer, greater than or equal to 0.

Minimum time in milliseconds to wait before evicting an idle connector instance.

Pool Min Idle

Integer, greater than or equal to 0. Should be less than Pool Max Idle.

Minimum number of idle connector instances.


4.4 Modifying Field Lengths on the Process Form

You might want to modify the lengths of fields (attributes) on the process form. For example, if you use the Japanese locale, you might want to increase the lengths of process form fields to accommodate multibyte data from the target system.

To modify the length of a field on the process form, follow these steps:

  1. Log in to the Design Console.

  2. Expand Development Tools, and double-click Form Designer.

  3. Search for and open the UD_AS400 process form.

  4. Click Create New Version.

  5. Enter a label for the new version, click the Save icon, and then close the dialog box.

  6. From the Current Version list, select the version that you create.

  7. Modify the length of the required field.

  8. Click the Save icon.

  9. Click Make Version Active.

  10. Define the connector. If you are planning to perform any of the other procedures described in this chapter, perform those procedures and then define the connector. See Section 4.6, "Defining the Connector" for more information.

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.

You can use access policies to manage multiple installations of the target system.

Note:

If you want to create copies of all the objects that constitute the connector, then see "Cloning Connectors" in Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

4.6 Defining the Connector

By using the Administrative and User Console, you can define a customized or reconfigured connector. Defining a connector is equivalent to registering the connector with Oracle Identity Manager.

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:

The following events take place when you define a connector:

See "Defining Connectors" in Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for detailed information about the procedure to define connectors.

4.7 Enabling Ad-Hoc Linking

During trusted source reconciliation of a new user, whose account is not existing in Oracle Identity Manager, an event is generated for that user by throwing a "no match found" error. You can link this new user to any of the user already existing in Oracle Identity Manager using Ad-Hoc linking.

To enable Ad-Hoc linking for a user:

  1. Log in to Design Console.

  2. Go to Development Tools, Form Designer.

  3. In the Table Name field, enter UD_AS400CON and click Preview Form to open the form.

  4. Click Create New Version.

  5. Click on the Properties tab.

  6. Under the Password (PasswordField) property, set the Required Property Value to False.

  7. Click Save.

  8. Click Make Version Active.