Extending the Functionality of the Microsoft Active Directory User Management Connector

6 Extending the Functionality of the Microsoft Active Directory User Management Connector

You can extend the functionality of the connector to address your specific business requirements.

By default the connector is configured to perform a certain set of tasks. For addressing your specific business requirements, you can extend the functionality of the connector by performing the procedures described in the following sections:

6.1 Adding Custom Fields for Target Resource Reconciliation

You can add additional fields for user, group, or organizational unit reconciliation.

Note:

Binary attributes are not supported. Connector supports string, long, char, double, float, int, and bool attribute types of the Microsoft Active Directory target system.

6.1.1 Adding Custom Fields for Target Resource Reconciliation of Users

You can add additional fields for user 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.

To add a custom field for target resource reconciliation for users:

Log in to Identity Self Service as an administrator.
Click the Manage tab, and then click the Applications box to open the Applications page.
Search for and open the Active Directory Target application to which you want to add custom fields.
Select Schema and then click Add Attribute.
In the newly added row, add the new attribute name, the OIM Profile and target system attribute that it will map to, and so on. For example, enter values for the Display Name , Identity Attribute, Target Attribute , and Data Type fields. Then, select the Recon Field checkbox and any other reconciliation properties as required.
Click Apply to save the changes.
Log in to Oracle Identity System Administration as an administrator.
Create and activate a sandbox.
Select Form Designer.
Create a new form with the following values and then click Create:
1. In the Resource Type field, enter the Active Directory Target application to which you added custom fields.
2. In the Form Name field, enter a form name. If you add attributes incrementally to the application, then you must create new forms every time you add new attributes. Therefore, it is recommended that you include a version number in the form name.
Ensure that the newly created attribute is present in the list of attributes on the form and save the changes. Then, publish the sandbox.
Navigate to Application Instances and the search for and open the application instance associated with the application to which you added the new attributes.
From the Form dropdown, select the new version of the form you just created and then click Apply.

The newly added fields are now available to be added to the View and Modify forms of the application by creating a new Sandbox and using the normal customize forms process.

6.1.2 Adding Custom Fields for Target Resource Reconciliation of Groups and Organizational Units

You can add additional fields for group or organizational unit 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.

To add a custom field for target resource reconciliation:

Log in to the Oracle Identity Governance 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 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.
  
  Note that if you are adding a boolean field, then select String as the field type.
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 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 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_ADGRP_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.
If you are using Oracle Identity Governance release 11.1.2.x or later, then all changes made to the Form Designer of the Design Console must be done in a new UI form as follows:
1. Log in to Oracle Identity System Administration.
2. Create and active a sandbox. See Creating and Activating a Sandbox for more information.
3. Create a new UI form to view the newly added field along with the rest of the fields. See Creating a New UI Form for more information about creating a UI form.
4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form (created in Step 5.c), and then save the application instance.
5. Publish the sandbox. See Publishing a Sandbox for more information.
Create a reconciliation field mapping for the custom field in the provisioning process as follows:
1. Log in to the Design Console.
2. Expand Process Management and then double-click Process Definition.
3. Search for and open one of the following provisioning process:
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
4. On the Reconciliation Field Mappings tab of the provisioning process, click Add Field Map.
5. 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.
6. Double-click the Process Data field, and then select UD_ADGRP_DESCRIPTION.
7. Click Save and close the dialog box.
8. Click Save.

6.2 Adding New Multivalued Fields for Target Resource Reconciliation

You can add new multivalued fields for user, group, or organizational unit during target resource reconciliation.

Note:

Binary attributes are not supported. Connector supports string, long, char, double, float, int, and bool attribute types of the Microsoft Active Directory target system.

6.2.1 Adding New Multivalued Fields for Target Resource Reconciliation of Users

You can add multivalued fields for user reconciliation between Oracle Identity Governance and the target system.

Note:

This procedure can be applied to add user fields only.

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

To add a new multivalued field for target resource reconciliation:

On the Application On-Boarding UI, select the Active Directory Target application.
Select Schema and then click Add Attribute.
In the newly added row, enter values for the Display Name and Target Attribute fields.
To select a value for the Data Type field, click the drop-down and select String.
Select the Recon Field checkbox.
Click Advanced Settings denoted by three horizontal lines at the end of the row and select the Lookup checkbox.
In the List of values field, enter the name of the lookup definition and click OK.
Click Apply.

6.2.2 Adding New Multivalued Fields for Target Resource Reconciliation of Groups and Organizational Units

You can add multivalued fields for reconciliation of groups and organizational units between Oracle Identity Governance and the target system.

Note:

This procedure can be applied to add either 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 Governance natively.

To add a new multivalued field for target resource reconciliation:

Log in to the Oracle Identity Governance 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. shows the multivalued field added on a new form.
Figure 6-1

Figure 6-1 Multivalued Field Added on a New Form

Description of "Figure 6-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 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.
If you are using Oracle Identity Governance release 11.1.2.x or later, then all changes made to the Form Designer of the Design Console must be done in a new UI form as follows:
1. Log in to Oracle Identity System Administration.
2. Create and active a sandbox. See Creating and Activating a Sandbox for more information.
3. Create a new UI form to view the newly added field along with the rest of the fields. See Creating a New UI Form for more information about creating a UI form.
4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form (created in Step 4.c), and then save the application instance.
5. Publish the sandbox. See Publishing a Sandbox for more information.
Add the new multivalued field to the list of reconciliation fields in the resource object as follows:
1. Log in to the Design Console.
2. Expand Resource Management and then double-click Resource Objects.
3. Search for and open one of the following resource objects:
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
4. On the Object Reconciliation tab, click Add Field.
5. 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.
6. Click Save and then close the dialog box.
7. Right-click the newly created field and select Define Property Fields.
8. 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.
9. Click Save, and then close the dialog box. Figure 6-2 shows the new reconciliation field added in the resource object.
  
  Figure 6-2 New Reconciliation Field Added in the Resource Object
  
  Description of "Figure 6-2 New Reconciliation Field Added in the Resource Object"
10. 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 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.
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 groups: AD Group
  
  For organizational units: AD Organizational Unit
3. On the Reconciliation Field Mappings tab of the 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.

6.3 Adding Custom Fields for Provisioning

You can add additional fields while provisioning users, groups, or organizational units.

Note:

Binary attributes are not supported. Connector supports string, long, char, double, float, int, and bool attribute types of the Microsoft Active Directory target system.

6.3.1 Adding Custom Fields for Provisioning Users

You can add additional fields while provisioning users.

Note:

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

To add a custom field for provisioning users:

On the Application On-Boarding UI, select the Active Directory Target application.
Select Schema and then click Add Attribute.
In the newly added row, enter values for the Display Name and Target Attribute fields.
To select a value for the Data Type field, click the drop-down and select String.
Select the Provision Field checkbox.
Click Apply.

6.3.2 Adding Custom Fields for Provisioning Groups and Organizational Units

You can map additional attributes for provisioning apart from the default attributes.

To add a custom field for provisioning for groups and organizational units, perform the procedures listed in the following sections:

6.3.2.1 Adding a New Field on the Process Form

If you have added the field on the process form by performing Step 4 of Adding Custom Fields for Target Resource Reconciliation of Groups and Organizational Units, then you need not add the field again. If you have not added the field, then add it as follows:

Log in to the Oracle Identity Governance Design Console.
Expand Development Tools and then double-click Form Designer.
Search for and open one of the following process forms:

For groups: UD_ADGRP

For organizational units: UD_ADOU
Click Create New Version, and then click Add.
Enter the details of the field.

For example, if you are adding the Description field, enter UD_ADGRP_DESCRIPTION in the Name field, and then enter the rest of the details of this field.
Click Save and then click Make Version Active.

6.3.2.2 Replicating Form Designer Changes to a New UI Form

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

Log in to Oracle Identity System Administration.
Create and active a sandbox. See Creating and Activating a Sandbox for more information.
Create a new UI form to view the newly added field along with the rest of the fields. See Creating a New UI Form for more information about creating a UI form.
Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form (created in Step 3.c), and then save the application instance.
Publish the sandbox. See Publishing a Sandbox for more information.

6.3.2.3 Creating an Entry in the Provisioning Lookup Definition

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

Log in to the Oracle Identity Governance Design Console.
Expand Administration and then double-click Lookup Definition.
Search for and open one of the following lookup definitions:

For groups: Lookup.ActiveDirectory.GM.ProvAttrMap

For organizational units: Lookup.ActiveDirectory.OM.ProvAttrMap
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.

Note:

If the field added is Boolean, then enter the Decode value in the following format:

TARGET_ATTR_NAME=(OIM_PROCESS_FORM_FIELD_NAME=='1')?"TRUE":"FALSE"

For example, consider the target system attribute OCSUserEnabled and a field named OCSUserEnabled in the process form. In this case, the decode value of the OCSUserEnabled code key is as follows:

OCSUserEnabled=(OCSUserEnabled == '1') ? "TRUE":"FALSE"
Click Save.

6.3.2.4 Enabling Update Provisioning Operations on the Custom Field

After adding the custom field, you must enable update provisioning operations on that field as follows:

In the provisioning process, add a new task for updating the field as follows:
1. Expand Process Management and then double-click Process Definition.
2. Search for and open one of the following provisioning process:
  
  For groups: AD Group
  
  For organizational units: AD Organizational Unit
3. 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.
4. In the Task Properties section, select the following fields:
  
  Conditional
  
  Allow Cancellation while Pending
  
  Allow Multiple Instances
5. Click Save.
In the provisioning process, select the adapter name in the Handler Type section as follows:
1. Go to the Integration tab, click Add.
2. In the Handler Selection dialog box, select Adapter.
3. From the Handler Name column, select adpADIDCUPDATEATTRIBUTEVALUE.
4. 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.

If you are enabling update provisioning operations for a Group custom field, then repeat Steps 3 through 5 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

If you are enabling update provisioning operations for an Organizational Unit custom field, then repeat Steps 3 through 5 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.

6.3.2.5 Updating the Request Dataset

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

In a text editor, open the XML file located in the OIM_HOME/dataset/file directory for editing.
Add the AttributeReference element and specify values for the mandatory attributes of this element.
For example, while performing the procedure described in Adding a New Field on the Process Form, 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 the procedure described in Adding a New Field on the Process Form.
- For the type attribute, enter the value that you entered in the Variant Type column of the process form while performing the procedure described in Adding a New Field on the Process Form.
- For the widget attribute, enter the value that you entered in the Field Type column of the process form, while performing the procedure described in Adding a New Field on the Process Form.
- For the length attribute, enter the value that you entered in the Length column of the process form while performing the procedure described in Adding a New Field on 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.
While performing the procedure described in Adding a New Field on the Process Form, if you added more than one attribute on the process form, then repeat this step for each attribute added.
Save and close the XML file.

6.3.2.6 Clearing Content Related to Request Datasets from the Server Cache

Run the PurgeCache utility to clear content related to request datasets from the server cache.

See Running the PurgeCache Utility in Oracle Fusion Middleware Administering Oracle Identity Governance for more information about the PurgeCache utility.

6.3.2.7 Importing Request Datasets

Note:

Perform the procedure described in this section only if you have enabled request-based provisioning.

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

6.4 Adding New Multivalued Fields for Provisioning

You can add new multivalued fields for user, group, or organizational unit during a provisioning operation.

Note:

Binary attributes are not supported. Connector supports string, long, char, double, float, int, and bool attribute types of the Microsoft Active Directory target system.

6.4.1 Adding New Multivalued Fields for Provisioning Users

You can add multivalued fields for provisioning users between Oracle Identity Governance and the target system.

Note:

This procedure can be applied to add user fields only.

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

To add a new multivalued field for provisioning:

On the Application On-Boarding UI, select the Active Directory Target application.
Select Schema and then click Add Attribute.
In the newly added row, enter values for the Display Name and Target Attribute fields.
To select a value for the Data Type field, click the drop-down and select String.
Select the Provision Field checkbox.
Click Advanced Settings denoted by three horizontal lines at the end of the row and select the Lookup checkbox.
In the List of values field, enter the name of the lookup definition and click OK.
Click Apply.

6.4.2 Adding New Multivalued Fields for Provisioning Groups and Organizational Units

You can add new multivalued fields for provisioning.

Note:

Before starting the following procedure, perform Steps1 through 4 as described in Adding New Multivalued Fields for Target Resource Reconciliation of Groups and Organizational Units. If these steps have been performed while adding new multivalued fields for target resource reconciliation, then you need not repeat the steps.

To add new multivalued fields for provisioning:

6.4.2.1 Creating an Entry in the Provisioning Lookup Definition

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

Log in to the Oracle Identity Governance Design Console.
Expand Administration and double-click Lookup Definition.
Search for and open one of the lookup definitions:
- 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.
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.

6.4.2.2 Enabling Update Provisioning Operations on the Multivalued Field

Enable update provisioning operations on the multivalued field as follows:

Expand Process Management, and then double-click Process Definition.
Search for and open one of the following process definitions:

For groups: AD Group

For organizational units: AD Organizational Unit
Click Add and enter the task name and description. For example, enter Car License Insert as the task name and task description.
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
Click Save.
On the Integration tab in the AD User provisioning Process, click Add and then select Adapter. From the list of adapters, select adpADIDCUPDATECHILDTABLEVALUES.
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.

If you are enabling update provisioning operations on a Group multivalued field, then repeat Steps 8 through 10 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

If you are enabling update provisioning operations on an Organizational Unit multivalued field, then repeat Steps 8 through 10 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 1 through 15 with the following difference:

While performing Step 4, 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 1 through 15 with the following difference:

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

6.4.2.3 Updating the Request Dataset

Note:

Perform the procedure described in this section only if you have 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:

In a text editor, open the XML file located in the OIM_HOME/dataset/file directory for editing.
Add the AttributeReference element and specify values for the mandatory attributes of this element.
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.
Save and close the XML file.

6.4.2.4 Clearing Content Related to Request Datasets from the Server Cache

Note:

Perform the procedure described in this section only if you have enabled request-based provisioning.

Run the PurgeCache utility to clear content related to request datasets from the server cache. See Purging Cache in Oracle Fusion Middleware Administering Oracle Identity Governance for more information about the PurgeCache utility.

6.4.2.5 Importing Request Datasets

Note:

Perform the procedure described in this section only if you have enabled request-based provisioning.

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

6.5 Adding Terminal Services Fields for Reconciliation and Provisioning

You can add additional terminal services fields for reconciliation and provisioning operations.

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.

6.6 Adding the Group Name (pre-Windows 2000) Attribute

You can add a group name (pre-Windows 200) attribute for reconciliation and provisioning.

This section discusses the following topics related to adding the Group Name (pre-Windows 2000 ) attribute for reconciliation and provisioning:

6.6.1 About the Group Name (pre-Windows 2000) Attribute

Group Name and Group Name (pre-Windows 2000) are two of the attributes specific to groups in the target system.

Oracle Identity Governance contains only the Group Name field in its process form. By default, during group provisioning, the value that you specify for the Group Name field in the OIM process form, is entered as the value of the Group Name and Group Name (pre-Windows 2000) attributes. If you want to specify different values for the Group Name and Group Name (pre-Windows 2000) attributes in the target system, then you must create the Group Name (pre-Windows 2000) field on the OIM process form. To do so, you must add a new field (Group Name Pre Windows) in Oracle Identity Governance for reconciliation and provisioning operations.

6.6.2 Adding the Group Name Pre Windows Field for Reconciliation

You can add the Group Name Pre Windows field for reconciliation.

To do so, perform the following procedure:

Log in to the Oracle Identity Governance Design Console.
Add the Group Name Pre Windows 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 the AD Group resource object.
3. On the Object Reconciliation tab, click Add Field.
4. In the Add Reconciliation Field dialog box, enter Group Name Pre Windows 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.

Update the Lookup.ActiveDirectory.GM.ReconAttrMap lookup definition for reconciliation as follows:

Expand Administration and then double-click Lookup Definition.
Search for and open the Lookup.ActiveDirectory.GM.ReconAttrMap lookup definition.
Click Add to create an entry for the Group Name Pre Windows field.
In the Code Key column, enter Group Name Pre Windows. In the Decode column, enter sAMAccountName.

In the Code Key column, locate Group Name and change its Decode value to cn. Table 6-1 lists the updated list of entries in the Lookup.ActiveDirectory.GM.ReconAttrMap lookup definition.

Table 6-1 Entries in the Updated Lookup.ActiveDirectory.GM.ReconAttrMap Lookup Definition

Group Field on Oracle Identity Governance	Microsoft Active Directory Field
Display Name	displayName
Group name	cn
Group Name Pre Windows	sAMAccountName
Group Type	groupType
OIM Org Name	sAMAccountName
Organization Name[LOOKUP]	ad_container
Org Name	sAMAccountName
Org Type	OIM Organization Type
Unique Id	__UID__

Click Save.

Add the Group Name Pre Windows field on the process form as follows:
1. Expand Development Tools and then double-click Form Designer.
2. Search for and open the UD_ADGRP process form.
3. Click Create New Version, and then click Add.
4. Enter the details of the new field. In the Name field, enter UD_ADUSER_GROUPNAME_PREWINDOWS. In the Field Label column, enter Group Name Pre Windows. Enter the rest of the details of this field.
5. On the Properties tab, select the Group Name Pre Windows field, and then click Add Property. The Add Property dialog box displays.
6. From the Property Name list, select Required.
7. In the Property Value field, enter True.
8. Click the Save icon and close the dialog box.
9. Click Save and then click Make Version Active.
Create a reconciliation field mapping for the new field in the provisioning process as follows:
1. Expand Process Management and then double-click Process Definition.
2. Search for and open the AD Group provisioning process.
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 Group Name Pre Windows.
5. Double-click the Process Data field, and then select UD_ADGRP_GROUPNAME_PREWINDOWS.
6. Click Save and close the dialog box.
7. Click Save.
Expand Resource Management and then double-click Resource Objects.
Click Create Reconciliation Profile.

6.6.3 Adding the Group Name Pre Windows Field for Provisioning

You can add the Group Name Pre Windows field for provisioning.

To do so, perform the following procedures:

6.6.3.1 Adding the Group Name Pre Windows Field

If you have added the field on the process form by performing Step 4 of Adding the Group Name Pre Windows Field for Reconciliation, then you need not add the field again. If you have not added the field, then:

Log in to the Oracle Identity Governance Design Console.
Expand Development Tools and then double-click Form Designer.
Search for and open the UD_ADGRP process form.
Click Create New Version, and then click Add.
In the Name field, enter UD_ADUSER_GROUPNAME_PREWINDOWS.
In the Field Label column, enter Group Name Pre Windows. Then, enter values for the rest of the columns as listed for the Group Name field.
On the Properties tab, select the Group Name Pre Windows field, and then click Add Property. The Add Property dialog box displays.
From the Property Name list, select Required.
In the Property Value field, enter True.
Click the Save icon and close the dialog box.
Click Save and then click Make Version Active.

6.6.3.2 Updating the Lookup.ActiveDirectory.GM.ProvAttrMap Lookup Definition

Update the Lookup.ActiveDirectory.GM.ProvAttrMap lookup definition for provisioning as follows:

Expand Administration and then double-click Lookup Definition.
Search for and open the Lookup.ActiveDirectory.GM.ProvAttrMap lookup definition.
Click Add to create an entry for the Group Name Pre Windows field.
In the Code Key column, enter Group Name Pre Windows. In the Decode column, enter sAMAccountName.

In the Code Key column, locate and replace Group Name with Group Name[IGNORE], and change its Decode value to IGNORED. Table 6-1 lists the updated list of entries in the Lookup.ActiveDirectory.GM.ProvAttrMap lookup definition.

Table 6-2 Entries in the Updated Lookup.ActiveDirectory.GM.ProvAttrMap Lookup Definition

Group Field on Oracle Identity Governance	Microsoft Active Directory Field
__NAME__	__NAME__="CN=${Group_Name},${Organization_Name}"
Display Name	displayName
Group Name[IGNORE]	IGNORED
Group Name Pre Windows	sAMAccountName
Group Type	groupType
Organization Name[LOOKUP,IGNORE]	IGNORED
Unique Id	__UID__

Click Save.

6.6.3.3 Enabling Update Provisioning Operations on the Group Name Pre Windows Field

Enable update provisioning operations on the Group Name Pre Windows field as follows:

In the provisioning process, add a new task for updating the field as follows:
1. Expand Process Management and then double-click Process Definition.
2. Search for and open the AD Group provisioning process.
3. Click Add and enter the task name and task description as follows:
  
  Task Name: Group Name Pre Windows Updated
  
  Task Description: Process Task for handling update of the Group Name Pre Windows field.
4. In the Task Properties section, select the Conditional, Allow Cancellation while Pending, and Allow Multiple Instances fields.
5. Click Save.
In the provisioning process, select the adapter name in the Handler Type section as follows:
1. Go to the Integration tab, click Add.
2. In the Handler Selection dialog box, select Adapter.
3. From the Handler Name column, select adpADIDCUPDATEATTRIBUTEVALUE.
4. 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.

Repeat Steps 3 through 5 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	Group Name Pre Windows
objectType	Literal	String	Group

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.

6.6.3.4 Updating Adapters

If the Group Name Updated process task calls the adpADIDCUPDATEATTRIBUTEVALUES adapter, then:

Remove the adpADIDCUPDATEATTRIBUTEVALUES adapter and add the adpADIDCUPDATEATTRIBUTEVALUE adapter.
On the Integration tab, 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.

Repeat Steps 2 through 4 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	Group Name
objectType	Literal	String	Group

6.6.3.5 Updating the Request Dataset

Note:

Perform the procedures described in this section only if you want to perform 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:

In a text editor, open the XML file located in the OIM_HOME/dataset/file directory for editing.
Add the AttributeReference element and specify values for the mandatory attributes of this element.
For example, while performing the procedure described in Adding the Group Name Pre Windows Field, if you added Employee ID as an attribute on the process form, then enter the following line:
```
<AttributeReference
name = "GroupName PreWindows"
attr-ref = "Group Name Pre Windows"
type = "String"
widget = "text"
length = "70"
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_GROUPNAME_PREWINDOWS is the value in the Name column of the process form, then you must specify GroupName PreWindows 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 the procedure described in Adding the Group Name Pre Windows Field.
- For the type attribute, enter the value that you entered in the Variant Type column of the process form while performing the procedure described in Adding the Group Name Pre Windows Field.
- For the widget attribute, enter the value that you entered in the Field Type column of the process form, while performing the procedure described in Adding the Group Name Pre Windows Field.
- For the length attribute, enter the value that you entered in the Length column of the process form while performing the procedure described in Adding the Group Name Pre Windows Field.
- 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 the procedure described in Adding the Group Name Pre Windows Field if you added more than one attribute on the process form, then repeat this step for each attribute added.
Save and close the XML file.

6.6.3.6 Running the PurgeCache Utility

Note:

Perform the procedures described in this section only if you want to perform request-based provisioning.

6.6.3.7 Importing the Request Dataset Definitions into MDS

Note:

Perform the procedures described in this section only if you want to perform request-based provisioning.

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

6.7 Configuring Transformation and Validation Of Data

You can configure transformation and validation of data for users, groups, and organizations.

6.7.1 About Configuring Transformation and Validation of Data

Configure transformation and validation of user account data by writing Groovy script logic while creating your application.

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

Similarly, you can configure validation of reconciled and provisioned single-valued data according to your requirements. For example, you can validate data fetched from the First Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.

To configure transformation or validation of user account data, you must write Groovy scripts while creating your application. For more information about writing Groovy script-based validation and transformation logic, see Validation and Transformation of Provisioning and Reconciliation Attributes of Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

6.7.2 Configuring Transformation of Data During Reconciliation for Groups and Organizational Units

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

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 a 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) {}
```
Create a JAR file to hold the Java class.
Run the Oracle Identity Governance Upload JARs utility to post the JAR file to the Oracle Identity Governance database. This utility is copied into the following location when you install Oracle Identity Governance:

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 Governance administrator, URL of the Oracle Identity Governance 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.
Add an entry in the lookup definition for transformation as follows:
1. Log in to the Design Console.
2. Search for and open one of the following lookup definitions:
  - For groups: Lookup.ActiveDirectory.GM.ReconTransformation
  - For organizational units: Lookup.ActiveDirectory.OM.ReconTransformation
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.OM.Configuration.Trusted lookup definition:
- Code Key value: Recon Transformation Lookup
- Decode value: Lookup.ActiveDirectory.OM.ReconTransformation

6.7.3 Configuring Validation of Data During Reconciliation and Provisioning for Groups and Organizational Units

You can configure validation of reconciled and provisioned single-valued data according to your requirements. For example, you can validate data fetched from the First Name attribute to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.

To configure validation of data:

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

This validation class must implement the validate method.
Create a JAR file to hold the Java class.
Run the Oracle Identity Governance Upload JARs utility to post the JAR file to the Oracle Identity Governance database. This utility is copied into the following location when you install Oracle Identity Governance:

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 Governance administrator, URL of the Oracle Identity Governance 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.
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 one of the following lookup definitions:
  - For groups: Lookup.ActiveDirectory.GM.ReconValidation
  - For organizational units: Lookup.ActiveDirectory.OM.ReconValidation
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 one of the following lookup definitions:
  - For groups: Lookup.ActiveDirectory.GM.Configuration
  - For organizational units: Lookup.ActiveDirectory.OM.Configuration
6. Ensure that the value of the Recon Validation Lookup entry is set to one of the following:
  - For groups: Lookup.ActiveDirectory.GM.ReconValidation.
  - For organizational units: Lookup.ActiveDirectory.OM.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 one of the following lookup definitions:
  - For groups: Lookup.ActiveDirectory.GM.ProvValidation
  - For organizational units: Lookup.ActiveDirectory.OM.ProvValidation
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 one of the following lookup definitions:
  - For groups: Lookup.ActiveDirectory.GM.Configuration
  - For organizational units: Lookup.ActiveDirectory.OM.Configuration
6. Ensure that the value of the Provisioning Validation Lookup entry is set to one of the following:
  - For groups: Lookup.ActiveDirectory.GM.ProvValidation.
  - For organizational units: Lookup.ActiveDirectory.OM.ProvValidation.
7. Save the changes to the lookup definition.

6.8 Action Scripts

Actions are scripts that you can configure to run before or after the create, update, or delete an account provisioning operations.

For example, you can configure a script to run before every user creation. Similarly, you can run custom PowerShell scripts before or after creating, updating, or deleting a mailbox.

The following are topics pertaining to action scripts:

6.8.1 Action Scripts for Users

The following are topics pertaining to action scripts for users:

6.8.1.1 About Configuring Action Scripts for Users

You can configure Action Scripts by writing your own PowerShell scripts while creating your application.

These scripts can be configured to run before or after the create, update, or delete an account provisioning operations. For example, you can configure a script to run before every user creation operation.

For information on adding or editing action scripts, see Updating the Provisioning Configuration in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

Note:

The scripting language used is PowerShell.

6.8.1.2 Running a Custom PowerShell Script for Users

As an example, the following procedure describes the steps to run a custom PowerShell script before a create operation:

Select an application of your choice after creating it or while updating it.
Select Settings, User, and then Provisioning. All available action scripts are displayed.

Figure 6-3 Preview Settings for Action Scripts

Description of "Figure 6-3 Preview Settings for Action Scripts"
To view its contents, click any of the enabled action scripts.

Figure 6-4 Action Scripts

Description of "Figure 6-4 Action Scripts"
Set the value of the Target field to Resource only. The script is executed on the computer where the target system is running.

Click Edit, and then enter the following content in the Script field:

Powershell.exe -File NAME_AND_FULL_LOCATION_OF_THE_CUSTOM_SCRIPT
Exit

Sample value:

Powershell.exe -File C:\myscripts\CustomScript.ps1
Exit

Click Save and then click Apply to commit the action scripts to the database.
Log in to the computer running the connector server and create the custom script (in this example the customScript.ps1 script, located in the C:\myscripts directory) file with the following content:
```
$Class = "organizationalUnit"
$OU = "OU=ScriptOU81"
$objADSI = [ADSI]"LDAP://Dc=extest,DC=com"
$objOU = $objADSI.create($Class, $OU)
$objOU.setInfo()
```
This script runs before every create provisioning operation. This script creates an Organization named 'ScriptOU81'. Similarly, you can write custom scripts as per your requirement.
Note:
- If you are using a PowerShell script, then before running the script by using the connector or Oracle Identity Governance, verify the following on the computer running the connector server:
  - You must be able to connect manually to the AD server with the values specified in the script using the PowerShell window without any issues.
  - From the command prompt, navigate to the directory containing the batch file. Then, run the batch file with appropriate parameters and ensure that the PowerShell script runs on AD server without any issues.
- Process form fields marked as IGNORE are not sent to the connector.

6.8.1.3 Running Actions Using Visual Basic Scripts for Users

The following is an example procedure for running actions using Visual Basic scripts that consumes data dynamically from the process form. This is an example procedure for an After Create action, which requires creating a user in an organizational unit in addition to the one in which the user is provisioned to.

Create a file (a script) on the computer running Oracle Identity Governance with the following data:
```
C:\arg.vbs %givenName%
```
Note that there is a space between C:\arg.vbs and %givenName%.
On the machine hosting the target system, create a file in the C:\ directory. For example, create an arg.vbs file.

Include the following lines in the arg.vbs file:

Set args = WScript.Arguments
GivenNameFromArg = args.Item(0)
lengthGivenName = Len(GivenNameFromArg) - 2
GivenNameTrim = Mid(GivenNameFromArg, 2, lengthGivenName)
Set objOU = GetObject("LDAP://ausovm3194win.matrix.com:389/OU=TestOrg4,dc=matrix,dc=com")
Set objUser = objOU.Create("User", "cn=scriptCreate" & GivenNameTrim )
objUser.Put "givenName", "scriptCreate" & GivenNameTrim
objUser.Put "sAMAccountName", "scriptCreate " & GivenNameTrim
objUser.Put "userPrincipalName", "scriptCreate" & GivenNameTrim
objUser.Put "displayName", "scriptCreate" & GivenNameTrim
objUser.Put "sn", "scriptCreate" & GivenNameTrim
objUser.SetInfo

Save and close the file.
Provision a user account on Oracle Identity Governance.

6.8.1.4 Important Notes on Running Actions Scripts for Users

The following are important notes on running actions scripts:

Any errors encountered while running action scripts are ignored and are not propagated to Oracle Identity Governance.
During create operations, all attributes part of process form are available to the script.
During update operations, only the attribute that is being updated is available to the script.
During delete operations, only the __UID__ (GUID) attribute is available to the script.

6.8.1.5 Guidelines on Creating Scripts for Users

The following are the guidelines that you must apply or be aware of while configuring action scripts:

All field names used in the scripts must be enclosed within %%.
You can call any VB script from a shell and pass the process form fields.
You cannot include the Password field in the script. This is because password is stored as a guarded string. Therefore, we do not get the exact password when we fetch values for the Password field.
Addition of child table attributes belongs to the 'Update' category and not 'Create.'

6.8.2 Action Scripts for Groups and Organizational Units

The following are topics pertaining to action scripts for groups and organizational units:

6.8.2.1 About Configuring Action Scripts for Groups and Organizational Units

You can configure Action Scripts by writing your own PowerShell scripts while creating your application.

Note:

The scripting language used is PowerShell.

6.8.2.2 Running a Custom PowerShell Script for Groups and Organizational Units

As an example, the following procedure describes the steps to run a custom PowerShell script before a create operation:

Log in to the Design Console.
Search for and open one of the following lookup definitions:
- For groups: Lookup.ActiveDirectory.GM.Configuration
- For organizational units: Lookup.ActiveDirectory.OU.Configuration
Add the following new values:
- Code Key: TIMING Action Language
  
  Sample value: Before Create Action Language
- Decode: Enter the scripting language of the script you want to execute
  
  Sample value: Shell
Add these new values:
- Code Key: TIMING Action File
  
  Sample value: Before Create Action File
- Decode: Enter the full path of the batch file that invokes the script. (Oracle Identity Governance must be able to access this file.)
  
  Sample value: /scratch/Scripts/InvokeCustomScript.bat
Add these new values:
- Code Key: TIMING Action Target
  
  Sample value: Before Create Action Target
- Decode: Resource (do not modify this value)
Save the lookup definition.
On the computer running Oracle Identity Governance, create the /scratch/Scripts/InvokeCustomScript.bat file with the following content:
```
Powershell.exe -File NAME_AND_FULL_LOCATION_OF_THE_CUSTOM_SCRIPT
Exit
```
Sample value:
```
Powershell.exe -File C:\myscripts\CustomScript.ps1
Exit
```
Log in to the computer running the connector server and create the custom script (in this example the customScript.ps1 script, located in the C:\myscripts directory) file with the following content:
```
$Class = "organizationalUnit"
$OU = "OU=ScriptOU81"
$objADSI = [ADSI]"LDAP://Dc=extest,DC=com"
$objOU = $objADSI.create($Class, $OU)
$objOU.setInfo()
```
This script runs before every create provisioning operation. This script creates an Organization named 'ScriptOU81'. Similarly, you can write custom scripts as per your requirement.
Note:

If you are using a PowerShell script, then before running the script by using the connector or Oracle Identity Governance, verify the following on the computer running the connector server:
- You must be able to connect manually to the AD server with the values specified in the script using the PowerShell window without any issues.
- From the command prompt, navigate to the directory containing the batch file. Then, run the batch file with appropriate parameters and ensure that the PowerShell script runs on AD server without any issues.

Note that you can pass process form fields to scripts that call the before or after action scripts. These process form fields must be present in Lookup.ActiveDirectory.GM.ProvAttrMap or Lookup.ActiveDirectory.OU.ProvAttrMap lookup definitions and be mapped to a corresponding target system attribute. For example, you can pass the First Name process form field (present in Lookup.ActiveDirectory.GM.ProvAttrMap or Lookup.ActiveDirectory.OU.ProvAttrMap lookup definitions) to an action script by specifying "givenName," which is the name of the corresponding attribute in the target system.

Note:

Process form fields marked as IGNORE are not sent to the connector.

6.8.2.3 Running Actions Using Visual Basic Scripts for Groups and Organizational Units

Create a file (a script) on the computer running Oracle Identity Governance with the following data:
```
C:\arg.vbs %givenName%
```
Note that there is a space between C:\arg.vbs and %givenName%.
On the machine hosting the target system, create a file in the C:\ directory. For example, create an arg.vbs file.

Include the following lines in the arg.vbs file:

Set args = WScript.Arguments
GivenNameFromArg = args.Item(0)
lengthGivenName = Len(GivenNameFromArg) - 2
GivenNameTrim = Mid(GivenNameFromArg, 2, lengthGivenName)
Set objOU = GetObject("LDAP://ausovm3194win.matrix.com:389/OU=TestOrg4,dc=matrix,dc=com")
Set objUser = objOU.Create("User", "cn=scriptCreate" & GivenNameTrim )
objUser.Put "givenName", "scriptCreate" & GivenNameTrim
objUser.Put "sAMAccountName", "scriptCreate " & GivenNameTrim
objUser.Put "userPrincipalName", "scriptCreate" & GivenNameTrim
objUser.Put "displayName", "scriptCreate" & GivenNameTrim
objUser.Put "sn", "scriptCreate" & GivenNameTrim
objUser.SetInfo

Save and close the file.
Provision a user account on Oracle Identity Governance.

6.8.2.4 Important Notes on Running Actions Scripts for Groups and Organizational Units

The following are important notes on running actions scripts:

Any errors encountered while running action scripts are ignored and are not propagated to Oracle Identity Governance.
During create operations, all attributes part of process form are available to the script.
During update operations, only the attribute that is being updated is available to the script.

If other attributes are also required, then a new adapter calling ICProvisioningManager# updateAttributeValues(String objectType, String[] labels) must be created and used. During adapter mapping in process task, add the form field labels of the dependent attributes.
During delete operations, only the __UID__ (GUID) attribute is available to the script.

6.8.2.5 Guidelines on Creating Scripts for Groups and Organizational Units

The following are the guidelines that you must apply or be aware of while configuring action scripts:

Your script file can contain scripts that include attributes present in the decode column of any of the following lookup definitions:
- Lookup.ActiveDirectory.GM.ProvAttrMap
- Lookup.ActiveDirectory.OM.ProvAttrMap
All field names used in the scripts must be enclosed within %%.
You can call any VB script from a shell and pass the process form fields.
You cannot include the Password field in the script. This is because password is stored as a guarded string. Therefore, we do not get the exact password when we fetch values for the Password field.
Addition of child table attributes belongs to the 'Update' category and not 'Create.'

6.9 Enabling Reconciliation and Provisioning Operations Across Multiple Domains

The Microsoft Active Directory User Management connector supports reconciliation and provisioning operations across multiple domains in a single forest.

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.

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:

6.9.1 Understanding Enabling Reconciliation Across Multiple Domains

This following sections help you understand enabling reconciliation across multiple domains:

6.9.1.1 About 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 Governance, 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 Governance.

6.9.1.2 Enabling Reconciliation Across Multiple Domains

To enable reconciliation across multiple domains:

Set the value of the Search Child Domains parameter of Advanced Settings Parameters to yes.
Specify the name of the domain controller that is hosting the Global Catalog Server as the value of the Global Catalog Server parameter of the Basic Configuration Parameters section.

Note:

If the value of the Search Child Domains parameter is set to yes and no value is specified for the Global Catalog Server parameter, then the connector determines the Global Catalog Server on its own. It is strongly recommended that you specify a value for the Search Child Domains parameter in the Advanced Settings Parameters and the Global Catalog Server parameter in the Basic Configuration Parameters.
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.
It is recommended to not enter any value for LDAP Host Name parameter of the Basic Configuration Parameters section. The connector will automatically find the right domain controller to fetch complete user information after obtaining the distinguished name from the global catalog server. If you specify a value for the LDAP Host Name parameter, then the connector ignores it and determines the appropriate domain controller (for fetching user information) by using the ADSI referrals feature.

6.9.2 Understanding 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 LDAP Host Name parameter and 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.

6.10 About Using the Connector for Multiple Trusted Source Reconciliation

You can use the connector for more than one 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.

6.11 Multiple Installations of the Target System

You can use the Active Directory User Management connector in an environment containing multiple target systems.

The following are topics related to multiple target system installations:

6.11.1 About Multiple Installations of the Target System

You must create copies of configurations of your base application to configure it for multiple installations of the target system.

Note:

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

If you are upgrading from 11.1.2.x to 12.2.1.3.0, then:

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, if you are using Oracle Identity Governance release 12.2.1.3.0, then only the IT resource information must be changed. If you are using Oracle Identity Governance release 12.2.1.3.0, then the IT resource information must be changed and application instances must be created.

In addition, irrespective of the Oracle Identity Governance release that you are using, 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.
If you are using Application On-Boarding, then:

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, if you are using Oracle Identity Governance release 12.2.1.3.0, then the basic configuration information must be changed and a new application must be created.

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 create a new application.

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 Governance, and they want to configure Oracle Identity Governance 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.

6.11.2 Configuring the Connector for Multiple Installations of the Target System

You can configure the connector for multiple installations of the target system by upgrading the connector from Oracle Identity Governance release 11.1.2.x to 112.2.1.3.0 or through application on-boarding.

To configure the connector for multiple installations of the target system, perform one of the procedures listed in the following sections:

6.11.2.1 Configuring the Connector for Multiple Installations of the Target System while Upgrading from Oracle Identity Governance release 11.1.2.x to 12.2.1.3.0

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

Create IT resources of the Active Directory IT resource type so that there is one IT resource for each installation of the target system. If you are using Oracle Identity Governance release 12.2.1.3.0 or later, then in addition to creating the IT resource, you must create the application instance.
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.
Manually synchronize the lookup definitions in Oracle Identity Governance with the lookup field values on the target system.

6.11.2.2 Configuring the Connector for Multiple Installations of the Target System Using Application On-Boarding

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

Create a new application using application on-boarding for multiple installation of the target system.
Manually synchronize the lookup definitions in Oracle Identity Governance with the lookup field values on the target system.

6.12 Creating a Home Directory After User Create Provisioning Operation

You can initiate the process to update the home directory after the Create User provisioning operation.

To accomplish this task in Application On-Boarding, you must write a post-create Action Script and make the home directory creation changes in that script itself.

6.13 Configuring the Connector for Provisioning Groups of the Security Group - Universal Group Type

You can create a group of type Security Group - Universal by adding this group type to the Lookup.ActiveDirectory.GroupTypes lookup definition.

There are six types of groups that you can create in the target system. By default, this connector is shipped with only five group types that you can select for the group that you create through Oracle Identity Governance. If you want to create a group of type Security Group - Universal, then you must add this group type to the Lookup.ActiveDirectory.GroupTypes lookup definition as follows:

Log in to the Design Console.
Expand Administration, and then double-click Lookup Definition.
Search for and open Lookup.ActiveDirectory.GroupTypes lookup definition.
Click Add.
In the new row that is added, enter the following values:

Code Key: - 2147483640

Decode: Security Group - Universal
Click the Save icon.

You can now search for -2147483640 and select the Security Group - Universal group type while creating a group through Oracle Identity Governance.