4 Upgrading to Release 9.0.3 from Release 9.0.2 on WebSphere Application Servers

This chapter explains how to upgrade to Release 9.0.3 from Release 9.0.2 on WebSphere application servers—do not attempt to upgrade to Release 9.0.3 from any other previous Oracle Identity Manager release.

Note:

If you are a new Oracle Identity Manager customer and Release 9.0.3 is your initial deployment of the product, you can skip this chapter and simply run the Release 9.0.3 installer program to deploy Release 9.0.3.

Extract the contents of the Release 9.0.3 upgrade package to a temporary directory on your existing Release 9.0.2 system.

Note:

This document refers to this temporary directory as <PATCH>.

The following is a list of the steps in this section that explain how to upgrade from Release 9.0.2 to Release 9.0.3 on WebSphere:

1. Upgrading to WebSphere 5.1.1.12

2. Upgrading the Database for Oracle Identity Manager

   • Upgrading an Existing Database Instance In-Place

   • Creating a New Database Instance for the Upgrade

3. Preparing for the Upgrade

   1. Preparing the Oracle Identity Manager Server for Upgrade

   2. Preparing the Administrative and User Console for Upgrade

   3. Preparing the Design Console for Upgrade

   4. Preparing the Remote Manager for Upgrade

4. Performing the Upgrade

   1. Updating the Design Console xlDataObjectBeans.jar

5. Migrating Release 9.0.2 Custom Code

6. Upgrading the Diagnostic Dashboard

Upgrading to WebSphere 5.1.1.12

Release 9.0.3 is certified on the WebSphere 5.1.1.12 application server. You must upgrade to WebSphere 5.1.1.12 before upgrading to Release 9.0.3. Be sure to also upgrade the WebSphere client to 5.1.1.12 for the Release 9.0.3 Design Console.

Note:

For WebSphere clusters, you must also upgrade the Network Deployment Manager and all Node Managers to 5.1.1.12.

Refer to the WebSphere application server documentation for details on upgrading to WebSphere 5.1.1.12.

Note:

While upgrading to WebSphere 5.1.1.12 application server, you should review IBM's information about the WebSphere application server required changes for United States daylight saving time changes. Go to the IBM Support and downloads Web site at:

http://www.ibm.com/support/us/

Upgrading the Database for Oracle Identity Manager

Choose one of the following approaches to upgrade the database used by your Oracle Identity Manager Release 9.0.2 deployment:

• Perform an in-place upgrade of the existing database configured for Release 9.0.2—refer to Upgrading an Existing Database Instance In-Place.

• Create a new instance of the database for Release 9.0.3, then import the data used by your Release 9.0.2 deployment into that new database and perform the upgrade—refer to Creating a New Database Instance for the Upgrade.

Before you upgrade your database, perform the following steps:

1. Extract the contents of the Oracle Identity Manager Release 9.0.3 upgrade package to a temporary directory on the database machine—this document refers to this temporary directory as <PATCH>.

2. Enable execute permissions on the scripts in the <PATCH> directory.

Upgrading an Existing Database Instance In-Place

This approach upgrades your existing Release 9.0.2 database instance by upgrading the database schema while your database remains in-place.

1. Backup your existing database. As appropriate to your particular database, use the export/backup utilities provided with the Oracle database or SQL Server 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 Identity Manager Release 9.0.2 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.

2. Verify your database is properly configured by referring to the database vendor's documentation and the Oracle Identity Manager Installation and Upgrade Guide specific to your application server.

3. Upgrade your database schema from Oracle Identity Manager Release 9.0.2 to Release 9.0.3 by using the one of the following scripts appropriate for your database and operating system. Be sure to run the script on the machine where the database resides.

   Note:

   The oim_db_upg_902_to_903 script also upgrades the required stored procedures for Oracle.

   Oracle on UNIX and Linux:

   1. Run the following script on the system where the database for Oracle Identity Manager Release 9.0.2 is installed to upgrade the database schema:

      <PATCH>/db/oracle/Scripts/oim_db_upg_902_to_903.sh
      
      

   2. Enter the appropriate information for the Oracle database when prompted by the oim_db_upg_902_to_903.sh script.

   Oracle on Windows:

   Run the following batch script on the system where the Release 9.0.2 database is installed to upgrade the database schema:

   <PATCH>\db\oracle\Scripts\oim_db_upg_902_to_903.bat
   
   

   The following is the command line usage for the Oracle oim_db_upg_902_to_903.bat script:

   oim_db_upg_902_to_903.bat <ORACLE_SID> <ORACLE_HOME> <ORACLE_XELL_USER> <ORACLE_XELL_USER_PWD> <PATCH> 
   
   

   SQL Server:

   Run the <PATCH>\db\SQLServer\Scripts\upg_902_to_903.bat batch file. Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing this script.

4. Perform the following steps to recompile the stored procedures for your database:

   Note:

   If you are using an Oracle database, you can skip this step as running the oim_db_upg_902_to_903 script already created the required stored procedures for Oracle.

   SQL Server:

   1. Launch a plain-text editor, then open:

      <PATCH>\db\SQLServer\StoredProcedures\compile_all_XL_SP.bat
      
      

   1. For every stored procedure listed in the Sequential Lists section of compile_all_XL_SP.bat, replace the string @sysuser 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). Be sure you replace the entire @sysuser string, including the @ character

   1. Run the following script:

      <PATCH>\db\SQLServer\StoredProcedures\compile_all_XL_SP.bat
      
      

      Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing this script.

5. Perform the following steps appropriate for your database to upgrade the Oracle Identity Manager Audit and Compliance module:

   Oracle:

   1. Log in to SQL *Plus with the credentials of the Oracle Identity Manager Release 9.0.2 database schema owner.

   1. Run the following script:

      <PATCH>/db/oracle/Scripts/Oracle_Enable_XACM.sql
      
      

   SQL Server:

   Run the following script:

   <PATCH>\db\SQLServer\Scripts\SQLServer_Enable_XACM.bat
   
   

   Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing this script.

6. The user profile auditing feature and the reports feature 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 commands:

   Windows:

   Run the following .bat file:

   <PATCH>\db\Utilities\LoadXML.bat
   
   

   UNIX and Linux:

   Run the following script:

   <PATCH>/db/Utilities/LoadXML.sh
   
   

   Refer to Appendix B, "Loading Metadata into the Database" for more information on executing this script.

Creating a New Database Instance for the Upgrade

In this approach, you create a new database instance for Release 9.0.3, then import the data used by your Release 9.0.2 deployment into that new database and perform the upgrade. This method ensures that your current working database remains available if a rollback is required. Use the following steps for creating a new, upgraded database instance:

1. Backup your existing database. As appropriate to your particular database, use the export/backup utilities provided with the Oracle database or SQL Server 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 Identity Manager Release 9.0.2 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.

2. Create a new database by referring to the database vendor's documentation and the Oracle Identity Manager Installation and Upgrade Guide specific to your application server.

   Note:

   If you create a new database, be sure to specify the user name and password used by your original database instance as the credentials for your new database.

3. Using the import utility provided by your particular database, import the data you exported from your Release 9.0.2 database into your newly created Release 9.0.3 database. This creates an exact copy of your original database instance.

4. Upgrade your database schema from Oracle Identity Manager Release 9.0.2 to Release 9.0.3 by using the one of the following scripts appropriate for your database and operating system. Be sure to run the script on the machine where the database resides.

   Oracle on UNIX and Linux:

   Run the following script on the new Release 9.0.3 database system and enter the appropriate information when prompted to upgrade the database schema:

   <PATCH>/db/oracle/Scripts/oim_db_upg_902_to_903.sh
   

   Note:

   The oim_db_upg_902_to_903 script also upgrades the required stored procedures for Oracle.

   Oracle on Windows:

   Run the following batch script on the new Release 9.0.3 database system to upgrade the database schema:

   <PATCH>\db\oracle\Scripts\oim_db_upg_902_to_903.bat
   
   

   The following is the command line usage for the Oracle oim_db_upg_902_to_903.bat script:

   oim_db_upg_902_to_903.bat <ORACLE_SID> <ORACLE_HOME> <ORACLE_XELL_USER> <ORACLE_XELL_USER_PWD> <PATCH>
   
   

   SQL Server:

   Run the following script:

   <PATCH>\db\SQLServer\Scripts\upg_902_to_903.bat
   
   

   Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing this script.

5. Perform the following steps to recompile the stored procedures for your database:

   Note:

   If you are using an Oracle database, you can skip this step as running the oim_db_upg_902_to_903 script already created the required stored procedures for Oracle.

   SQL Server:

   1. Launch a plain-text editor and open the following script:

      <PATCH>\db\SQLServer\StoredProcedures\compile_all_XL_SP.bat
      
      

   1. For every stored procedure listed in the Sequential Lists section of compile_all_XL_SP.bat, replace the string @sysuser 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). Be sure you replace the entire @sysuser string, including the @ character.

   1. Run the following script:

      <PATCH>\db\SQLServer\StoredProcedures\compile_all_XL_SP.bat
      
      

      Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing this script.

6. Perform the following steps appropriate for your database to upgrade the Oracle Identity Manager Audit and Compliance module:

   Oracle:

   1. Log in to SQL *Plus with the credentials of the Oracle Identity Manager Release 9.0.2 database schema owner.

   1. Run the following script:

      <PATCH>/db/oracle/Scripts/Oracle_Enable_XACM.sql
      
      

   SQL Server:

   Run the following script:

   <PATCH>\db\SQLServer\Scripts\SQLServer_Enable_XACM.bat
   
   

   Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing this script.

7. The user profile auditing feature and the reports feature 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 commands:

   Windows:

   Run the following script:

   <PATCH>\db\Utilities\LoadXML.bat
   
   

   UNIX and Linux:

   Run the following script:

   <PATCH>/db/Utilities/LoadXML.sh
   
   

   Refer to Appendix B, "Loading Metadata into the Database" for more information on executing this script.

Preparing for the Upgrade

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

• Oracle Identity Manager server

• Administrative and User Console

• Design Console

• Remote Manager

Preparing the Oracle Identity Manager Server for Upgrade

Prepare the Oracle Identity Manager server for upgrade to Release 9.0.3 by updating the Release 9.0.2 libraries, scripts, and configuration files using the information in this section.

Note:

If you are upgrading to Release 9.0.3 in a WebSphere cluster, perform the steps in this section on the NDM host machine.

1. Extract the contents of the Oracle Identity Manager Release 9.0.3 upgrade package to a temporary directory on the machine where the Oracle Identity Manager Release 9.0.2 server is installed—this document refers to this temporary directory as <PATCH>.

2. Backup the following directories.

   • <XL_HOME>\xellerate\config

   • <XL_HOME>\xellerate\DDTemplates

   • <XL_HOME>\xellerate\lib

   • <XL_HOME>\xellerate\setup

   • <XL_HOME>\xellerate\webapp

   • <XL_HOME>\xellerate\ext

   • <XL_HOME>\xellerate\connectorResources

   • <XL_HOME>\documentation

3. 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 4-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>\documentation\	<XL_HOME>\documentation
   <PATCH>\xellerate\config\	<XL_HOME>\xellerate\config\
   <PATCH>\xellerate\ext\	<XL_HOME>\xellerate\ext\
   <PATCH>\xellerate\GTC\	<XL_HOME>\xellerate\GTC\
   <PATCH>\xellerate\connectorResources\	<XL_HOME>\xellerate\connectorResources\

   
   

4. Copy the following files from the <PATCH>\xellerate\setup directory to the <XL_HOME>\xellerate\setup directory:

   • setup.xml

   • patch_websphere.cmd

   • patch_websphere.sh

   • websphere-setup.xml

5. Edit the patch script specific to your operating system in the <XL_HOME>/xellerate/setup/ directory as listed in the following table:

   Table 4-2 WebSphere Upgrade Patch Scripts and Parameters to Edit

   Operating System	Script to Edit	Parameter to Edit
   Windows	patch_websphere.cmd	Replace @java_home with the path to the Java installation directory. Replace @wasHome with the path to the WebSphere installation directory. Replace @loc with the path to the Oracle Identity Manager server installation directory.
   UNIX and Linux	patch_websphere.sh	Replace @java_home with the path to directory containing the JDK. Replace @loc with the path to the Oracle Identity Manager server installation directory.

   
   

6. Update your existing Release 9.0.2 Oracle Identity Manager server xlconfig.xml configuration file in the <XL_HOME>/xellerate/config/ directory with the new cache related setting for Release 9.0.3. Perform the following steps:

   1. Open the <XL_HOME>/xellerate/config/xlconfig.xml file and locate the <xl-configuration>< Cache> parameter.

   2. Add the following XML entry before the </Cache> parameter:

      <LinguisticSort>
               <Enable>true</Enable>
               <ExpireTime>-1</ExpireTime>
      </LinguisticSort>
      
      

Preparing the Administrative and User Console for Upgrade

Several Administrative and User Console files were modified in Release 9.0.3. If you customized your Release 9.0.2 Administrative and User Console, that is, you made changes to the default, stock Administrative and User Console that shipped with Release 9.0.2, you must add your customizations into the new Release 9.0.3 Administrative and User Console files.

Refer to Appendix C, "Upgrading Customized Administrative and User Consoles" if you customized your Release 9.0.2 Administrative and User Console.

If you did not customize your Release 9.0.2 Administrative and User Console, skip this section and continue the upgrade process by referring to Preparing the Design Console for Upgrade.

Preparing the Design Console for Upgrade

Prepare the Oracle Identity Manager Design Console for upgrade to Release 9.0.3 by updating your Release 9.0.2 Design Console libraries, scripts, and configuration files using the following steps:

1. Backup the following files and directories:

   • <XL_DC_HOME>\xlclient\XLDesktopClient.ear

   • <XL_DC_HOME>\xlclient\CustomClient.zip

   • <XL_DC_HOME>\xlclient\xlFvcUtil.ear

   • <XL_DC_HOME>\xlclient\lib

   • <XL_DC_HOME>\xlclient\ext

   • <XL_DC_HOME>\xlclient\fvcutil_websphere.cmd

   • <XL_DC_HOME>\documentation

2. 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 4-3 Oracle Identity Manager Design Console Pre-Upgrade Files to Copy

   Copy From....	To
   <PATCH>\xlclient\XLDesktopClient.ear	<XL_DC_HOME>\xlclient\
   <PATCH>\xlclient\CustomClient.zip	<XL_DC_HOME>\xlclient\
   <PATCH>\xlclient\xlFvcUtil.ear	<XL_DC_HOME>\xlclient\
   <PATCH>\xlclient\lib\	<XL_DC_HOME>\xlclient\lib\
   <PATCH>\xlclient\ext\	<XL_DC_HOME>\xlclient\ext\
   <PATCH>\xlclient\fvcutil_websphere.cmd	<XL_DC_HOME>\xlclient\
   <PATCH>\documentation\	<XL_DC_HOME>\documentation\

   
   

Preparing the Remote Manager for Upgrade

Prepare the Oracle Identity Manager Remote Manager for upgrade to Release 9.0.3 by updating your Release 9.0.2 Remote Manager libraries, scripts, and configuration files using the following steps:

1. Backup the <XL_RM_HOME>\xlremote\lib\ directory.

2. Copy the contents of the <PATCH>\xlremote\lib\ directory to the <XL_RM_HOME>\xlremote\lib\ directory, overwriting files if necessary.

Performing the Upgrade

Upgrading from an existing Oracle Identity Manager Release 9.0.2 deployment to Oracle Identity Manager Release 9.0.3 involves assembling a new enterprise application archive (EAR) file from the latest libraries, then redeploying the EAR.

Use the following steps to perform the upgrade to Release 9.0.3 for both a single WebSphere application server and WebSphere clusters:

1. Enable SOAP communication to NDM/WAS for the patch utility. Edit the <NDM|WAS_INSTALL_DIR>\properties\soap.client.props to enable security with the following properties:

   com.ibm.SOAP.securityEnabled=true
   com.ibm.SOAP.loginUserid=xelsysadm
   com.ibm.SOAP.loginPassword=xelsysadm
   
   

2. Copy the following files from the <PATCH>\xellerate\ext\ directory to the <WEBSPHERE_HOME>\AppServer\lib\ext\ directory and overwrite the existing files if necessary.

   For a WebSphere cluster, copy the following files from the <PATCH>\xellerate\ext\ directory to the <WEBSPHERE_HOME>\AppServer\lib\ext\ directory on all cluster participants, overwriting the existing files if necessary:

   • ojdbc14.jar

   • Uix2.jar

   • Uix2-dbg.jar

3. For a single WebSphere application server, make sure the WebSphere application server is running and execute one of the following patch_websphere scripts.

   For a WebSphere cluster, make sure the WebSphere application server is running on all nodes in the cluster and that the Deployment Manager is running on the NDM host. Execute one of the following patch_websphere scripts on the NDM host.

   Note:

   After successfully executing the patch_websphere script, you may receive some unexpected output in the console or terminal where you execute the patch_websphere script. You can safely ignore this output.

   Windows:

   • Run <XL_HOME>\xellerate\setup\patch_websphere.cmd using the WebSphere administrator's password and the Oracle Identity Manager database user's password as command arguments, for example:

     <XL_HOME>\xellerate\setup\patch_websphere.cmd <WebSphere_admin_password> <database_user_password>
     
     

   UNIX and Linux:

   • Run <XL_HOME>/xellerate/setup/patch_websphere.sh using the WebSphere administrator's password and the Oracle Identity Manager database user's password as command arguments, for example:

     $ <XL_HOME>/xellerate/setup/patch_websphere.sh -<WebSphere_admin_password> -<database_user_password>
     
     

4. For a single WebSphere application server, stop and restart the application server after running the patch_websphere script to complete the upgrade to Release 9.0.3.

   For a WebSphere cluster, stop the cluster components in the following order and proceed to the next step:

   1. Stop the cluster using the Admin Console

   2. Stop the JMS server using the Admin Console

   3. Stop the NDM

5. Complete the upgrade to Release 9.0.3 for a WebSphere cluster using the following steps:

   1. Copy the <XL_HOME> directory from the NDM host to all cluster participants—including the JMS host— while maintaining the same directory hierarchy structure.

   2. Run the setupWebSphereCustomRegistry.cmd script on the NDM host, JMS host, and all cluster participants. The setupWebSphereCustomRegistry.cmd script is located in the <XL_HOME>/xellerate/setup/ directory. Run the setupWebSphereCustomRegistry.cmd script as follows, where <WEBSPHERE_HOME> is the home directory of WebSphere:

      setupWebSphereCustomRegistry.cmd <WEBSPHERE_HOME>
      
      

   3. Start the NDM, start the JMS server, and then start the cluster using the Admin Console to complete the cluster upgrade to Release 9.0.3.

Updating the Design Console xlDataObjectBeans.jar

After performing the upgrade to Release 9.0.3, you must update the Design Console xlDataObjectBeans.jar file using the following steps:

1. Log in to the WebSphere Administrative Console

2. Click Applications and then click Enterprise Applications.

3. Select the Xellerate application option and click Export.

4. Save the generated xellerate.ear

5. Extract xlDataObjectBeans.jar from xellerate.ear.

6. Copy xlDataObjectBeans.jar to the <XL_DC_HOME>\xlclient\lib\ directory.

Migrating Release 9.0.2 Custom Code

You can recycle custom code used in your Release 9.0.2 environment into your newly upgraded Release 9.0.3 environment.

Note:

Before you migrate custom code from the Release 9.0.2 environment, you must first recompile the custom code using the Oracle Identity Manager Release 9.0.3 libraries.

The following is a list of the customized items you can migrate from your Release 9.0.2 environment and reuse in Release 9.0.3 after recompiling using the Release 9.0.3 libraries:

Note:

For clustered environments, after recompiling the following customized items using the Release 9.0.3 libraries, copy the recompiled code to the remaining participants in the cluster.

• Custom java code recompiled using the integrated development environment (that is, Eclipse, JDeveloper, WASD or command line javac) and Release 9.0.3 libraries.

• Custom java libraries bound to functional Oracle Identity Manager Release 9.0.2 adapters recompiled using Release 9.0.3 libraries. You do not need to recompile the adapters.

• Custom scheduled tasks recompiled using Release 9.0.3 libraries.

• Custom event handlers recompiled using Release 9.0.3 libraries.

• Custom clients that were built using Oracle Identity Manager Release 9.0.2 APIs must be updated to make them compatible with the Oracle Identity Manager Release 9.0.3 APIs.

  For example, certain APIs might have been deprecated and replaced by new APIs. Refer to the Oracle Identity Manager Release 9.0.3 Release Notes for information on API changes between Oracle Identity Manager Release 9.0.2 and Release 9.0.3.

Upgrading the Diagnostic Dashboard

You must remove the existing Release 9.0.2 Diagnostic Dashboard XIMDD application before upgrading to the Release 9.0.3 Diagnostic Dashboard on WebSphere. Use the following steps:

1. Remove the existing XIMDD application using the Admin Console.

2. Install a new instance of the XIMDD application using the Release 9.0.3 XIMDD.war file in the <PATCH>\DiagnosticDashboard directory.

   Refer to the "Installing the Diagnostic Dashboard" section in the "Working with the Diagnostic Dashboard" chapter in the Oracle Identity Manager Administrative and User Console Guide for complete steps on how to install the Diagnostic Dashboard on your application server.