14 Upgrading to Oracle Identity Manager 9.0.1 from Version 9.0.0

Oracle Identity Manager has formerly been known as both Oracle Xellerate Identity Provisioning and also Thor Xellerate Identity Manager. The Oracle Identity Manager Audit and Compliance module, formerly known as Oracle Xellerate Audit and Compliance Manager, is a new, optional module that installs on top of Oracle Identity Manager and facilitates user profile auditing.

This chapter describes upgrading from Oracle Xellerate Identity Provisioning 9.0.0 to Oracle Identity Manager version 9.0.1, with optional addition of the Oracle Identity Manager Audit and Compliance.

The Oracle Identity Manager 9.0.0 upgrade package is contained in upg_900_to_901.zip. Extract the contents of this package to a temporary directory on the machine where you plan to install Oracle Identity Manager 9.0.1. Henceforth, this document refers to this temporary directory as <Patch>.

Important:

The Oracle Identity Manager 9.0.0 to 9.0.1 upgrade for JBoss is supported only for environments using SQL Server as a database.

Upgrade Overview

The following is an overview of the process for upgrading to Oracle Identity Manager version 9.0.1 from Oracle Xellerate Identity Provisioning 9.0.0:

Upgrade the database you used for Oracle Xellerate Identity Provisioning 9.0.0. Refer to "Upgrading Your 9.0.0 Database to 9.0.1" for more information.
Perform the pre-upgrade configuration tasks. Refer to"Pre-Upgrade Configuration" for more information.
Perform the upgrade to Oracle Identity Manager 9.0.1. Refer to "Performing the Upgrade to 9.0.1" for more information.
Migrate any Oracle Xellerate Identity Provisioning 9.0.0 custom code, including custom clients, scheduled tasks, event handlers, and libraries bound to adapters to your new Oracle Identity Manager 9.0.1 environment. Refer to "Migrating Custom Code to 9.0.1" for more information.

Upgrading Your 9.0.0 Database to 9.0.1

Perform the following steps to upgrade your existing SQL Server database used for Oracle Xellerate Identity Provisioning 9.0.0:

Extract the contents of the Oracle Identity Manager 9.0.1 upgrade package (upg_900_to_901.zip) to a temporary directory on the machine where you plan to install Oracle Identity Manager 9.0.1. Henceforth, this document refers to this temporary directory as <Patch>.
Backup your existing SQL Server database. Use the utilities provided with your SQL Server database to perform a complete backup of your production database. Production database backup includes, but is not limited to, complete export or backup of the Oracle Xellerate Identity Provisioning 9.0.0 database instance to ensure that no data is lost during the upgrade process. If the upgrade fails, this backup can be used to restore the database to its original state.
Verify your existing SQL Server database configuration is properly configured. Consult "Setting Up the SQL Server" or your SQL Server documentation for more information if needed.
Upgrade your database schema from Oracle Xellerate Identity Provisioning 9.0.0 to Oracle Identity Manager 9.0.1 by using the upg_900_to_901.bat script. Be sure to run the script on the machine where the database resides.
1. Run the <Patch>\Database\SQLServer\Scripts\upg_900_to_901.bat batch file.
Note:
Refer to "Executing the SQL Server Upgrade Script" for more information on executing this script on an SQL Server database.
New stored procedures have been introduced in Oracle Identity Manager 9.0.1. Perform the following steps to create the required stored procedures for your SQL Server database:
1. Launch a plain-text editor and open the <Patch>/Database/SQLServer/StoredProcedures/compile_all_XL_SP.bat file.
2. For every stored procedure listed in the Sequential Lists section of compile_all_XL_SP.bat, replace the @sysuser string with the database user name. This is necessary because SQL Server requires functions invoked from a stored procedure to be qualified by the database user name (owner).
3. Go to the <Patch>/Database/SQLServer/StoredProcedures/ directory and run the compile_all_XL_SP.bat batch file.
  
  Note:
  Refer to "Executing the SQL Server Upgrade Script" for more information on executing this script on an SQL Server database.
To upgrade and enable the optional Oracle Identity Manager Audit and Compliance module, perform the following steps:

Note:
This step is necessary only if you are upgrading the 9.0.0 version of the Audit and Compliance module to the 9.0.1 version of the Audit and Compliance module.
1. Run the <Patch>/Database/SQLServer/Scripts/SQLServer_Enable_XACM.bat batch file.
  
  Note:
  Refer to "Executing the SQL Server Upgrade Script" for more information on executing this script on an SQL Server database.
The user profile auditing feature and the reports feature introduced in Oracle Identity Manager 9.0.1 require that certain metadata be loaded into the database. As appropriate for the operating system on the machine hosting your Oracle Identity Manager server, load Oracle Identity Manager metadata into your database by executing one of the following:

Windows
1. Run the <Patch>\Database\Utilities\LoadXML.bat batch file.
Linux
1. Run the <Patch>/Database/Utilities/LoadXML.sh batch file.
Note:
Refer to "Loading Metadata into the Database" before executing this script.

Pre-Upgrade Configuration

Before you upgrade to the Oracle Identity Manager 9.0.1, you must prepare for the upgrade by performing pre-upgrade configuration tasks to the following components:

Oracle Identity Manager Server
Remote Manager
Design Console

Pre-Upgrade Configuration for the Oracle Identity Manager Server

Prepare the Oracle Identity Manager Server for upgrade to 9.0.1 by updating 9.0.0 libraries, scripts, and configuration files using the following steps:

Important:

If upgrading from a clustered JBoss environment, perform the following steps on all cluster members, including the model node.

Backup the following directories.
- <XL_900_HOME>\xellerate\ext
- <XL_900_HOME>\xellerate\config
- <XL_900_HOME>\xellerate\DDTemplates
- <XL_900_HOME>\xellerate\lib
- <XL_900_HOME>\xellerate\setup
- <XL_900_HOME>\xellerate\webapp
- <XL_900_HOME>\xellerate\bin
- <XL_900_HOME>\documentation

Copy the directories and files listed in the location of the From column in the following table to the location listed in the To column in the following table. Overwrite the existing files in the To location if necessary.

Table 14-1 Oracle Identity Manager Server Pre-Upgrade Files to Copy

Copy From....	To
Patch\xellerate\DDTemplates	<XL_HOME>\xellerate\DDTemplates
Patch\xellerate\lib	<XL_HOME>\xellerate\lib
Patch\xellerate\webapp	<XL_HOME>\xellerate\webapp
Patch\xellerate\bin	<XL_HOME>\xellerate\bin
Patch\xellerate\config	<XL_HOME>\xellerate\config
Patch\documentation	<XL_HOME>\documentation
Patch\xellerate\ext\nexaweb-common.jar	<XL_HOME>\xellerate\ext
Patch\xellerate\readme.htm	<XL_HOME>

Copy the following files from Patch\xellerate\setup to <XL_HOME>\xellerate\setup:
- setup.xml
- patch_jboss.cmd
- patch_jboss.sh
- jboss-setup.xml

Modify the <XL_HOME >/xellerate/config/xlconfig.xml file as follows:

Locate the parameter <xl-configuration>.<Offlining>. .<MessageHandlerMDB>.<message-handler-task>.

Note:
Refer to "Conventions" for more information on identifying and locating xml tags.

Insert the following block of lines:
```
<ProcessOfflineMessage>com.thortech.xl.schedule.jms.processOfflineProcesses.processOfflinedProvisioningProcesses</ProcessOfflineMessage>
<ProcessTaskOfflineMessage>com.thortech.xl.schedule.jms.processTaskOffline.processOfflinedProcessTask</ProcessTaskOfflineMessage>
```
after the string:
<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<ReconOfflineMessage>

but before the string:
<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<TestMessage>

Locate the configuration parameter <xl-configuration>.<Offlining>.

Note:

Refer to "Conventions" for more information on identifying and locating xml tags.

Insert the following block of lines:

<process_offline_queue>
       <queueName>queue/xlQueue</queueName>
       <autoAcknowledge>true</autoAcknowledge>
       <replyTo></replyTo>
       <persistentFlag>true</persistentFlag>
       <disableMessageId>true</disableMessageId>
       <disableTimeStampe>false</disableTimeStampe>
        <messageEncrypt>false</messageEncrypt>
</process_offline_queue>
<process_task_offline_queue>
    <queueName>queue/xlQueue</queueName>
     <autoAcknowledge>true</autoAcknowledge>
     <replyTo></replyTo>
     <persistentFlag>true</persistentFlag>
     <disableMessageId>true</disableMessageId>
     <disableTimeStampe>false</disableTimeStampe>
     <messageEncrypt>false</messageEncrypt>
</process_task_offline_queue>

after the string:

<xl-configuration>.<Offlining>.</attestation_workflow_task_queue>

but before the string:

<xl-configuration>.<Offlining>.<test_queue>

Edit the <XL_HOME>/xellerate/setup/patch_jboss script as follows:

Windows

Edit patch_jboss.cmd and replace the following:
- replace @java_loc with the path to the Java installation directory
- replace @loc with the path to the Oracle Identity Manager server 9.0.1 installation directory
Linux

Edit patch_jboss.sh and replace the following:
- replace @loc with the path to the Oracle Identity Manager server 9.0.1 installation directory

Pre-Upgrade Configuration for the Design Console

Prepare the Oracle Identity Manager Design Console for upgrade to 9.0.1 by updating 9.0.0 libraries, scripts, and configuration files using the following steps:

Backup the following files and directories:
- <XL_900_DC_HOME>\xlclient\XLDesktopClient.ear<XL_900_DC_HOME>\xlclient\CustomClient.zip
- <XL_900_DC_HOME>\xlclient\xlFvcUtil.ear
- <XL_900_DC_HOME>\xlclient\lib
- <XL_900_DC_HOME>\xlclient\ext
- <XL_900_DC_HOME>\documentation
Copy the following files from Patch\xlclient\ to <XL_DC_HOME>\xlclient, overwriting existing files if necessary:
- Patch\xlclient\XLDesktopClient.ear
- Patch\xlclient\CustomClient.zip
- Patch\xlclient\xlFvcUtil.ear
Copy Patch\xellerate\ext\nexaweb-common.jar to XL_DC_HOME>\xellerate\ext, overwriting the existing file if necessary.
Copy the contents of the Patch\xlclient\lib directory to <XL_DC_HOME>\xlclient\lib, overwriting files if necessary.
Copy the contents of the Patch\documentation directory to <XL_DC_HOME>\documentation, overwriting files if necessary.
Copy Patch\xellerate\readme.htm to <XL_DC_HOME>\xlclient\, overwriting the existing file if necessary.

Pre-Upgrade Configuration for the Remote Manager

Prepare the Oracle Identity Manager Remote Manager for upgrade to 9.0.1 by updating 9.0.0 libraries, scripts, and configuration files using the following steps:

Backup the content of the following directories:
- <XL_900_RM_HOME>\xlremote\lib
- <XL_900_RM_HOME>\xlremote\config
Copy the contents of the Patch\xlremote\lib directory to the <XL_RM_HOME>\xlremote\lib directory, overwriting files if necessary.

Edit the xlconfig.xml file in the <XL_RM_HOME>/xlremote/config/ directory as follows:

Locate the parameter <xl-configuration>.<Offlining>. .<MessageHandlerMDB>.<message-handler-task>.

Note:
Refer to "Conventions" for more information on identifying and locating xml tags.

Insert the following block of lines:
```
<ProcessOfflineMessage>com.thortech.xl.schedule.jms.processOfflineProcesses.processOfflinedProvisioningProcesses</ProcessOfflineMessage>
<ProcessTaskOfflineMessage>com.thortech.xl.schedule.jms.processTaskOffline.processOfflinedProcessTask</ProcessTaskOfflineMessage>
```
after the string:
<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<ReconOfflineMessage>

but before the string:
<xl-configuration>.<Offlining>.<MessageHandlerMDB>.<message-handler-task>.<TestMessage>

Locate the configuration parameter <xl-configuration>.<Offlining>.

Note:

Refer to "Conventions" for more information on identifying and locating xml tags.

Insert the following block of lines:

<process_offline_queue>
       <queueName>queue/xlQueue</queueName>
       <autoAcknowledge>true</autoAcknowledge>
       <replyTo></replyTo>
       <persistentFlag>true</persistentFlag>
       <disableMessageId>true</disableMessageId>
       <disableTimeStampe>false</disableTimeStampe>
        <messageEncrypt>false</messageEncrypt>
</process_offline_queue>
<process_task_offline_queue>
    <queueName>queue/xlQueue</queueName>
     <autoAcknowledge>true</autoAcknowledge>
     <replyTo></replyTo>
     <persistentFlag>true</persistentFlag>
     <disableMessageId>true</disableMessageId>
     <disableTimeStampe>false</disableTimeStampe>
     <messageEncrypt>false</messageEncrypt>
</process_task_offline_queue>

after the string:

<xl-configuration>.<Offlining>.</recon_offline_queue>

but before the string:

<xl-configuration>.<Offlining>.<test_queue>

Performing the Upgrade to 9.0.1

Upgrading from an existing Oracle Xellerate Identity Provisioning 9.0.0 deployment to Oracle Identity Manager 9.0.1 involves assembling a new enterprise application archive (EAR) file from the latest libraries, then redeploying the EAR.

Perform the following steps after completing all the pre-upgrade tasks to upgrade an existing Oracle Xellerate Identity Provisioning 9.0.0 deployment to Oracle Identity Manager 9.0.1:

Make sure the JBoss application server is not running.

Run the patch_jboss script:

Windows

Run <XL_HOME>\xellerate\setup\patch_jboss.cmd

Linux

Run <XL_HOME>/xellerate/setup/patch_jboss.sh

Note:

If you are upgrading from a non-clustered version 9.0.0 Oracle Xellerate Identity Provisioning environment to a clustered version 9.0.1 Oracle Identity Manager environment, you must repeat these steps on each node in the cluster.

Migrating Custom Code to 9.0.1

In a version 9.0.1 environment, you can recycle custom code (including custom clients, scheduled tasks, event handlers and libraries bound to adapters) originally used in your version 9.0.0 environment.

Important:

Before migrating custom code from the 9.0.0 environment, the custom code must first be rebuilt using the Oracle Identity Manager 9.0.1 libraries.

Recompiling Custom Code

Custom code written for Oracle Xellerate Identity Provisioning 9.0.0 needs to be rebuilt using the Oracle Identity Manager 9.0.1 libraries, which are located in <XL_HOME>/xellerate/lib.

Using the integrated development environment (that is, Eclipse, JDeveloper, WASD or command line javac) that originally compiled the version 9.0.0 custom code, recompile all custom java code using Oracle Identity Manager 9.0.1 libraries instead of Oracle Xellerate Identity Provisioning 9.0.0 libraries.

Migrating Adapters

Custom java libraries bound to functional Oracle Xellerate Identity Provisioning 9.0.0 adapters can be reused in a Oracle Identity Manager 9.0.1 environment after they have been recompiled using Oracle Identity Manager 9.0.1 libraries.

The recompiled custom java libraries that were originally in the directory <XL_900_HOME>/xellerate/JavaTasks must be copied to the directory <XL_HOME>/xellerate/JavaTasks.

The recompiled custom java libraries that were originally in the directory <XL_900_RM_HOME> /xlremote/JavaTasks must be copied to the directory <XL_RM_HOME>/xlremote/JavaTasks.

Important:

If you are upgrading from a non-clustered to a clustered environment, you must repeat this step on all cluster members.

Note:

You do not need to recompile the adapters themselves.

Migrating Scheduled Tasks

Custom scheduled tasks that were functional in Oracle Xellerate Identity Provisioning 9.0.0 can be reused in your Oracle Identity Manager 9.0.1 environment after you have recompiled them using Oracle Identity Manager 9.0.1 libraries.

The recompiled custom scheduled tasks need to be copied to the directory <XL_HOME>/xellerate/ScheduleTask.

Note:

If you are upgrading from a non-clustered to a clustered environment, you must repeat this step on all cluster members.

Migrating Event Handlers

Custom event handlers that were functional in Oracle Xellerate Identity Provisioning 9.0.0 can be reused in your version 9.0.1 environment after you have recompiled them using Oracle Identity Manager 9.0.1 libraries.

The recompiled custom event handlers must be copied to the directory <XL_HOME> /xellerate/EventHandlers.

Note:

If upgrading from a non-clustered environment to a clustered environment then repeat this step on all cluster members.

Migrating xlWebApp Customizations

You must reapply any customizations (for example, JSP customizations) made to the Oracle Xellerate Identity Provisioning 9.0.0 web application to the 9.0.1 Oracle Identity Manager environment.

Migrate any customizations previously applied to your version 9.0.0 web application to the out-of-box version 9.0.1 web application xlWebApp.war, which resides in the directory <XL_HOME>/xellerate/webapp.

After migrating the 9.0.0 web application customizations, you must patch your version 9.0.1 web application. See Appendix B, "Patching an Existing Oracle Identity Manager Installation" for more information.

Migrating Custom Clients

Any custom clients that were built using Oracle Xellerate Identity Provisioning 9.0.0 APIs must be updated to make them compatible with the Oracle Identity Manager 9.0.1 APIs. For example, certain APIs might have been deprecated and replaced by new APIs. Refer to the Oracle Identity Manager Release Notes for a comprehensive list of API calls that have changed between Oracle Xellerate Identity Provisioning 9.0.0 and Oracle Identity Manager 9.0.1.

Upgrading the Diagnostic Dashboard

To upgrade your existing 9.0.0 Diagnostic Dashboard to version 9.0.1, you must install a new instance of the Diagnostic Dashboard. Use the following steps to upgrade to the 9.0.1 Diagnostic Dashboard:

Install a new instance of the XIMDD application using the new, version 9.0.1 XIMDD.war file in the Patch\DiagnosticDashboard directory
Refer to "Installing the Diagnostic Dashboard" for more information.