2 Upgrading to Release 9.1.0 on JBoss Application Server

This chapter explains how to upgrade to release 9.1.0 from release 9.0.3.2 on JBoss Application Server. Do not attempt to upgrade to release 9.1.0 from any other previous 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.

Note:

This guide refers to this temporary directory as PATCH.

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

1. Creating a Backup of the Existing Deployment

2. Upgrading the Oracle Identity Manager Database

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

   • Preparing Oracle Identity Manager for Upgrade

   • Preparing and Upgrading the Design Console

   • Preparing and Upgrading the Remote Manager

4. Performing the Upgrade from Release 9.0.3.2 to Release 9.1.0

5. Migrating Custom Java Code

6. Postupgrade Configuration

7. Upgrading the Diagnostic Dashboard

2.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, 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 back up of the OIM_HOME directory in which you have installed Oracle Identity Manager.

• Oracle Identity Manager Design Console

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

• JBoss Application Server

  Create a back up of the directory in which JBoss Application Server is installed.

• Oracle Identity Manager Remote Manager

  Create a back up 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.

2.2 Upgrading the Oracle Identity Manager Database

For details about upgrading the Oracle Identity Manager Database, see Chapter 6, "Upgrading the Oracle Identity Manager Database".

2.3 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

2.3.1 Preparing Oracle Identity Manager for Upgrade

To prepare Oracle Identity Manager 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 in the computer on which Oracle Identity Manager release 9.0.3.2 is installed. This document refers to this temporary directory as PATCH.

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 2-1. Overwrite the existing files in the To location if necessary.

   Table 2-1 Oracle Identity Manager Preupgrade Files to Copy

   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/SPMLWS/	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 the xlUpgradeAttestation.jar file. Copy it only before running the UpgradeAttestation script.

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

   • setup.xml

   • patch_jboss.cmd

   • patch_jboss.sh

   • jboss-setup.xml

   • spml_jboss.cmd

   • spml_jboss.sh

   • UpgradeAttestation.sh

   • UpgradeAttestation.bat

5. Copy the OIM_HOME/xellerate/config/xl-jms-service.xml file to the JBOSS_HOME/server/default/deploy/jms/ directory. For information about multiple JMS queues, see "Multiple JMS Queues".

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

   Table 2-2 JBoss Upgrade Patch Scripts and Parameters to Edit

   Operating System	Script to Edit	Parameter to Edit
   Microsoft Windows	patch_jboss.cmd	Replace @java_loc with the path to the Java installation directory. Replace @loc with the path to the Oracle Identity Manager installation directory.
   	spml_jboss.cmd	Replace @java_loc with the path to the Java installation directory. Replace @loc with the path to the Oracle Identity Manager installation directory.
   	UpgradeAttestation.bat	Replace @java_home with the path to the Java installation directory.
   UNIX	patch_jboss.sh	Replace @java_loc with the path to the Java installation directory. Replace @loc with the path to the Oracle Identity Manager installation directory.
   	spml_jboss.sh	Replace @java_loc with the path to the Java installation directory. Replace @loc with the path to the Oracle Identity Manager installation directory.
   	UpgradeAttestation.sh	Replace @java_home with the path to the Java installation directory.

   
   

7. Migrate any customizations you made to the release 9.0.3.2 Web application, for example JSP customizations. To do so, 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 Java Code" for more information about migrating customizations

8. 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. To do so:

   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 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:

Chapter12: "SPML Web Service" in Oracle Identity Manager Tools Reference

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 future usage

Additional JMS queues are created in step 7 in "Preparing Oracle Identity Manager for Upgrade".

2.3.2 Preparing and Upgrading the Design Console

To prepare the Oracle Identity Manager Design Console for upgrade to release 9.1.0, you must update your release 9.0.3.2 Design Console libraries, scripts, and configuration files by performing 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 2-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 2-3 Oracle Identity Manager Design Console Preupgrade Files to Copy

   Copy From	To
   PATCH/xlclient/XLDesktopClient.ear	OIM_DC_HOME/xlclient/
   PATCH/readme.html	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. Open the OIM_DC_HOME/xlclient/Config/xlconfig.xml file in a text editor.

   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. Replace MULTICASTADDRESS_VALUE with 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.

2.3.3 Preparing and Upgrading the Remote Manager

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

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.

2.4 Performing the Upgrade from Release 9.0.3.2 to Release 9.1.0

Perform the following steps to perform the upgrade to Release 9.1.0 (9.0.3.2 upgrade) on a single installation of JBoss Application Server:

1. Ensure that the JBoss Application Server is not running.

   Note:

   If JBoss Application Server is running, then you can stop it by running one of the following commands, as appropriate for the operating system on the Oracle Identity Manager host computer:

   For Microsoft Windows:

   JBOSS_HOME\bin\shutdown.bat -S
   

   For UNIX:

   JBOSS_HOME/bin/shutdown.sh -S
   

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

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

4. Run the patch_jboss script:

   For Microsoft Windows:

   Run OIM_HOME\xellerate\setup\patch_jboss.cmd OIM_DB_USER_ PASSWORD

   For UNIX:

   Run OIM_HOME/xellerate/setup/patch_jboss.sh OIM_DB_USER_ PASSWORD

   Where OIM_DB_USER_PASSWORD is the database password for Oracle Identity Manager installation.

5. Copy the PATCH/xellerate/ext/ojdbc14.jar file to the JBOSS_HOME/server/default/lib/ directory. If this JAR file already exists in the destination directory, then overwrite the existing file..

6. Edit the login-config.xml file in the JBOSS_HOME/server/default/conf/ directory. To do so:

   1. In the login-config.xml file, search for:

      <login-module code="com.thortech.xl.security.jboss.XLClientLoginModule" flag="required">
      

   2. Change to:

      <login-module code="org.jboss.security.ClientLoginModule" flag="required">
      

   3. Save the changes in the file.

7. Restart JBoss Application Server.

8. 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 have been upgraded. If you are running the scheduled task through the Design Console, then ensure that the Design Console has also been upgraded.

2.5 Migrating Custom Java 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 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 items by using the release 9.1.0 libraries, copy them to each participant node of 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 for release 9.0.3.2 to the same directory in release 9.1.0. In addition, you must copy the recompiled custom Java libraries in the OIM_RM_HOME/xellerate/JavaTasks/ directory for release 9.0.3.2 to the OIM_RM_HOME/xellerate/JavaTasks/ directory for 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 for 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 in release 9.1.0.

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

• Custom resources by copying the OIM_HOME/xellerate/customResources/ directory in release 9.0.3.2 to the OIM_HOME/xellerate/customResources/ directory in 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.

2.6 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

2.6.1 Setting the User Profile Audit Level

To set the user profile audit level:

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

   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, perform the following steps:

   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, perform the following steps:

   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.

2.6.2 Generating User Snapshots

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

2.6.3 Generating GPA Snapshots

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

2.6.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".

2.7 Upgrading the Diagnostic Dashboard

To upgrade to the release 9.1.0 Diagnostic Dashboard XIMDD application on JBoss Application Server, install a new instance of the XIMDD application by copying the release 9.1.0 XIMDD.war file from the PATCH/DiagnosticDashboard/ directory to the JBOSS_HOME/server/default/deploy/ directory.

Note:

• You need not remove the existing version of release 9.0.3.2 Diagnostic Dashboard XIMDD application to upgrade to the 9.1.0 Diagnostic Dashboard on JBoss Application Server.

• For clustered installations, copy the application (XIMDD.war) to the JBOSS_HOME/server/all/deploy/ directory.

See Also:

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