Upgrading the Microsoft Active Directory User Management Connector

7 Upgrading the Microsoft Active Directory User Management Connector

If you have already deployed 11.1.1.6.0 version of this connector, then you can upgrade the connector to version 12.2.1.3.0.

Note:

The connector upgrade from version 11.1.1.6.0 to 12.2.1.3.0 is only supported in the CI-based mode.
Before you perform the upgrade procedure, it is strongly recommended that you create a backup of the Oracle Identity Governance database. Refer to the database documentation for information about creating a backup.
As a best practice, first perform the upgrade procedure in a test environment.

7.1 Preupgrade Steps

You must perform the following preupgrade steps to prepare your environment for upgrading the connector:

Perform a reconciliation run to fetch all latest updates to Oracle Identity Governance.
Perform the preupgrade procedure documented in Managing Connector Lifecycle of Oracle Fusion Middleware Administering Oracle Identity Governance.
On the target system, obtain the maximum value of the uSNChanged attribute as follows:
1. If you are using the connector across multiple domains, then on the domain controller on which the Global Catalog Server is running, navigate to RootDSE, and then look for the RootDSE properties.
2. If you are using the connector in a single domain, then on the domain controller used for reconciliation, navigate to RootDSE, and then look for the RootDSE properties.
3. In the RootDSE properties dialog box, search for the highestCommittedUSN attribute, and note down its value. The use of this value is described later in this chapter. shows the RootDSE properties dialog box in which the highestCommittedUSN attribute is displayed.
  
  Figure 7-1 RootDSE Properties Dialog Box
  
  Description of "Figure 7-1 RootDSE Properties Dialog Box"
Define the source connector (an earlier release of the connector that must be upgraded) in Oracle Identity Governance. You define the source connector to update the Deployment Manager XML file with all customization changes made to the connector. See Managing Connector Lifecycle of Oracle Fusion Middleware Administering Oracle Identity Governance for more information.

7.2 Upgrade Steps

This is a summary of the procedure to upgrade the connector for both staging and production environments.

Depending on the environment in which you are upgrading the connector, perform one of the following steps:

Development Environment

Perform the upgrade procedure by using the wizard mode.
Staging or Production Environment

Perform the upgrade procedure by using the silent mode. In the silent mode, use the silent.xml file that is exported from the development environment.

See Managing Connector Lifecycle of Oracle Fusion Middleware Administering Oracle Identity Governance for detailed information about the wizard and silent modes.

7.3 Postupgrade Steps

Postupgrade steps involve uploading new connector jars, configuring the upgraded IT resource of the source connector, deploying the Connector Server, and configuring the latest token value of the scheduled job.

The following sections describe the procedures that you must perform after the upgrade operation:

7.3.1 Performing Postupgrade Steps

Postupgrade steps involves performing the following procedure to conclude the upgrade operation:

Perform the postupgrade procedure documented in Managing Connector Lifecycle of Oracle Fusion Middleware Administering Oracle Identity Governance.
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 activate a sandbox. See Creating and Activating a Sandbox for more information.
3. Create a new UI form to view the upgraded 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 2.c), and then save the application instance.
5. Publish the sandbox. See Publishing a Sandbox for more information.
If you are using Oracle Identity Governance release 11.1.2.x or later and you are upgrading from release 11.1.1.5.0 to 11.1.1.6.0, then perform the following procedure to remove the auxiliary class child form (from the AD User form) that is retained after upgrade:
1. Create a new version of the upgraded AD User form.
2. Delete the UD_ADUSRCLS child form, and make the version active.
3. Run the FVC utility using this newly created form. See Step 4 for detailed information on running FVC utility.
Run the Form Version Control (FVC) utility to manage user data changes on a form after an upgrade operation. To do so:
1. In a text editor, open the fvc.properties file located in the OIM_DC_HOME directory and include the following entries:
```
ResourceObject;AD User
FormName;UD_ADUSER
FromVersion;SPECIFY_THE_VERSION_OF_THE_FORM_USED_BY_USER_ACCOUNTS_CREATED_BY_USING_THE_SOURCE_CONNECTOR
ToVersion;SPECIFY_THE_VERSION_OF_FORM_THAT_IS_IN_THE_ACTIVE_STATUS_AFTER_THE_UPGRADE
ParentParent;UD_ADUSER_AD;UD_ADUSER_SERVER
```
  Note:
  
  To determine values for the FromVersion and ToVersion attributes, see Determining Values For the FromVersion and ToVersion Attributes.
  
  To verify whether you are specifying the correct process form associated with the resource object, perform the procedure described in Verifying If the Correct Process Form is Associated With the Resource Object.
2. Run the FVC utility. This utility is copied into the following directory when you install the design console:
  
  For Microsoft Windows:
  
  OIM_DC_HOME/fvcutil.bat
  
  For UNIX:
  
  OIM_DC_HOME/fvcutil.sh
  
  When you run this utility, you are prompted to enter the login credentials of the Oracle Identity Governance administrator, and the logger level and log file location.

To manage AD Group form changes after an upgrade operation, run the FVC utility by performing the instructions in step 4.a and 4.b with the following difference:

While perform Step 4.a, replace the entry added in Step 4.a with the following:

ResourceObject;AD Group
FormName;UD_ADGRP
FromVersion;SPECIFY_THE_VERSION_OF_THE_FORM_USED_BY_USER_ACCOUNTS_CREATED_BY_USING_THE_SOURCE_CONNECTOR
ToVersion;SPECIFY_THE_VERSION_OF_FORM_THAT_IS_IN_THE_ACTIVE_STATUS_AFTER_THE_UPGRADE
ParentParent;UD_ADGRP_ADSERVER;UD_ADGRP_SERVER

To manage AD Organization Unit form changes after an upgrade operation, run the FVC utility by performing the instructions in step 4.a and 4.b with the following difference:

While perform Step 4.a, replace the entry added in Step 4.a with the following:

ResourceObject;AD Organizational Unit
FormName;UD_OU
FromVersion;SPECIFY_THE_VERSION_OF_THE_FORM_USED_BY_USER_ACCOUNTS_CREATED_BY_USING_THE_SOURCE_CONNECTOR
ToVersion;SPECIFY_THE_VERSION_OF_FORM_THAT_IS_IN_THE_ACTIVE_STATUS_AFTER_THE_UPGRADE
ParentParent;UD_OU_AD;UD_OU_SERVER

If you are upgrading the connector from release 11.1.1.5.0 to 11.1.1.6.0, then run the PostUpgradeScript.sql script as follows:
Note:
- Skip performing this step if you upgrading the connector directly from release 9.1.x to 11.1.1.6.0.
- If you first performed an upgrade from release 9.1.x to 11.1.1.5.0, and then are upgrading from release 11.1.1.5.0 to 11.1.1.6.0, then in the PostUpgradeScript.sql file, replace "ADOU" with "OU", and then run the script.
1. Connect to the Oracle Identity Governance database by using the OIM User credentials.
2. Run the PostUpgradeScript.sql located in the ConnectorDefaultDir/AD_PACKAGE/upgrade directory.
Deploy the Connector Server.
Re-configure the IT resource of the source connector (an earlier release of the connector that must be upgraded).
Configure the latest token value of the scheduled job as follows:

The following scheduled jobs contain the Latest Token attribute:

Active Directory User Target Recon

Active Directory User Trusted Recon

Active Directory Group Recon

Active Directory Organization Recon

After upgrading the connector, you can perform either full reconciliation or incremental reconciliation. To perform incremental reconciliation, specify the value of the highestCommittedUSN attribute (noted in Preupgrade Steps) as the value of the Latest Token attribute. This ensures that records created or modified since the last reconciliation run (the one that you performed in Preupgrade Steps) are fetched into Oracle Identity Governance. From the next reconciliation run onward, the reconciliation engine automatically enters a value for the Latest Token attribute.

See Performing Full Reconciliation and Incremental Reconciliation for more information about performing full or incremental reconciliation.
Configure the sync token value of the scheduled job as follows:

The following scheduled jobs contain the Sync Token attribute:

Active Directory User Target Delete Recon

Active Directory User Trusted Delete Recon

Active Directory Group Delete Recon

After upgrading the connector, you can perform either full delete reconciliation or incremental delete reconciliation. To perform full delete reconciliation, you must not specify any value for the Sync Token attribute of the scheduled job. To perform incremental delete reconciliation, you must specify the value of the Sync Token attribute in the following format:

<String>0|{uSNChanged}|{True/False}|{DOMAIN_CONTROLLER}</String>

In this format, replace:
- {uSNChanged} with the value of the highestCommittedUSN attribute noted in Preupgrade Steps.
- {True/False} with one of the following values:
  - True if the Global Catalog Server is used during delete reconciliation runs
  - False if the Global Catalog Server is not used during delete reconciliation runs
- {DOMAIN_CONTROLLER} with the name of the domain controller on which you located RootDSE while performing the procedure described in Preupgrade Steps.

7.3.2 Determining Values For the FromVersion and ToVersion Attributes

To determine values for the FromVersion and ToVersion attributes:

Log in to the Design Console.
Expand Development Tools and then double-click Form Designer.
Search for and open the form whose version you are trying to determine. For example, UD_ADUSER.
In the Version Information region, search for and note down the value of the Active Version field, for example, initial version. This is the value of the ToVersion attribute.
In the Operations region, click the Current Version list, and note down the second highest value in the list, for example Immediate Version. This is the value of the FromVersion attribute.

7.3.3 Verifying If the Correct Process Form is Associated With the Resource Object

In the fvc.properties file, you might want to specify the process form name too. To verify whether you are specifying the correct process form associated with the resource object:

Log in to the Design Console.
Expand Process Management and then double-click Process Definition.
Search for and open the process form associated with the resource object.
In the Form Assignment region, note down the value of the Table Name field. This value is name of the process form that is linked to the process definition and resource object.