Extending the Functionality of the Connector

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 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 Adding Target System Attributes for Target Reconciliation.

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

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

Change the process task to handle updates, as follows:

In the Design Console, expand Process Management and then double-click Process definition.
Search for and select process AS400 User.
In the Task column, look for an update task that is similar to the one you want to add and select that entry.
Click Add.
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.
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.
Save your changes.
To add an Event Handler, select the Integration tab, and then click Add.

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

Save and close the Creating New Task dialog.
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.

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.

4.1.2 Adding Target System Attributes for Target Reconciliation

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

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.
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.
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.
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
In the Design Console, regenerate the reconciliation profile for the Resource Object.
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.

4.1.3 Adding Target System Attributes for Trusted Reconciliation

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

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

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:

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;
 
    }
}

Create a JAR file to hold the Java class.
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.
Log in to the Design Console.
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.
In the Code Key column, enter the resource object field name that you want to validate.
In the Decode column, enter the class name.

For example, com.validationexample.MyValidator.
Save your changes to the lookup definition.
Search for and open the Lookup.AS400.UM.Configuration lookup definition.
In the Code Key column, enter Provisioning Validation Lookup.
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 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:

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;
   }
}

Create a JAR file to hold the Java class.
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.
Log in to the Design Console.
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.
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).
In the Decode column, enter the class name.

For example, com.transformationexample.MyTransformer.
Save the changes to the lookup definition.
Search for and open the Lookup.AS400.UM.Configuration lookup definition.
In the Code Key column, enter Recon Transformation Lookup.
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:

Log in to the Design Console.
Expand Development Tools, and double-click Form Designer.
Search for and open the UD_AS400 process form.
Click Create New Version.
Enter a label for the new version, click the Save icon, and then close the dialog box.
From the Current Version list, select the version that you create.
Modify the length of the required field.
Click the Save icon.
Click Make Version Active.
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 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 Administering 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:

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

The following events take place when you define a connector:

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

See Defining Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed information 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:

Log in to Design Console.
Go to Development Tools, Form Designer.
In the Table Name field, enter UD_AS400CON and click Preview Form to open the form.
Click Create New Version.
Click on the Properties tab.
Under the Password (PasswordField) property, set the Required Property Value to False.
Click Save.
Click Make Version Active.