4 Extending the Functionality of the Connector

This chapter describes procedures that you can perform to extend the functionality of the connector for addressing your specific business requirements. This chapter discusses the following sections:

Section 4.1, "Adding Custom Fields for Target Resource Reconciliation"
Section 4.2, "Adding New Multivalued Fields for Target Resource Reconciliation"
Section 4.3, "Adding Custom Fields for Provisioning"
Section 4.4, "Adding New Multivalued Fields for Provisioning"
Section 4.5, "Adding Terminal Services Fields for Reconciliation and Provisioning"
Section 4.6, "Configuring the Connector for User-Defined Object Classes"
Section 4.7, "Adding New Fields for Trusted Source Reconciliation"
Section 4.8, "Configuring Transformation of Data During Reconciliation"
Section 4.9, "Configuring Validation of Data During Reconciliation and Provisioning"
Section 4.10, "Enabling Reconciliation and Provisioning Operations Across Multiple Domains"
Section 4.11, "Configuring the Connector for Multiple Trusted Source Reconciliation"
Section 4.12, "Configuring the Connector for Multiple Installations of the Target System"

4.1 Adding Custom Fields for Target Resource Reconciliation

Note:

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

By default, the fields listed in Table 1-10 are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can map additional fields for user, group, or organizational unit reconciliation.

To add a custom field for target resource reconciliation:

Log in to the Oracle Identity Manager Design Console.
Add the custom field to the list of reconciliation fields in the resource object as follows:
1. Expand Resource Management and then double-click Resource Objects.
2. Search for and open one of the following resource objects:
  
  For users: AD User
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
3. On the Object Reconciliation tab, click Add Field.
4. In the Add Reconciliation Field dialog box, enter the details of the field.
  
  For example, enter Description in the Field Name field and select String from the Field Type list.
5. Click Save and close the dialog box.
6. Click Create Reconciliation Profile. This copies changes made to the resource object into MDS.
7. Click Save.
Create an entry for the field in the lookup definition for reconciliation as follows:
1. Expand Administration and then double-click Lookup Definition.
2. Search for and open one of the following lookup definitions:
  
  For users: Lookup.ActiveDirectory.UM.ReconAttrMap
  
  For groups: Lookup.ActiveDirectory.GM.ReconAttrMap
  
  For organizational units: Lookup.ActiveDirectory.OM.ReconAttrMap
3. Click Add and enter the Code Key and Decode values for the field. The Code Key value is the name of the field that you provide for the reconciliation field in Step 2.d. The Decode value is the name of the target system field.
  
  For example, enter Description in the Code Key field and then enter description in the Decode field.
4. Click Save.
Add the custom field on the process form as follows:
1. Expand Development Tools and then double-click Form Designer.
2. Search for and open one of the following process forms:
  
  For users: UD_ADUSER
  
  For groups: UD_ADGRP
  
  For organizational units: UD_ADOU
3. Click Create New Version, and then click Add.
4. Enter the details of the field.
  
  For example, if you are adding the Description field, enter UD_ADUSER_DESCRIPTION in the Name field, and then enter the rest of the details of this field.
5. Click Save and then click Make Version Active.
Create a reconciliation field mapping for the custom field in the provisioning process as follows:
1. Expand Process Management and then double-click Process Definition.
2. Search for and open one of the following provisioning process:
  
  For users: AD User
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
3. On the Reconciliation Field Mappings tab of the provisioning process, click Add Field Map.
4. In the Add Reconciliation Field Mapping dialog box, from the Field Name field, select the value for the field that you want to add.
  
  For example, from the Field Name field, select Description.
5. Double-click the Process Data field, and then select UD_ADUSER_DESCRIPTION.
6. Click Save and close the dialog box.
7. Click Save.

4.2 Adding New Multivalued Fields for Target Resource Reconciliation

Note:

This procedure can be applied to add either user, group, or organizational unit fields.

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

By default, the multivalued fields listed in Table 1-10 are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can add new multivalued fields for target resource reconciliation.

To add a new multivalued field for target resource reconciliation:

Log in to the Oracle Identity Manager Design Console.
Create a form for the multivalued field as follows:
1. Expand Development Tools and double-click Form Designer.
2. Create a form by specifying a table name and description, and then click Save.
3. Click Add and enter the details of the field.
4. Click Save and then click Make Version Active. Figure 4-1 shows the multivalued field added on a new form.
Figure 4-1 Multivalued Field Added on a New Form

Description of "Figure 4-1 Multivalued Field Added on a New Form"
Add the form created for the multivalued field as a child form of the process form as follows:
1. Search for and open one of the following process forms:
  
  For users: UD_ADUSER
  
  For groups: UD_ADGRP
  
  For organizational units: UD_ADOU
2. Click Create New Version.
3. Click the Child Table(s) tab.
4. Click Assign.
5. In the Assign Child Tables dialog box, select the newly created child form, click the right arrow, and then click OK.
6. Click Save and then click Make Version Active. Figure 4-2 shows the child form added to the process form.
Figure 4-2 Child Form Added to the Process Form

Description of "Figure 4-2 Child Form Added to the Process Form"
Add the new multivalued field to the list of reconciliation fields in the resource object as follows:
1. Expand Resource Management and then double-click Resource Objects.
2. Search for and open one of the following resource objects:
  
  For users: AD User
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
3. On the Object Reconciliation tab, click Add Field.
4. In the Add Reconciliation Fields dialog box, enter the details of the field.
  
  For example, enter carlicenses in the Field Name field and select Multi-Valued Attribute from the Field Type list.
5. Click Save and then close the dialog box.
6. Right-click the newly created field and select Define Property Fields.
7. In the Add Reconciliation Fields dialog box, enter the details of the newly created field.
  
  For example, enter carlicense in the Field Name field and select String from the Field Type list.
8. Click Save, and then close the dialog box. Figure 4-3 shows the new reconciliation field added in the resource object.
  
  Figure 4-3 New Reconciliation Field Added in the Resource Object
  
  Description of "Figure 4-3 New Reconciliation Field Added in the Resource Object"
9. Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
Create an entry for the field in the lookup definition for reconciliation as follows:
1. Expand Administration and then double-click Lookup Definition.
2. Search for and open one of the following lookup definitions:
  
  For users: Lookup.ActiveDirectory.UM.ReconAttrMap
  
  For groups: Lookup.ActiveDirectory.GM.ReconAttrMap
  
  For organizational units: Lookup.ActiveDirectory.OM.ReconAttrMap
  
  Note:
  
  For the target system fields, you must use the same case (uppercase or lowercase) as given on the target system. This is because the field names are case-sensitive.
3. Cick Add and enter the Code Key and Decode values for the field, and then Click Save. The Code Key and Decode values must be in the following format:
  
  Code Key: MULTIVALUED_FIELD_NAME~CHILD_RESOURCE_OBJECT_FIELD_NAME
  
  Decode: Corresponding target system attribute.
  
  For example, enter carlicenses~carlicense in the Code Key field and then enter carlicense in the Decode field. Figure 4-4 shows the lookup code added to the lookup definition.
Figure 4-4 Entry Added in the Lookup Definition

Description of "Figure 4-4 Entry Added in the Lookup Definition"
Create a reconciliation field mapping for the new field as follows:
1. Expand Process Management and double-click Process Definition.
2. Search for and open one of the following process definitions:
  
  For users: AD User
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
3. On the Reconciliation Field Mappings tab of the AD User (or AD Group, or AD Organizational Unit process definition, click Add Table Map.
4. In the Add Reconciliation Table Mapping dialog box, select the field name and table name from the list, click Save, and then close the dialog box.
5. Right-click the newly created field, and select Define Property Field Map.
6. In the Field Name field, select the value for the field that you want to add.
7. Double-click the Process Data Field field, and then select UD_CARLICEN.
8. Select Key Field for Reconciliation Field Matching and click Save. Figure 4-5 shows the new reconciliation field mapped to a process data field in the process definition.
Figure 4-5 New Reconciliation Field Mapped to a Process Data Field

Description of "Figure 4-5 New Reconciliation Field Mapped to a Process Data Field"

4.3 Adding Custom Fields for Provisioning

By default, the attributes listed in Table 1-15 section are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning.

To add a custom field for provisioning:

Log in to the Oracle Identity Manager Design Console.
Add the new field of the process form.

If you have added the field on the process form by performing Step 4 of Section 4.1, "Adding Custom Fields for Target Resource Reconciliation," then you need not add the field again. If you have not added the field, then:
1. Expand Development Tools and then double-click Form Designer.
2. Search for and open one of the following process forms:
  
  For users: UD_ADUSER
  
  For groups: UD_ADGRP
  
  For organizational units: UD_ADOU
3. Click Create New Version, and then click Add.
4. Enter the details of the field.
  
  For example, if you are adding the Description field, enter UD_ADUSER_DESCRIPTION in the Name field, and then enter the rest of the details of this field.
5. Click Save and then click Make Version Active.
Create an entry for the field in the lookup definition for provisioning as follows:
1. Expand Administration and then double-click Lookup Definition.
2. Search for and open one of the following lookup definitions:
  
  For users: Lookup.ActiveDirectory.UM.ProvAttrMap
  
  For groups: Lookup.ActiveDirectory.GM.ProvAttrMap
  
  For organizational units: Lookup.ActiveDirectory.OM.ProvAttrMap
3. Cick Add and then enter the Code Key and Decode values for the field. The Decode value must be the name of the field on the target system.
  
  For example, enter Description (name of the field added to the process form in Step 2 of this procedure) in the Code Key field and then enter description in the Decode field.
4. Click Save.

Enable update provisioning operations on the custom field as follows:

In the provisioning process, add a new task for updating the field as follows:

i. Expand Process Management and then double-click Process Definition.

ii. Search for and open one of the following provisioning process:

For users: AD User

For groups: AD Group

For organizational units: AD Organizational Unit

iii. Click Add and enter the task name and task description. The following are sample values:

Task Name: Description Updated

Task Description: Process Task for handling update of the description field.

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

- Conditional

- Allow Cancellation while Pending

- Allow Multiple Instances

v. Click Save.
In the provisioning process, select the adapter name in the Handler Type section as follows:

i. Go to the Integration tab, click Add.

ii. In the Handler Selection dialog box, select Adapter.

iii. From the Handler Name column, select adpADIDCUPDATEATTRIBUTEVALUE.

iv. Click Save and close the dialog box.
In the Adapter Variables region, click the procInstanceKey variable.
In the dialog box that is displayed, create the following mapping:

Variable Name: procInstanceKey

Map To: Process Data

Qualifier: Process Instance
Click Save and close the dialog box.

Perform one of the following steps:

For users:

Repeat Steps 4.c through 4.e for the remaining variables listed in the Adapter Variables region. The following table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

Variable	Map To	Qualifier	Literal Value
Adapter Return Variable	Response Code	NA	NA
itResourceFieldName	Literal	String	UD_ADUSER_SERVER
attrFieldName	Literal	String	Description
objectType	Literal	String	User

For groups:

Repeat Steps 4.c through 4.e for all the variables listed in the following table. This table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

Variable	Map To	Qualifier	Literal Value
procInstanceKey	Process Data	Process Instance	NA
Adapter Return Variable	Response Code	NA	NA
itResourceFieldName	Literal	String	UD_ADGRP_SERVER
attrFieldName	Literal	String	CUSTOM_FIELD_NAME
objectType	Literal	String	Group

For organizational units:

Repeat Steps 4.c through 4.e for all the variables listed in the following table. This table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

Variable	Map To	Qualifier	Literal Value
procInstanceKey	Process Data	Process Instance	NA
Adapter Return Variable	Response Code	NA	NA
itResourceFieldName	Literal	String	UD_ADOU_SERVER
attrFieldName	Literal	String	CUSTOM_FIELD_NAME
objectType	Literal	String	organizationalUnit

On the Responses tab, click Add to add at least the SUCCESS response code, with Status C. This ensures that if the custom task is successfully run, then the status of the task is displayed as Completed.
Click the Save icon and close the dialog box, and then save the process definition.

Note:

Perform steps 5 through 7 only if you want to perform request-based provisioning.

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 file located in the OIM_HOME/dataset/file directory for editing.
2. Add the AttributeReference element and specify values for the mandatory attributes of this element.
  
  See Also:
  
  The "Configuring Requests" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager guide for more information about creating and updating request datasets
  
  For example, while performing Step 2 of this procedure, if you added Employee ID as an attribute on the process form, then enter the following line:
```
<AttributeReference
name = "Employee ID"
attr-ref = "Employee ID"
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_ADUSER_EMPLOYEE_ID is the value in the Name column of the process form, then you must specify Employee ID 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 while performing Step 2.
  - For the type attribute, enter the value that you entered in the Variant Type column of the process form while performing Step 2.
  - For the widget attribute, enter the value that you entered in the Field Type column of the process form, while performing Step 2.
  - For the length attribute, enter the value that you entered in the Length column of the process form while performing Step 2.
  - For the available-in-bulk attribute, specify true if the attribute must be available during bulk request creation or modification. Otherwise, specify false.
  While performing Step 2, 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.
Run the PurgeCache utility to clear content related to request datasets from the server cache.

See Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for more information about the PurgeCache utility.
Import into MDS, the request dataset definitions in XML format.

See Section 2.3.1.4.2, "Importing Request Datasets" for detailed information about the procedure.

4.4 Adding New Multivalued Fields for Provisioning

To add new multivalued fields for provisioning:

Note:

Before starting the following procedure, perform Steps 1 through 3 as described in Section 4.2, "Adding New Multivalued Fields for Target Resource Reconciliation." If these steps have been performed while adding new multivalued fields for target resource reconciliation, then you need not repeat the steps.

Log in to the Oracle Identity Manager Design Console.
Create an entry for the field in the lookup definition for provisioning as follows:
1. Expand Administration and double-click Lookup Definition.
2. Search for and open one of the lookup definitions:
  - For a user field on Microsoft Active Directory, open Lookup.ActiveDirectory.UM.ProvAttrMap.
  - For a group field on Microsoft Active Directory, open Lookup.ActiveDirectory.GM.ProvAttrMap.
  - For a organizational unit field on Microsoft Active Directory, open Lookup.ActiveDirectory.OM.ProvAttrMap.
3. Cick Add and then enter the Code Key and Decode values for the field. The Code Key and Decode values must be in the following format:
  
  Code Key: CHILD_FORM_NAME~CHILD_FIELD_LABEL
  
  In this format, CHILD_FORM_NAME specifies the name of the child form. CHILD_FIELD_NAME specifies the name of the field on the OIM User child form in the Administrative and User Console.
  
  Decode: Corresponding target system attribute
  
  Note:
  
  For the target system fields, you must use the same case (uppercase or lowercase) as given on the target system. This is because the field names are case-sensitive.
  
  For example, enter UD_CARLICEN~Car License in the Code Key field and then enter carLicense in the Decode field. Figure 4-6 shows the entry added to the lookup definition.
  
  Figure 4-6 Entry Added to the Lookup Definition
  
  Description of "Figure 4-6 Entry Added to the Lookup Definition"
Expand Process Management.
In the process definition, add the task for provisioning multivalued attributes as follows:
1. Double-click Process Definition.
2. Search for and open one of the following process definitions:
  
  For users: AD User
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
3. Click Add and enter the task name and description. For example, enter Car License Insert as the task name and task description.
4. In the Task Properties section, select the following:
  - Conditional
  - Allow cancellation while Pending
  - Allow Multiple Instances
  - UD_CARLICEN, to add the child table from the Child Table list
  - Insert, to add the data from the Trigger Type list
5. Click Save. Figure 4-7 shows the multivalued task added to the process.
Figure 4-7 Multivalued Field Added to the AD User Provisioning Process

Description of "Figure 4-7 Multivalued Field Added to the AD User Provisioning Process"
Select the adapter as follows:
1. On the Integration tab in the AD User provisioning Process, click Add and then select Adapter. From the list of adapters, select adpADIDCUPDATECHILDTABLEVALUES.
2. Click Save and then close the dialog box.
In the Adapter Variables region, click the procInstanceKey variable.
In the dialog box that is displayed, create the following mapping:

Variable Name: procInstanceKey

Map To: Process Data

Qualifier: Process Instance
Click Save and close the dialog box.

Perform one of the following steps:

For users:

Repeat Steps 6 through 8 for the remaining variables listed in the Adapter Variables region. The following table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

Variable	Map To	Qualifier	Literal Value
Adapter Return Variable	Response Code	NA	NA
itResourceFieldName	Literal	String	UD_ADUSER_SERVER
childTableName	Literal	String	UD_CARLICEN
objectType	Literal	String	User

For groups:

Repeat Steps 6 through 8 for all the variables listed in the following table. This table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

Variable	Map To	Qualifier	Literal Value
procInstanceKey	Process Data	Process Instance	NA
Adapter Return Variable	Response Code	NA	NA
itResourceFieldName	Literal	String	UD_ADGRP_SERVER
childTableName	Literal	String	UD_CHILD_PROCESS_FORM_NAME
objectType	Literal	String	Group

For organizational units:

Repeat Steps 6 through 8 for all the variables listed in the following table. This table lists values that you must select from the Map To, Qualifier, and Literal Value lists for each variable:

Variable	Map To	Qualifier	Literal Value
procInstanceKey	Process Data	Process Instance	NA
Adapter Return Variable	Response Code	NA	NA
itResourceFieldName	Literal	String	UD_ADOU_SERVER
childTableName	Literal	String	UD_CHILD_PROCESS_FORM_NAME
objectType	Literal	String	organizationalUnit

On the Responses tab, click Add to add at least the SUCCESS response code, with Status C. This ensures that if the custom task is successfully run, then the status of the task is displayed as Completed.
Click the Save icon, close the dialog box, and then save the process definition.
Add the Car License Update process task by performing Steps 3 through 11 with the following difference:

While performing Step 4.d, instead of selecting UD_CARLICEN from the Child Table list, select UD_CARLICN. Similarly, instead of selecting Insert from the Trigger Type list, select Update.
Add the Car License Delete process task by performing Steps 3 through 11 with the following difference:

While performing Step 4.d, instead of selecting UD_CARLICEN from the Child Table list, select UD_CARLICN. Similarly, instead of selecting Insert from the Trigger Type list, select Delete.
Click Save on Process Task.
Update the request dataset.

Note:

Perform steps 15 through 17 only if you enabled request-based provisioning.

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 file located in the OIM_HOME/DataSet/file directory for editing.
2. Add the AttributeReference element and specify values for the mandatory attributes of this element.
  
  See Also:
  
  The "Configuring Requests" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for more information about creating and updating request datasets
  
  For example, if you added Car License as an attribute on the process form, then enter the following line:
```
<AttributeReference
name = "Car License"
attr-ref = "Car License"
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_CAR_LICENSE is the value in the Name column of the process form, then you must specify Car License 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 add more than one attribute on the process form, then repeat this step for each attribute added.
3. Save and close the XML file.
Run the PurgeCache utility to clear content related to request datasets from the server cache.

See Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for more information about the PurgeCache utility.
Import into MDS, the request dataset definitions in XML format.

See Section 2.3.1.4.2, "Importing Request Datasets" for detailed information about the procedure.

4.5 Adding Terminal Services Fields for Reconciliation and Provisioning

Note:

The information in this section is applicable only to the Microsoft Active Directory target system and only if you are going to use the target system as a target resource.

Terminal Services fields are only supported for Microsoft Active Directory and not Microsoft AD LDS. Skip this section you are using Microsoft AD LDS as the target system.

By default, the following terminal services fields are readily available for reconciliation and provisioning:

AllowLogon

TerminalServicesProfilePath

TerminalServicesHomeDirectory

If required, you can add the following terminal services fields for reconciliation and provisioning operations:

TerminalServicesInitialProgram

TerminalServicesWorkDirectory

AllowLogon

MaxConnectionTime

MaxDisconnectionTime

MaxIdleTime

ConnectClientDrivesAtLogon

ConnectClientPrintersAtLogon

DefaultToMainPrinter

BrokenConnectionAction

ReconnectionAction

EnableRemoteControl

TerminalServicesProfilePath

TerminalServicesHomeDirectory

TerminalServicesHomeDrive

The procedure described in the following sections can be applied to add terminal services fields for reconciliation and provisioning. Note that the terminal field names in the preceding list must be used as the decode value in the Lookup.ActiveDirectory.UM.ProvAttrMap and Lookup.ActiveDirectory.UM.ReconAttrMap lookup definitions for provisioning and reconciliation, respectively.

Section 4.1, "Adding Custom Fields for Target Resource Reconciliation"
Section 4.3, "Adding Custom Fields for Provisioning"

4.6 Configuring the Connector for User-Defined Object Classes

To configure the connector for user-defined object classes:

Create the object class and assign mandatory and optional attributes to the object class.

Refer to Microsoft documentation for information about creating the object class.

Note:

Assign the user object class as the parent of the object class that you create.
Refresh the schema.
To add the mandatory and optional attributes of the object class for provisioning, perform the procedure described in Section 4.3, "Adding Custom Fields for Provisioning."
Open the Lookup.Configuration.ActiveDirectory lookup definition and change the decode value of the ObjectClass code key value to include the new object class name.

4.7 Adding New Fields for Trusted Source Reconciliation

Note:

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

By default, the attributes listed in Table 1-19 are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can add new fields for trusted source reconciliation.

Before you add a new field for trusted source reconciliation, you must first determine the target system name of the field as follows:

Install the target system schema, if it is not already installed.

Refer to the Microsoft Web site for information about installing the schema.

Note:

The ADSIEdit tool provides an alternative to installing and using the target system schema for determining the name of the field that you want to add. The Microsoft Web site provides information about using this tool.
Open the target system schema.
Expand the Console Root folder, expand the target system schema, and then double-click Classes.
Right-click user, and then select Properties.

The Attributes tab displays the attributes (that is, fields) that are currently in use on the target system
Note down the name of the field that you want to add, and then click Cancel.

For example, if you want to add the Employee ID field for reconciliation, then note down employeeID.

To add a new field for trusted source reconciliation:

See Also:

Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed information about these steps

Log in to the Oracle Identity Manager Design Console.
Add the new field on the OIM User process form as follows:
1. Expand Administration.
2. Double-click User Defined Field Definition.
3. Search for and open the Users form.
4. Click Add and enter the details of the field.
  
  For example, if you are adding the Employee ID field, then enter Employee ID in the Name field, set the data type to String, enter USR_UDF_EMPLOYEE_ID as the column name, and enter a field size value.
5. Click Save.
Add the new field to the list of reconciliation fields in the resource object as follows:
1. Expand the Resource Management folder.
2. Double-click Resource Objects.
3. Search for and open one of the following resource objects:
  
  For users: AD User Trusted
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
4. On the Object Reconciliation tab, click Add Field.
5. Enter the details of the field and click Save.
  
  For example, enter Employee ID in the Field Name field and select String from the Field Type list.
  
  Later in this procedure, you will enter the field name as the Decode value of the entry that you create in the lookup definition for reconciliation.
6. Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
Create a reconciliation field mapping for the new field as follows:
1. Expand Process Management.
2. Double-click Process Definition.
3. Search for and open the AD User Trusted process definition.
4. On the Reconciliation Field Mappings tab, click Add Field Map.
5. In the Field Name field, select the value for the field that you want to add.
  
  For example, select Employee ID = Employee ID.
6. Click Save.
Create an entry for the field in the lookup definition for reconciliation as follows:
1. Expand Administration and then double-click Lookup Definition.
2. Search for and open the Lookup.ActiveDirectory.UM.ReconAttrMap.Trusted lookup definition.
  
  Search for and open the Lookup.ActiveDirectoryLDS.UM.ReconAttrMap.Trusted lookup definition if you are using Microsoft AD LDS.
3. Cick Add and then enter the Code Key and Decode values for the field. The Code Key value must be the name of the field created in the AD User Trusted resource object. The Decode value is the name of the corresponding field on the target system.
  
  Note:
  
  For the target system fields, you must use the same case (uppercase or lowercase) as given on the target system. This is because the field names are case-sensitive.
  
  For example, enter employeeID in the Code Key field and then enter Employee ID in the Decode field.
4. Click Save.
Select Field Type and click Save.

4.8 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 transformation of reconciled data according to your requirements. For example, you can automate the look up of the field name from an external system and set the value based on the field name.

To configure transformation of data:

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

The only criteria for the class is that it should have a method with the following name and signature:

public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) {}

The following is a sample transformation class:

import java.util.*;
public class MyTransformer {
 
      /*
      Description:Abstract method for transforming the attributes
      param hmUserDetails<String,Object>
      HashMap containing parent data details
      param hmEntitlementDetails <String,Object>
      HashMap containing child data details
      */
          
      public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails, String sField) {
      /*
       * 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 firstName= (String)hmUserDetails.get("First Name");
      firstName= "blahPrefix" + firstName + "blahSuffix";
      System.out.println("First Name Value is changed to: " + firstName);
      return firstName;
      }
} /* End */

The method defined in this class transforms the value of the First Name attribute by prefixing the first name with blahPrefix and suffixing the first name with blahSuffix, and returns the transformed value.

Create a JAR file to hold the Java class.
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:

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.

See Also:

Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed information about the Upload JARs utility
Add an entry in the lookup definition for transformation as follows:
1. Log in to the Design Console.
2. Search for and open the Lookup.ActiveDirectory.UM.ReconTransformation lookup definition.
3. In the Code Key column, enter the reconciliation field name for the attribute on which you want to apply the transformation. For example: First Name.
4. In the Decode column, enter the name of the class file. For example: com.transformationexample.MyTransformer.
5. Save the changes to the lookup definition.
Note:

To configure the transformation of data during trusted source reconciliation, then add the following entries in the Lookup.ActiveDirectory.UM.Configuration.Trusted lookup definition:
- Code Key value: Recon Transformation Lookup
- Decode value: Lookup.ActiveDirectory.UM.ReconTransformation

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

For data that fails the validation check, the following message is displayed or recorded in the log file:

Value returned for field FIELD_NAME is false.

To configure validation of data:

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

This validation class must implement the oracle.iam.connectors.common.validate.Validator interface and the validate method.

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 sUserID=(String) hmUserDetails.get(field);
for(int i=0;i<sUserID.length();i++){
if (sUserID.charAt(i) == '#'){
valid=false;
break;
}
}
return valid;
}
}

Create a JAR file to hold the Java class.
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:

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.

See Also:

Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed information about the Upload JARs utility
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.ActiveDirectory.UM.ReconValidation lookup definition.
3. In the Code Key column, enter the resource object field name. In the Decode column, enter the class name (for example: com.validate.MyValidation).
4. Save the changes to the lookup definition.
5. Search for and open the Lookup.ActiveDirectory.UM.Configuration lookup definition.
6. Ensure that the value of the Recon Validation Lookup entry is set to Lookup.ActiveDirectory.UM.ReconValidation.
7. Save the changes to the lookup definition.
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.ActiveDirectory.UM.ProvValidation lookup definition.
3. In the Code Key column, enter the process form field name. In the Decode column, enter the class name (for example: com.validate.MyValidation).
4. Save the changes to the lookup definition.
5. Search for and open the Lookup.ActiveDirectory.UM.Configuration lookup definition.
6. Ensure that the value of the Provisioning Validation Lookup entry is set to Lookup.ActiveDirectory.UM.ProvValidation.
7. Save the changes to the lookup definition.

4.10 Enabling Reconciliation and Provisioning Operations Across Multiple Domains

Note:

The information in this section is applicable only if you are using Microsoft Active Directory as the target system. Enabling reconciliation and provisioning operations across multiple domains is not supported if you are using Microsoft AD LDS as the target system.

The Microsoft Active Directory User Management connector supports reconciliation and provisioning operations across multiple domains in a single forest. Reconciliation runs are performed by using the Global Catalog Server and provisioning operations are performed by using LDAP referrals.

If you want to enable reconciliation and provisioning across multiple domains, then perform the procedure described in the following sections:

Section 4.10.1, "Enabling Reconciliation Across Multiple Domains"
Section 4.10.2, "Enabling Provisioning Across Multiple Domains"

4.10.1 Enabling Reconciliation Across Multiple Domains

To perform reconciliation across multiple domains, this connector uses both the domain controller and the Global Catalog Server for fetching records from the target system.

During reconciliation, records from the Global Catalog Server are fetched to the connector. After a record is fetched into the connector, the distinguishedName and uSNChanged attribute values are read. By using the distinguishedName, the connector performs an LDAP query on the domain controller that contains the actual data (referrals are used here). This approach is used for reconciliation because the Global Catalog Server has only partial set of records. Complete data can only be fetched from the domain controller.

After all records are fetched into Oracle Identity Manager, the reconciliation engine updates the Latest Token attribute of the scheduled job with the maximum value of the uSNChanged attribute of a domain controller on which the Global Catalog Server is running. From the next reconciliation run onward, only records whose uSNChanged attribute values are greater than current value in the Latest Token attribute are fetched from the Global Catalog Server. Therefore, any updates made to a record on the target system must update the uSNChanged attribute of that record in the Global Catalog Server so that the connector can detect records that have been updated since the last reconciliation run and then fetch them into Oracle Identity Manager.

To enable reconciliation across domains:

Set the value of the SearchChildDomains entry to yes in one of the following lookup definitions:

For trusted source reconciliation: Lookup.Configuration.ActiveDirectory.Trusted

For target resource reconciliation: Lookup.Configuration.ActiveDirectory
Specify the name of the domain controller that is hosting the Global Catalog Server as the value of the SyncGlobalCatalogServer IT resource parameter.

Note:

If the value of the SearchChildDomains entry in the configuration lookup definition is set to yes and no value is specified for the SyncGlobalCatalogServer parameter of the IT resource, then the connector determines the Global Catalog Server on its own. It is strongly recommended that you specify a value for the SearchChildDomains entry and the SyncGlobalCatalogServer IT resource parameter.
While performing group reconciliation in a cross-domain environment, the connector fetches only those groups of the account that are visible to the domain controller on which the account is present.

4.10.2 Enabling Provisioning Across Multiple Domains

In a parent-child deployment environment of the target system, before performing provisioning operations across multiple domains, it is expected that the target system IT resource is configured with the parent domain. In a replication environment of the target system, before performing provisioning operations across multiple domains, it is expected that the target system IT resource is configured with any of the domain controllers.

This scenario is illustrated by the following example:

Suppose a parent-child domain environment in which the parent domain is dc1 and child domain is dc2. The target system IT resource is configured to include dc1 as the value of the LDAPHostName parameter the name of the parent domain as the value of the DomainName parameter.

During provisioning, if we select an organization that belongs to the child domain, multiple groups that span across domains, and the manager from the parent domain, then LDAP referrals are internally used by ADSI (Active Directory Service Interfaces). This is because all connectors operations are leveraged to ADSI, which enables creation of an account in the child domain even without providing any details of the child domain in the IT resource.

All this information is internally calculated depending upon the organization that is selected during the provisioning operation. In the connector, the referral chasing option is set to All, which means that all referrals are chased when any referral is provided by the domain controller. Therefore, no explicit configuration procedure is required to enable provisioning across multiple domains.

See Also:

The ADSI documentation for more information about LDAP referrals

4.11 Configuring the Connector for Multiple Trusted Source Reconciliation

The following are examples of scenarios in which there is more than one trusted source for user data in an organization:

One of the target systems is a trusted source for data about employees. The second target system is a trusted source for data about contractors. The third target system is a trusted source for data about interns.
One target system holds the data of some of the identity fields that constitute an OIM User. Two other systems hold data for the remaining identity fields. In other words, to create an OIM User, data from all three systems would need to be reconciled.

If the operating environment of your organization is similar to that described in either one of these scenarios, then this connector enables you to use the target system as one of the trusted sources of user data in your organization.

See Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed information about multiple trusted source reconciliation.

4.12 Configuring the Connector for Multiple Installations of the Target System

Note:

The information in this section also applies to Microsoft AD LDS.

Perform the procedure described in this section if your environment has multiple installations of the target system, which share the same schema managed by this connector. In such a scenario, only the IT resource information must be changed and scheduled tasks must be replicated, but the underlying workflow and process form is shared across all installations of the target system.

If your environment has multiple installations of the target system and the schema differs (that is, different sets of attributes must be managed by using the connector. In other words, you need different process forms, workflows, and so on), then you must use the connector cloning feature. For more information about cloning the connector, see Section 2.5, "Postcloning Steps."

You may want to configure the connector for multiple installations of Microsoft Active Directory. The following example illustrates this requirement:

The Tokyo, London, and New York offices of Example Multinational Inc. have their own installations of Microsoft Active Directory. The company has recently installed Oracle Identity Manager, and they want to configure Oracle Identity Manager to link all the installations of Microsoft Active Directory.

To meet the requirement posed by such a scenario, you must configure the connector for multiple installations of Microsoft Active Directory.

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

See Also:

Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for detailed instructions on performing each step of this procedure

Create IT resources of the Active Directory IT resource type so that there is one IT resource for each installation of the target system.

See Section 2.2.1.2, "Configuring the IT Resource for the Target System" for information about the values to be specified for the IT resource parameters.
Create copies of the reconciliation scheduled tasks for each installation of the target system. While creating a scheduled task, specify attribute values corresponding to the target system installation for which you are creating the scheduled task.

See Section 3.3.4, "Reconciliation Scheduled Jobs" for information about the values to be specified for the scheduled task attributes.
Manually synchronize the lookup definitions in Oracle Identity Manager with the lookup field values on the target system.

Before you perform provisioning operations:

The User Principal Name field on the process form is pre-populated with values from the User ID field and the UPN Domain IT resource parameter. Before you switch to a different IT resource during a provisioning operation, you must change the IT resource to which the User Principal Name field is mapped.

Expand Development Tools, and double-click Form designer.
Search for and open the AD User form.
On the Pre-Populate tab, double-click the User Principal Name row.
In the Pre-Population adapter dialog box, double-click the IT resource that you are currently using (for example, Active Directory).
From the Qualifier list in the Map Adapter Variables dialog box, select the IT resource that you want to use. For example, select Active Directory. Then, click the Save icon and close the dialog box.
In the Pre-Population adapter dialog box, click the Save icon and close the dialog box.
Click the Save icon on the Form Designer form.

When you perform provisioning operations:

When you use the Administrative and User Console to perform provisioning, you can specify the IT resource corresponding to the Microsoft Active Directory installation to which you want to provision the user.