5 Upgrading to Release 9.1.0 on Oracle Application Server

This chapter explains how to upgrade to release 9.1.0 from release 9.0.3.2 on Oracle Application Server. Do not attempt to upgrade to release 9.1.0 from any other previous Oracle Identity Manager release of Oracle Identity Manager.

Extract the contents of the release 9.1.0 upgrade package to a temporary directory on your existing release 9.0.3.2 system.

The following steps (detailed in this chapter) explain how to upgrade from release 9.0.3.2 to release 9.1.0 on Oracle Application Server:

1. Creating a Backup of the Existing Deployment

2. Upgrading the Oracle Identity Manager Database

3. Applying Oracle Application Server Patches

4. Preparing for the Upgrade from Release 9.0.3.2 to Release 9.1.0

   1. Preparing Oracle Identity Manager for Upgrade

   2. Preparing and Upgrading the Design Console

   3. Preparing and Upgrading the Remote Manager for Upgrade

5. Performing the Upgrade From Release 9.0.3.2 to Release 9.1.0

6. Migrating Custom Code

7. Postupgrade Configuration

8. Upgrading the Diagnostic Dashboard

5.1 Creating a Backup of the Existing Deployment

The first step for upgrading to release 9.1.0 is to create a backup of your existing Oracle Identity Manager installation. If the upgrade fails, then you can use this backup to restore the existing Oracle Identity Manager installation to its original state.

Create a backup of the following:

• Oracle Identity Manager

  Create a backup of the OIM_HOME directory in which you have installed Oracle Identity Manager.

• Oracle Identity Manager Design Console

  Create a backup of the OIM_DC_HOME directory in which you have installed the Oracle Identity Manager Design Console.

• Oracle Application Server

  Create a backup of the directory in which Oracle Application Server is installed.

• Oracle Identity Manager Remote Manager

  Create a backup of the OIM_RM_HOME directory in which you have installed the Oracle Identity Manager Remote Manager.

• Database used for release 9.0.3.2

  Follow the standard backup procedure for the database.

5.2 Upgrading the Oracle Identity Manager Database

For details about upgrading the Oracle Identity Manager database, refer to Chapter 6, "Upgrading the Oracle Identity Manager Database".

5.3 Applying Oracle Application Server Patches

You must run the following patches on Oracle Application Server before installing Oracle Identity Manager release 9.1.0 on it:

Note:

• Patches and instructions on how to apply those patches can be downloaded from the Oracle MetaLink Web site at:

  http://metalink.oracle.com

• If you are installing Oracle Identity Manager on Microsoft Windows Vista, then you must set the environment variable OPATCH_PLATFORM_ID to 207.

1. Install OPatch patch 2617419.

2. Install Oracle Application Server patch 6685235.

3. Install Oracle Application Server patch 5389650.

4. Install Oracle Application Server patch 6454278.

5. Open the ORACLE_HOME/j2ee/OAS_INSTANCE/config/rmi.xml file. Add max-server-sockets="200" as shown:

   <rmi-server
   ...
   max-server-sockets="200">
   

5.4 Preparing for the Upgrade from Release 9.0.3.2 to Release 9.1.0

Before you upgrade to Oracle Identity Manager release 9.1.0, you must prepare for the upgrade by performing preupgrade configuration tasks on the following components:

• Oracle Identity Manager

• Design Console

• Remote Manager

5.4.1 Preparing Oracle Identity Manager for Upgrade

To prepare the Oracle Identity Manager deployment for upgrade to release 9.1.0, you must update the release 9.0.3.2 libraries, scripts, and configuration files by performing the following steps:

1. Extract the contents of the Oracle Identity Manager release 9.1.0 upgrade package to a temporary directory on the computer on which Oracle Identity Manager release 9.0.3.2 is installed.

2. Create a backup of the OIM_HOME directory.

3. Copy the directories and files listed in the location of the From column to the location listed in the To column in Table 5-1.

   Overwrite the existing files in the To location if necessary.

   Table 5-1  Oracle Identity Manager Preupgrade Files to Copy

   From	To
   PATCH/documentation/	OIM_HOME/documentation/
   PATCH/readme.html	OIM_HOME/
   PATCH/xellerate/bin/	OIM_HOME/xellerate/bin/
   PATCH/xellerate/config/	OIM_HOME/xellerate/config/
   PATCH/xellerate/ConnectorDefaultDirectory/	OIM_HOME/xellerate/ConnectorDefaultDirectory/
   PATCH/xellerate/DDTemplates/	OIM_HOME/xellerate/DDTemplates/
   PATCH/xellerate/ext/	OIM_HOME/xellerate/ext/
   PATCH/xellerate/GTC/	OIM_HOME/xellerate/GTC/
   PATCH/xellerate/JavaTasks/	OIM_HOME/xellerate/JavaTasks/
   PATCH/xellerate/lib/	OIM_HOME/xellerate/lib/
   PATCH/xellerate/SPMLSWS/	OIM_HOME/xellerate/SPMLWS/
   PATCH/xellerate/webapp/	OIM_HOME/xellerate/webapp/
   PATCH/xellerate/connectorResources/	OIM_HOME/xellerate/connectorResources/
   PATCH/xellerate/customResources/	OIM_HOME/xellerate/customResources/

   
   

   Note:

   While copying the PATCH/xellerate/lib/ directory, do not copy xlUpgradeAttestation.jar. Copy it only when you run the UpgradeAttestation script.

4. Copy the following files from the PATCH/xellerate/setup/ directory to the OIM_HOME/xellerate/setup/ directory:

   • setup.xml

   • patch_oc4j.cmd

   • patch_oc4j.sh

   • oc4j-setup.xml

   • spml_oc4j.cmd

   • spml_oc4j.sh

   • UpgradeAttestation.sh

   • UpgradeAttestation.bat

5. Edit the scripts specific to your operating system in the OIM_HOME/xellerate/setup/directory as listed in Table 5-2.

   Table 5-2  Oracle Application Server Upgrade Patch Scripts and Parameters to Edit

   Operating System	Script to Edit	Parameter to Edit
   Microsoft Windows	patch_oc4j.cmd	Replace @loc with the path to the Oracle Identity Manager installation directory. Replace @java_loc with the path to the Oracle Application Server Java directory. Replace @oracle_home with the path to the Oracle Application Server directory.
   	spml_oc4j.cmd	Replace @loc with the path to the Oracle Identity Manager installation directory. Replace @java_loc with the path to the Oracle Application Server Java directory. Replace @oracle_home with the path to the Oracle Application Server directory.
   	UpgradeAttestation.bat	Replace @java_home with the path to the Java installation directory.
   UNIX	patch_oc4j.sh	Replace @loc with the path to the Oracle Identity Manager installation directory. Replace @java_loc with the path to the Oracle Application server Java directory. Replace @oracle_home with the path to the Oracle Application Server directory.
   	spml_oc4j.sh	Replace @loc with the path to the Oracle Identity Manager installation directory. Replace @java_loc with the path to the Oracle Application Server Java directory. Replace @oracle_home with the path to the Oracle Application Server directory.
   	UpgradeAttestation.sh	Replace @java_home with the path to the Java installation directory.

   
   

6. Migrate any customizations you made to the release 9.0.3.2 Web application, for example JSP customizations.

   Apply the 9.0.3.2 customizations to the new release 9.1.0 xlWebApp.war Web application file located in the OIM_HOME/xellerate/webapp/ directory.

   See Also:

   ""Migrating Custom Code" for more information about migrating customizations

7. Update your existing release 9.0.3.2 xlconfig.xml configuration file in the OIM_HOME/xellerate/config/ directory with the new cache-related setting for release 9.1.0. Perform the following steps:

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

   2. After </ColumnMetaData>, add the following:

      <!-- API Data -->
      <API>
           <Enable>false</Enable>
           <ExpireTime>14400</ExpireTime>
      </API>
      

   3. After </AttestationTaskMessage>, add the following:

      <AttestationTaskDetailMessage>com.thortech.xl.schedule.jms.attestation.processOfflinedAttestationTaskDetails</AttestationTaskDetailMessage>
      

      Note:

      The aforementioned line of code must be added as a single line without any line breaks.

   4. Inside:

      <recon_offline_queue>
      

      Replace:

      <queueName>queue/xlQueue</queueName>
      
      With:
      <queueName>queue/xlReconQueue</queueName>
      

   5. Inside:

      <auditor_offline_queue>
      

      Replace:

      <queueName>queue/xlQueue</queueName>
      

      With:

      <queueName>queue/xlAuditQueue</queueName>
      

   6. Inside:

      <attestation_request_queue>
      

      Replace:

      <queueName>queue/xlQueue</queueName>
      

      With:

      <queueName>queue/xlAttestationQueue</queueName>
      

   7. Inside:

      <attestation_task_queue> 
      

      Replace

      <queueName>queue/xlQueue</queueName>
      

      With:

      <queueName>queue/xlAttestationQueue</queueName>
      

   8. Inside:

      <attestation_workflow_task_queue> 
      

      Replace:

      <queueName>queue/xlQueue</queueName> 
      

      With:

      <queueName>queue/xlAttestationQueue</queueName> 
      

   9. Inside:

      <process_offline_queue> 
      

      Replace:

      <queueName>queue/xlQueue</queueName> 
      

      With:

      <queueName>queue/xlProcessQueue</queueName> 
      

   10. Inside:

       <process_task_offline_queue> 
       

       Replace:

       <queueName>queue/xlQueue</queueName>
       

       With:

       <queueName>queue/xlProcessQueue</queueName>
       

   11. After </attestation_task_queue>, add the following:

       <attestation_task_detail_queue>
       <queueName>queue/xlAttestationQueue</queueName>
       <autoAcknowledge>true</autoAcknowledge>
       <replyTo></replyTo>
       <persistentFlag>true</persistentFlag>
       <disableMessageId>true</disableMessageId>
       <disableTimeStampe>false</disableTimeStampe>
       <messageEncrypt>false</messageEncrypt>
       </attestation_task_detail_queue>
       

Redeploying SPML Web Service

If you are using SPML Web service in the existing Oracle Identity Manager setup, then you must redeploy the SPML Web service for that setup whenever the setup is upgraded.

See Also:

Chapter 12: "SPML Web Service" in Oracle Identity Manager Tools Reference

5.4.2 Preparing and Upgrading the Design Console

Prepare the Oracle Identity Manager Design Console for upgrade to release 9.1.0 by updating your release 9.0.3.2 Design Console libraries, scripts, and configuration files by using the following steps.

1. Create a backup of the OIM_DC_HOME directory.

2. Copy the directories and files listed in the location of the From column to the location listed in the To column in Table 5-3.

   Overwrite the existing files in the To location if necessary.

   Note:

   Delete the release 9.0.3.2 files in the OIM_DC_HOME/documentation/ directory before copying the release 9.1.0 files from the PATCH/documentation/ directory.

   Table 5-3  Oracle Identity Manager Design Console Preupgrade Files to Copy

   From	To
   PATCH/xlclient/XLDesktopClient.ear	OIM_DC_HOME/xlclient/
   PATCH/xellerate/readme.htm	OIM_DC_HOME/xlclient/
   PATCH/xlclient/CustomClient.zip	OIM_DC_HOME/xlclient/
   PATCH/xlclient/xlFvcUtil.ear	OIM_DC_HOME/xlclient/
   PATCH/xlclient/lib/	OIM_DC_HOME/xlclient/lib/
   PATCH/documentation/	OIM_DC_HOME/documentation/
   PATCH/xellerate/ext/	OIM_DC_HOME/ext/

   
   

3. Edit the OIM_DC_HOME/xlclient/classpath.bat file and add the following string to the end of CLASSPATH: ";.\ext\oscache.jar;.\ext\commons-logging.jar;.\ext\javagroups-all.jar"

4. Specify the multicast address in the xlconfig.xml file of the Design Console as follows:

   1. In a text editor, open the OIM_DC_HOME/xlclient/Config/xlconfig.xml file.

   2. Add the following lines before the </xl-configuration> tag:

      <!--  Value of MultiCastAddress must be the same as that of Oracle Identity Manager -->
      <Cache>
        <XLCacheProvider>
          <MultiCastAddress>MULTICASTADDRESS_VALUE</MultiCastAddress>
        </XLCacheProvider>
      </Cache>
      

   3. Change MULTICASTADDRESS_VALUE to the value of the multicast address for Oracle Identity Manager.

   Note:

   After Oracle Identity Manager and the Design Console are upgraded, go to Adapter Manager on the Design Console and recompile all the adapters.

5.4.3 Preparing and Upgrading the Remote Manager for Upgrade

Prepare the Oracle Identity Manager Remote Manager for upgrade to release 9.1.0 by updating your release 9.0.3.2 Remote Manager libraries, scripts, and configuration files. To do so:

1. Create a backup of the OIM_RM_HOME/xlremote/lib/ directory.

2. Copy the contents of the PATCH/xlremote/lib/ directory to the OIM_RM_HOME/xlremote/lib/ directory, by overwriting files if required.

5.4.4 Multiple JMS Queues

Previously, Oracle Identity Manager used a single JMS queue (named xlQueue) for all asynchronous operations including requests, reconciliation, attestation, and offline tasks. In release 9.1.0, by default, Oracle Identity Manager uses separate JMS queues for specific operations to optimize JMS queue processing. The following is a list of the default JMS queue configuration and their related operations:

• xlQueue for request operations

• xlReconQueue for reconciliation operations

• xlAuditQueue for auditing operations

• xlAttestationQueue for attestation operations

• xlProcessQueue for usage in future Oracle Identity Manager releases

This section provides details that help to create the additional JMS queues.

Creating JMS Queues for JMS Server

To create JMS queues for JMS server:

1. Log in to the Oracle Enterprise Manager.

2. Under the Groups tab on the home page, click the group name to which the Oracle Identity Manager instance belongs (default_group by default).

3. Click the Administration tab.

4. Expand Administrative tasks, Services, Enterprise Messaging Service, and then click JMS Destinations. Two Oracle Identity Manager Queues, xlQueue and xlErrorQueue that were present in 9.0.3.2 are displayed.

5. To create the new queues, click Create New.

6. From the Destination Type list, select Queue, and enter xlReconQueue as the value for Destination Name.

7. From the File Based Persistence list, select Persistence and enter the following values:

   • JNDI Location: queue/xlReconQueue

   • Persistence File: xlReconQueueJMSStore

8. Click OK to create the queue.

9. Repeat steps 5 through 8 with the following values for Destination Name, JNDI Location and Persistence File:

   • Destination Name: xlAuditQueue

     JNDI Location: queue/xlAuditQueue

     Persistence File Name: xlAuditQueueJMSStore

   • Destination Name: xlAttestationQueue

     JNDI Location: queue/xlAttestationQueue

     Persistence File Name: xlAttestationQueueJMSStore

   • Destination Name: xlProcessQueue

     JNDI Location: queue/xlProcessQueue

     Persistence File Name: xlProcessQueueJMSStore

   Note:

   For a clustered installation of Oracle Identity Manager, create all the four queues for each server present in the cluster.

5.5 Performing the Upgrade From Release 9.0.3.2 to Release 9.1.0

Perform the following steps to upgrade to release 9.1.0 from release 9.0.3.2 on a single installation of Oracle Application Server:

1. Ensure that Oracle Application Server is not running.

   Note:

   If Oracle Application Server is running, then you can stop it by running the following command from the ORACLE_HOME/opmn/bin directory on the computer hosting the Oracle Identity Manager deployment:

   ./opmnctl stopall
   

2. Delete the OIM_HOME/xellerate/webapp/precompiled/ directory.

3. Start the Oracle Application Server as follows:

   1. Go to the ORACLE_HOME/opmn/bin directory.

   2. Run the following command:

      ./opmnctl startall
      

4. For upgrading attestation, see Appendix H, "Upgrade Attestation Utility". This is a mandatory step.

5. In the OIM_HOME/xellerate/Profiles/oc4j.profile file, after the line:

   # database type is either oracle or sqlserver
   database.type=oracle
   

   Add the following:

   # Reporting data source
   datasource.report=jdbc/xlXADS
   

6. Run the patch_oc4j script:

   For Microsoft Windows, run:

   OIM_HOME\xellerate\setup\patch_oc4j.cmd OAS_ADMIN_PASSWORD DATASOURCE_PASSWORD
   

   For UNIX, run:

   OIM_HOME/xellerate/setup/patch_oc4j.sh OAS_ADMIN_PASSWORD DATASOURCE_PASSWORD
   

   The patch_oc4j script parameters are:

   • OAS_ADMIN_PASSWORD is the Oracle Application Server administrator password.

   • DATASOURCE_PASSWORD is the database password for Oracle Identity Manager installation.

7. Copy the PATCH/xellerate/ext/ojdbc14.jar file to the OAS_HOME/jlib/ directory by overwriting the existing files, if required.

8. Restart Oracle Application Server.

9. Run the Re-Issue Audit Message Task scheduled task to ensure that all the pending audit messages in the aud_jms table are processed.

   Note:

   While running the Re-Issue Audit Message Task scheduled task, ensure that the database and Oracle Identity Manager are upgraded. If you are running the scheduled task by using the Design Console, then make sure that the Design Console has also been upgraded.

5.6 Migrating Custom Code

You can migrate the custom Java code from the release 9.0.3.2 environment into the new release 9.1.0 environment. Before you migrate the custom Java code from the release 9.0.3.2 environment, you must first recompile it by using the release 9.1.0 libraries located in the OIM_HOME/xellerate/lib/ directory.

Using the integrated development environment that originally compiled the release 9.0.3.2 custom Java code, which are Eclipse, JDeveloper, WASD or command-line javac, recompile all custom Java code by using the release 9.1.0 libraries.

The following is a list of the custom items that you can migrate from release 9.0.3.2 and reuse in release 9.1.0 after recompiling.

Note:

For clustered environments, after recompiling the following customized items by using the release 9.1.0 libraries, copy the recompiled code to each participant node in the cluster.

• Custom Java libraries bound to functional Oracle Identity Manager release 9.0.3.2 adapters recompiled by using release 9.1.0 libraries.

  You must copy the recompiled custom Java libraries in the OIM_HOME/xellerate/JavaTasks/ directory of release 9.0.3.2 to the same directory in release 9.0.3.2. In addition, you must copy the recompiled custom Java libraries in the OIM_RM_HOME/xellerate/JavaTasks/ directory of release 9.0.3.2 to the OIM_RM_HOME/xellerate/JavaTasks/ directory. of release 9.1.0.

• Custom scheduled tasks recompiled by using release 9.1.0 libraries.

  You must copy the recompiled custom scheduled tasks to the OIM_HOME/xellerate/ScheduleTask/ directory of release 9.1.0.

  Note:

  If you want to display the built-in scheduled task on the Administrative and User Console, then copy the xlScheduler.jar file from the OIM_HOME/lib directory to the OIM_HOME/xellerate/ ScheduledTask directory. If the ScheduledTask directory does not exist, then create it.

• Custom event handlers recompiled by using release 9.1.0 libraries.

  You must copy the recompiled custom event handlers to the OIM_HOME/xellerate/EventHandlers/ directory of release 9.1.0.

• Connector resource bundles by copying the OIM_HOME/xellerate/connectorResources/ directory of release 9.0.3.2 to the OIM_HOME/xellerate/connectorResources/ directory of release 9.1.0.

• Custom resources by copying the OIM_HOME/xellerate/customResources/ directory of release 9.0.3.2 to the OIM_HOME/xellerate/customResources/ directory of release 9.1.0.

• Custom Administrative and User Console deployments.

  Several Administrative and User Console files are modified in release 9.1.0. If you customized your release 9.0.3.2 Administrative and User Console, that is, you made changes to the default Administrative and User Console that shipped with release 9.0.3.2, then you must add your customizations into the new release 9.1.0 Administrative and User Console files.

5.7 Postupgrade Configuration

You must perform the following postupgrade configuration procedures:

• Setting the User Profile Audit Level

• Generating User Snapshots

• Generating GPA Snapshots

• Loading Data for Exception-Based Reporting

5.7.1 Setting the User Profile Audit Level

If you want to change the audit level, perform the following steps:

1. Define a secondary data source for reporting, if required.

   See Also:

   Oracle Identity Manager Audit Report Developer's Guide for information about defining a secondary data source

2. Start the application server on which the Oracle Identity Manager installation is running.

3. Set the audit level. The permissible values are in descending order:

   • Process Task

   • Resource Form

   • Resource

   • Membership

   • Core

   • None

4. To specify an audit level:

   1. Log in to the Design Console as an administrator.

   2. Navigate to the System Configuration form.

   3. Locate XL.UserProfileAuditDataCollection and set its value to Resource Form or the appropriate audit level as listed in step 3 of this procedure.

5. To collect user profile audit data in the secondary reporting data store:

   1. Log in to the Design Console as an administrator.

   2. Navigate to the System Configuration form.

   3. Locate XL.UserProfileAuditInSecondaryDS and set its value to TRUE.

5.7.2 Generating User Snapshots

For detailed information about generating user snapshots, see Appendix E, "Generating User Snapshots".

5.7.3 Generating GPA Snapshots

For detailed information about generating GPA snapshots, see Appendix G, "Generating GPA Snapshots".

5.7.4 Loading Data for Exception-Based Reporting

To load data for exception-based reporting, run the UPA Form Data Upgrade utility. For information about the UPA Form Data Upgrade utility, see Appendix F, "UPA Form Data Upgrade Utility".

5.8 Upgrading the Diagnostic Dashboard

To upgrade the existing release 9.0.3.2 Diagnostic Dashboard XIMDD application to the release 9.1.0 Diagnostic Dashboard on Oracle Application Server:

1. Remove the existing XIMDD application by using the Oracle Application Server Admin Console.

2. Install a new instance of the XIMDD application by using the Release 9.1.0 XIMDD.war file in the PATCH/DiagnosticDashboard/ directory.

   See Also:

   The "Working with the Diagnostic Dashboard" chapter in the Oracle Identity Manager Administrative and User Console Guide for more information about the Diagnostic Dashboard