4 Upgrading to Release 9.0.1.2 on WebSphere Application Servers

This chapter explains how to upgrade to Release 9.0.1.2 on WebSphere application servers. Release 9.0.1.2 is an upgrade only release—you can only upgrade to Release 9.0.1.2. You cannot install Release 9.0.1.2 as an initial, first deployment of the Oracle Identity Manager product without first installing Release 9.0.1.1.

If you are new a Oracle Identity Manager customer and Release 9.0.1.2 will be your first deployment of the product, refer to Upgrading to Release 9.0.1.2 as Your First Oracle Identity Manager Deployment.

If you are an existing Oracle Identity Manager customer already running Release 9.0.1.1.x on WebSphere, refer to Upgrading to Release 9.0.1.2 from Release 9.0.1.1.x.

Important: Refer to the Oracle Identity Manager Release Notes for Release 9.0.1.2 for information on the certified application servers and configurations.

Upgrading to Release 9.0.1.2 as Your First Oracle Identity Manager Deployment

If you are a new Oracle Identity Manager customer and Release 9.0.1.2 will be your first deployment of the product, you must first install Release 9.0.1.1 and then upgrade to Release 9.0.1.2. Use the following steps to upgrade to Release 9.0.1.2 as your first Oracle Identity Manager deployment:

1. Install the WebSphere application server by referring to the WebSphere documentation.

2. Install Oracle Identity Manager Release 9.0.1.1 on the WebSphere application server. You can download Release 9.0.1.1 from the Oracle Technology Network Web site using the following steps:

   1. Go to the Oracle Technology Network Web site at:

      http://www.oracle.com/technology/index.html

   2. Click on Downloads at the top of the page.

   3. Go to the Middleware section of the page and click Identity Management.

   4. Click the link for Oracle Identity Manager and Connector Pack.

   5. Click the link for Oracle Identity Manager (9.0.1.1) to download Release 9.0.1.1.

      Refer to the Oracle Identity Manager Installation Guide for WebSphere for details on installing Release 9.0.1.1. You can access the Oracle Identity Manager Release 9.0.1 documentation by clicking Oracle Identity Manager on the Oracle Documentation page of the Oracle Technology Network Web site at:

      http://www.oracle.com/technology/documentation/index.html

3. Upgrade to Release 9.0.1.2 from Release 9.0.1.1 using the steps in Upgrading to Release 9.0.1.2 from Release 9.0.1.1.x.

Upgrading to Release 9.0.1.2 from Release 9.0.1.1.x

The following is a list of the steps in this section that explain how to upgrade to Release 9.0.1.2 from Release 9.0.1.1.x:

1. Upgrading to WebSphere 5.1.1.12

2. Upgrading the Database for Oracle Identity Manager

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.1.1.x Custom Code

6. Redeploying the Diagnostic Dashboard

Upgrading to WebSphere 5.1.1.12

Release 9.0.1.2 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.1.2. Refer to the WebSphere application server documentation for details on upgrading to WebSphere 5.1.1.12.

Be sure to also upgrade the WebSphere client to version 5.1.1.12 for the Release 9.0.1.2 Design Console. For WebSphere clusters, you must also upgrade the Network Deployment Manager and all Node Managers to version 5.1.1.12.

Note: If you have WebSphere 5.1.1.12 installed, go to Upgrading the Database for Oracle Identity Manager to continue the upgrade process.

Upgrading the Database for Oracle Identity Manager

The scripts you must execute to upgrade your database depends on whether or not you deployed the Audit and Compliance Module in your Release 9.0.1.1.x environment. Be sure you execute the scripts appropriate for your environment.

Notes: When upgrading the database to Release 9.0.1.2, consider the following: Several scripts included in the Release 9.0.1.2 upgrade package call other scripts. Retain the same directory structure of the upgrade package after extracting it and be sure that you execute scripts only from the same directory as they are delivered in. Be sure to run the scripts on the machine where the database resides. Check for errors after executing any of the scripts by examining the log file generated in the directory after running any script.

Perform the following steps to upgrade your existing Release 9.0.1.1.x database instance:

1. Extract the contents of the Oracle Identity Manager Release 9.0.1.2 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.

3. 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.1.1.x 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.

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

5. Upgrade your database from Oracle Identity Manager Release 9.0.1.1.x to Release 9.0.1.2 by executing the following scripts appropriate for your type of database and depending on whether or not you deploy the Audit and Compliance Module.

   Oracle Databases and No Audit and Compliance Module Deployment:

   1. Execute the following script:

      <PATCH>\Database\Oracle\Scripts\upg_9011x_to_9012.sql
      
      

   2. Execute the following script:

      <PATCH>\Database\Oracle\StoredProcedures\compile_all_XL_SP.sql
      
      

   Oracle Databases With an Audit and Compliance Module Deployment:

   1. Execute the following script:

      <PATCH>\Database\Oracle\Scripts\upg_9011x_to_9012_XACM.sql
      
      

   2. Execute the following script:

      <PATCH>\Database\Oracle\StoredProcedures\compile_all_XL_SP.sql
      
      

   SQL Server and No Audit and Compliance Module Deployment:

   1. Execute the following script:

      <PATCH>\Database\SQLServer\Scripts\upg_9011x_to_9012.bat
      
      

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

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

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

   4. Execute the following script:

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

   
   

   Note: Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing these scripts.

   
   

   SQL Server With an Audit and Compliance Module Deployment:

   1. Execute the following script:

      <PATCH>\Database\SQLServer\Scripts\upg_9011x_to_9012.bat
      
      

   2. Execute the following script:

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

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

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

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

   5. Execute the following script:

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

   
   

   Note: Refer to Appendix A, "Executing the SQL Server Upgrade Scripts" for more information on executing these scripts.

   
   

6. Both the user profile auditing feature and the reports feature for Oracle Identity Manager require that certain metadata be loaded into the database.

   For environments that do not deploy the Audit and Compliance Module, execute:

   <PATCH>\Database\Utilities\LoadXML.<bat or sh>
   
   

   For environments that deploy the Audit and Compliance Module, execute:

   <PATCH>\Database\Utilities\LoadXML_XACM.<bat or sh>
   
   

   
   

   Note: 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.1.2, 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.1.2 by updating the Release 9.0.1.1.x libraries, scripts, and configuration files using the information in this section.

Note: If you are upgrading to Release 9.0.1.2 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.1.2 upgrade package to a temporary directory on the machine where the Oracle Identity Manager Release 9.0.1.1.x server is installed—this document refers to this temporary directory as <PATCH>.

2. Back up your existing <XL_HOME>\xellerate\ directory.

3. Recursively copy the <PATCH>\xellerate\ directory (including its subdirectories) to the <XL_HOME>\xellerate\ directory overwriting the existing files.

4. Recursively copy the <PATCH>\documentation\ directory (including its subdirectories) to the <XL_HOME>\documentation\ directory.

5. Update your existing Release 9.0.1.1.x Oracle Identity Manager server xlconfig.xml configuration file in the <XL_HOME>/xellerate/config/ directory to include the following new parameters introduced in Release 9.0.1.2:

   1. Set the <xl-configuration>< Cache>< ServerProperties><Enable> parameter to TRUE, for example:

      <xl-configuration><Cache><ServerProperties><Enable>TRUE</Enable>
      </ServerProperties></xl-configuration>
      
      

   2. Locate the <xl-configuration><Cache> parameter. After the <xl-configuration>.<Cache>.<ColumnMetaData> entry, but before the </Cache> entry, add the following entry:

      <API>
              <Enable>false</Enable>
                   <ExpireTime>14400</ExpireTime>
      </API>
      
      

6. Edit the requestPreview script located in the <XL_HOME>/xellerate/bin/ directory according to your database and operating system. If your database is running on Windows, edit the requestPreview.bat script. If your database is running on UNIX or Linux, edit the requestPreview.sh script. Make the following changes:

   Oracle

   Set JAVA_HOME to the location of the JDK that was selected when Oracle Identity Manager was installed. You can verify this value by checking the appserver.jdk.location property in the <XL_HOME>\xellerate\Profiles\websphere.profile file. For example, the appserver.jdk.location property might be the following:

   appserver.jdk.location=<WEBSPHERE_HOME>/java
   
   

   SQL Server

   • Set JAVA_HOME to the location of the JDK that was selected when Oracle Identity Manager was installed. You can verify this value by checking the appserver.jdk.location property in the <XL_HOME>\xellerate\Profiles\websphere.profile file. For example, the appserver.jdk.location property might be the following:

     appserver.jdk.location=<WEBSPHERE_HOME>/java
     
     

   • Set SQL_SERVER_DRIVER_DIR to the path of the directory that contains the mssqlserver.jar, msbase.jar, and msutil.jar files.

   • Uncomment the SQL_SERVER_DRIVER_DIR parameter.

Preparing the Administrative and User Console for Upgrade

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

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

If you did not customize your Release 9.0.1.1.x 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.1.2 by updating your Release 9.0.1.1.x Design Console libraries, scripts, and configuration files using the following steps:

1. Back up your existing <XL_DC_HOME>\xlclient\ directory

2. Recursively copy the <PATCH>\xlclient\ directory (including its subdirectories) to the <XL_DC_HOME>\xlclient\ directory overwriting the existing files.

Preparing the Remote Manager for Upgrade

Prepare the Oracle Identity Manager Remote Manager for upgrade to Release 9.0.1.2 by updating your Release 9.0.1.1.x 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.1.1.x deployment to Oracle Identity Manager Release 9.0.1.2 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.1.2 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 <PATCH>\xellerate\ext\ojdbc14.jar to the <WEBSPHERE_HOME>\AppServer\lib\ext\ directory and overwrite the existing file if necessary.

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

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.

   Windows:

   • Run <XL_HOME>\xellerate\setup\patch_websphere.cmd

   UNIX and Linux:

   • Run <XL_HOME>/xellerate/setup/patch_webpshere.sh

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

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

Updating the Design Console xlDataObjectBeans.jar

After performing the upgrade to Release 9.0.1.2, 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.1.1.x Custom Code

You can recycle custom code used in your Release 9.0.1.1.x environment into your newly upgraded Release 9.0.1.2 environment.

Note: Before you migrate custom code from the Release 9.0.1.1.x environment, you must first recompile the custom code using the Oracle Identity Manager Release 9.0.1.2 libraries.

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

Note: For clustered environments, after recompiling the following customized items using the Release 9.0.1.2 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.1.2 libraries.

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

• Custom scheduled tasks recompiled using Release 9.0.1.2 libraries.

• Custom event handlers recompiled using Release 9.0.1.2 libraries.

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

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

Redeploying the Diagnostic Dashboard

After upgrading to Release 9.0.1.2, you must redeploy the Diagnostic Dashboard using the following steps:

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

2. Use the <XL_HOME>\xellerate\webapp\XIMDD.war file and the instructions in the "Installing the Diagnostic Dashboard" section in the "Working with the Diagnostic Dashboard" chapter of the Oracle Identity Manager Administrative and User Console Guide to redeploy the Diagnostic Dashboard.