You must perform each of the following steps in your Development environment:
You must perform some of these steps when upgrading any environment. However, many of these steps are unique to the Development environment because this is the environment where you update the baseline for your Identity Manager application.
Set any Active Sync processes to start manually and, if applicable, disable any scheduled reconciliations until the upgrade is finished and appears to be successful.
Step 1 is optional, but performing this step is considered a best practice when upgrading the Production environment.
Also, if you perform Step 1 in your Production environment, make it a standard step when upgrading all of your other environments.
Quiesce your Identity Manager application and make it unavailable to all administrators and end users.
Make a copy of your existing database and Identity Manager file structure.
Backing up the database and file structure enables you to reinstate your working environment, if necessary.
Remove any hotfix class files from your WEB-INF/classes directory.
Generally, a hotfix class file works only with the specific version of the Identity Manager product for which that hotfix was delivered.
Make a copy of your existing configuration objects. Also, make a copy of other types of objects in the repository or copy at least a representative sampling of those objects.
The Identity Manager product upgrade saves the file system artifacts that it overlays, such as JSP files, but the upgrade does not preserve “before-images” of every object that it modifies in the repository. Taking a snapshot enables you to detect changes that the Identity Manager product upgrade makes to objects in the repository.
The following instructions describe how to use the Identity Manager SnapShot feature to create a baseline of the customized repository objects in your deployment and how to compare two snapshots to determine what changes have been made to certain system objects before and after the upgrade.
The SnapShot feature is not intended for detailed, ongoing XML diffs. It is only a minimal tool for “first-pass” comparisons.
From the Identity Manager Debug page, click the SnapShot button to view the SnapShot Management page.
Type a name for the snapshot in the Create field, and click the Create button.
When Identity Manager adds the snapshot, the snapshot’s name displays in the Compare menu list and to the right of the Export label.
To compare two snapshots, do the following:
Select the snapshots from each of the two Compare menus:
Click the Compare button.
If no objects were changed, a message indicates that no differences were found.
If object changes are detected, a message displays the object type and name, and indicates whether the object is different, absent, or present.
For example, if an object is present in baseline_1, but not present in baseline_2, then the baseline_1 column indicates Present and the baseline_2 column indicates Absent.
If you want to export a snapshot to a file in XML format, click the snapshot name link.
If you want to delete a snapshot, choose the snapshot name from the Delete menu and then click Delete.
If the target Identity Manager product version requires changes to your platform, you must make these changes before upgrading the Identity Manager product.
If you plan on upgrading the JDK or JRE, you must use a JDK or JRE supplied by the same vendor as your previous JDK. For example, do not install a Sun JDK if previously you were using a JDK from IBM.
If you are using an Oracle repository, the Identity Manager repository DDL uses data types that are not properly handled by older Oracle JDBC drivers. The JDBC drivers in ojdbc14.jar do not properly read all of the columns in the log table.
You must upgrade to the ojdbc5.jar for JDK 5 drivers for Identity Manager to work properly.
To upgrade the Identity Manager product itself, you might be required to do the following:
Most major releases and some minor releases of Identity Manager include database table changes. Consequently, you might have to modify the sample SQL scripts for your environment.
You must also update the database tables if you made any of the following modifications:
Changed the database instance name
Changed the name of the database account that owns the database tables
Separated the owner of the database tables from the database account used to connect to the database
Made more advanced DBA changes, such as configuring specific table spaces and growth characteristics for different sets of tables and indexes
You must remember any changes that you make to the sample SQL scripts for each Identity Manager version and use source control to manage these changes. In the future, you will have to make similar changes to the sample SQL scripts for subsequent Identity Manager versions.
You can use either of the following methods to upgrade the Identity Manager product:
Use the Identity Manager installer program as described in To Use the Identity Manager Installer.
Use the Identity Manager manual upgrade process as described in Upgrading Manually.
Both methods produce the same results.
In some environments you might prefer using the manual upgrade procedure. For example:
If you want to fully automate the upgrade as part of a repeatable upgrade procedure
If you have restricted access to your Production environment or cannot start the console
Upgrading the Identity Manager product might modify objects in the Identity Manager repository and in some file system artifacts such as .jsp files, Identity Manager product JARs, and third-party JARs.
When upgrading the Identity Manager product, be aware of the following:
If you copy files from the installation media to your own location, you must put the idm.war and install.class files in the same directory.
Use only one Identity Manager server to import update.xml, and have only one Identity Manager server running during the upgrade.
If you start any other Identity Manager servers during the upgrade, you must stop and restart those servers before making them available.
If your application server is installed on a machine running a UNIX® system, change directories to the $WSHOME/bin directory and run the following command to allow the scripts in this directory to be executed:
chmod -R +x *
For UNIX environments, be sure that you have an install directory in one of the following locations and that you can write to that directory:
/var/opt/sun/install
/var/sadm/install
Previously installed hotfixes are archived in the $WSHOME/patches/HotfixName directory.
The upgrade program has three steps: the upgrade pre-process step, the upgrade step, and the upgrade post-process step. The upgrade post-process step runs in a separate Java virtual machine and the default heap size for this step is 1024 MB. If you experience out-of-memory exceptions during an upgrade, set this value higher. To specify a custom value, set the JAVA_OPTS environment variable using the form —Xmx<heap size> where heap size is a value, such as 2048m. An example is -Xmx2048m.
Use the Identity Manager installation and upgrade program to upgrade your Development environment.
Use one of the following methods to start the installer:
To use the GUI installer, run install.bat (for Windows) or install (for UNIX).
The installer displays the Welcome screen.
To activate the installer in nodisplay mode, change to the directory where the software is located, and type:
The installer displays the Welcome text, and then presents a list of questions to gather installation information in the same order as the GUI installer.
If no display is present, the installer defaults to the nodisplay option.
The installer does not install an older version of the software over a newer version. In this situation, an error message displays and the installer exits.
On the Welcome screen, click Next.
On the Install or Upgrade? screen, select Upgrade and click Next.
On the Select Installation Directory screen, select the directory where the earlier Identity Manager version is located and click Next.
The installer displays progress bars for the pre-upgrade and post-upgrade processes and then proceeds to Installation Summary screen.
For detailed information about the installation, click Details, view the log file, and click Close to exit the installer.
Remove all of the compiled Identity Manager files from the work directory of the application server.
In some environments, you might want to perform the upgrade steps manually instead of using the Identity Manager installation and upgrade program.
Make sure that you set the JAVA_HOME environment variable.
Make sure that the bin directory in the JAVA_HOME directory is in your path.
Any previously installed hotfixes will be archived to the $WSHOME/patches/HotfixName directory.
The instructions in this section are based on installing Identity Manager on a Tomcat application server. Depending on your application server, you might have to use slightly different commands.
Refer to the appropriate chapter in Part II, Installing Identity Manager, in Sun Identity Manager 8.1 Installation for application server-specific instructions.
Perform the following steps to upgrade Identity Manager manually on a supported Windows platform:
Stop the application server and Gateway.
Update the Identity Manager database.
Enter the following commands to set your environment:
set ISPATH=Path-to-install-software set WSHOME=Path-to-Identity-Manager-Installation OR Staging-Directory set TEMP=Path-to-Temporary-Directory |
If you have a space in the path to the Identity Manager installation directory, you must specify the WSHOME environment variable without double quotes ("), as shown in the following example.
Do not use trailing slashes (\) when specifying the path even if the path contains no spaces.
set WSHOME=c:\Program Files\Apache Group\Tomcat 6.0\idm |
or
set WSHOME=c:\Progra~1\Apache~1\Tomcat~1\idm |
The following path will not work:
set WSHOME="c:\Program Files\Apache Group\Tomcat 6.0\idm" |
mkdir %TEMP% cd /d %TEMP% jar -xvf %ISPATH%\IDM.WAR\ WEB-INF\lib\idm.jar WEB-INF\lib\idmcommon.jar set TMPLIBPTH=%TEMP%\WEB-INF\lib set CLASSPATH=%TMPLIBPTH%\idm.jar;\ %TMPLIBPTH%\idmcommon.jar; java -classpath %CLASSPATH% -Dwaveset.home=%WSHOME%\ com.waveset.install.UpgradePreProcess |
Install the software.
cd %WSHOME% jar -xvf %ISPATH%\IDM.WAR |
java -classpath %CLASSPATH% -Dwaveset.home=%WSHOME% com.waveset.install.UpgradePostProcess |
The upgrade post-process step runs in a separate Java virtual machine. The default heap size for this step is 1024 MB. If you experience out-of-memory exceptions during this step, set the maximum heap size value higher. To specify a custom value, set the JAVA_OPTS environment variable using the form —Xmx<heap size> where heap size is a value, such as 2048m. An example is -Xmx2048m.
The installer supports upgrading installations that have renamed, deleted, or disabled the default Configurator account.
The installer prompts you for the user name and password to import the update.xml during the upgrade post process. If the user name or password is typed incorrectly, you will be prompted (up to three times) to enter the correct name or password. The error will be displayed in the text box behind it.
For manual installation, you must provide the -U username -P password flags to pass the credentials to the UpgradePostProcess procedure.
If you installed into a staging directory, create a .war file for deployment to your application server.
Remove the Identity Manager files from the application server work directory.
Perform the following steps to upgrade Identity Manager manually on a supported UNIX platform:
Stop the application server and Gateway.
Update the Identity Manager database.
export ISPATH=Path-to-Install-Software export WSHOME=Path-to-Identity-Manager-Installation-or-Staging Directory export TEMP=Path-to-Temporary-Directory |
mkdir $TEMP cd $TEMP jar -xvf $ISPATH/idm.war \ WEB-INF/lib/idm.jar WEB-INF/lib/idmcommon.jar CLASSPATH=$TEMP/WEB-INF/lib/idm.jar:\ $TEMP/WEB-INF/lib/idmcommon.jar: java -classpath $CLASSPATH -Dwaveset.home=$WSHOME \ com.waveset.install.UpgradePreProcess |
Install the software.
cd $WSHOME jar -xvf $ISPATH/idm.war |
java -classpath $CLASSPATH -Dwaveset.home=$WSHOME com.waveset.install.UpgradePostProcess |
The upgrade post-process step runs in a separate Java virtual machine. The default heap size for this step is 1024 MB. If you experience out-of-memory exceptions during this step, set the maximum heap size value higher. To specify a custom value, set the JAVA_OPTS environment variable using the form —Xmx<heap size> where heap size is a value, such as 2048m. An example is -Xmx2048m.
The installer supports upgrading installations that have renamed, deleted, or disabled the default Configurator account.
The installer prompts you for the user name and password to import the update.xml during the upgrade post process. If the user or password is typed incorrectly, you will be prompted (up to three times) to enter the correct name or password. The error will be displayed in the text box behind it.
For manual installation, you must provide the -U username -P password flags to pass the credentials to the UpgradePostProcess procedure.
Change directory to $WSHOME/bin/solaris or $WSHOME/bin/linux, and set permissions on the files in the directory so that they are executable.
If you installed into a staging directory, create a .war file for deployment to your application server.
Remove the Identity Manager files from the application server work directory.
If you encounter problems during the upgrade, check the upgrade log files located in the $WSHOME/patches/logs directory. The file names for the logs are based on a time stamp and the stage of the upgrade.
Upgrade every Sun Identity Manager Gateway installation in your environment. Newer versions of Identity Manager server do not work with older versions of the Gateway.
Log in to the Windows system and change to the directory where Gateway is installed.
gateway -k |
If using at least Windows 2000, exit all instances of the Services MMC plug-in.
gateway -r |
Extract the new Gateway files.
If you are installing the newly upgraded Gateway on a system that is not the Identity Manager server, then copy the gateway.zip file from the Identity Manager installation package.
Unpack the gateway.zip file into the directory where Gateway was installed.
gateway -i |
gateway -s |
Unless the Release Notes specify otherwise, newly installed versions of the Identity Manager server provide limited, temporary support for older versions of PasswordSync. This support is provided so that Identity Manager can continue to run while you upgrade your PasswordSync instances. All instances of PasswordSync should be updated to the same version as Identity Manager Server as soon as possible.
To upgrade PasswordSync, you must uninstall each PasswordSync installation in your environment and reboot. Use the add/modify programs feature from the Windows Control Panel to ensure correct removal.
Replace each installation with the new PasswordSync version and reboot. Use the appropriate binary file for the operating system on which you are installing. The binary for 32-bit Windows is called IdmPwSync_x86.msi and the binary for 64-bit Windows is called IdmPwSync_x64.msi.
You must reboot Windows twice: Once after uninstalling PasswordSync, and once after installing the new version. The two reboots are necessary due to the way the Windows Security Service loads the PasswordSync DLL.
For installation instructions, see Installing and Configuring PasswordSync on Windows in Sun Identity Manager 8.1 Business Administrator’s Guide.
After successfully upgrading the Identity Manager product, make a copy of the existing configuration objects. Also, make a copy of other object types in the repository, or copy at least a representative sampling of those objects.
The Identity Manager product upgrade does not record the changes that it makes to repository objects. If you compare this snapshot to the snapshot that you took before the upgrade, you can easily detect any changes made to repository objects during the upgrade.
You must analyze the changes made by the Identity Manager product upgrade, and update your configurations and customizations accordingly. For example:
If you modified any JSP files or stylesheets, you must merge these changes into the new JSP files or stylesheets.
If your Identity Manager application baseline includes Identity Manager product JARs and third-party JARs, you might have to update these JARs in the baseline. Your baseline should also include the SQL scripts that are used to create or update your database tables.
If you modified any of the default Identity Manager objects (such as the Default User Form), the upgrade process moves those objects into the savedObjects directory. To facilitate future upgrades, rename the modified objects with a custom name, and reference that name in the SystemConfiguration object.
If you extracted WPMessages.properties to the /config directory and customized any of the messages, you must extract and reapply these customizations.
You must carefully analyze changes made to repository objects during the Identity Manager product upgrade. For example:
If the Identity Manager product upgrade modified configuration objects that are in your source-control baseline, you must merge these changes into your configuration baseline. For more information, see Step 14: Merge Changes Back Into Source Control.
If the Identity Manager product upgrade modified configuration objects that are not currently in your baseline, you must add these objects to your application baseline. If you do not add these configuration objects to your application baseline, then you must make other plans to incorporate these changes, such as including the appropriate objects or commands within the subset of update.xml that your upgrade procedure imports in each environment.
You might decide that you can safely ignore these object changes, but in most cases it is considered a best practice to add these configuration objects to your baseline.
If the Identity Manager product upgrade modified objects in the repository that are not configuration objects, then these objects should not become part of your source-control baseline. For example, the Identity Manager update.xml file might refresh TaskInstance objects, User objects, Account objects, or Entitlement objects.
Identity Manager Engineering generally avoids updating these object types because there can be so many instances of each type, but in some cases changes are necessary or justified. In such cases, include executing an appropriate subset of the Identity Manager update.xml file in your baseline and in your upgrade process. Use this update.xml subset to update repository objects that are not part of your baseline.
After upgrading, restore any customized files and objects.
During the upgrade, Identity Manager automatically copies all customized files, such as JSP and HTML files, into the following directory:
$WSHOME/patches/Sun_Java_System_Identity_Manager_Version_Date_/savedFiles
The following table describes the files in this directory.
Table 3–1 savedFiles Directory File Structure
File Name |
Description |
---|---|
File containing a list of all saved customized files. This file also contains a list of files (installed with your older version of Identity Manager) that will be overwritten when files of the same name are installed during upgrade. |
|
File containing a list of all customized files that are not restored during the upgrade process. |
|
File containing a list of newer version files that are not installed during the upgrade process. |
The upgrade might add some files that were also installed with your original Identity Manager installation. Before overwriting the older files, Identity Manager automatically saves them in the savedFiles directory. See the changedFileList file for a list of these files.
Identity Manager automatically restores most of the files listed in changedFileList during the upgrade process, but does not restore all of them. See the notRestoredFileList for a list of these files. When restoring customized files, Identity Manager overwrites the newer version of the files that were installed during the upgrade.
You might have to manually restore some of your file customizations. Review the notRestoredFileList file to see a list of the files that were not restored during upgrade. If you must manually restore any customized files, edit the new file that was installed during the upgrade to incorporate your customizations, and then save the newly edited file.
If you have configured your form and process mappings in the system configuration, you will not have to restore those object customizations after the upgrade. If you have customized objects that are not listed in the system configuration, then you must manually restore these objects by importing the XML for these objects.
As a safety measure, Identity Manager automatically saves many of the commonly customized objects to files when you import update.xml. These files are saved to subdirectories in the WEB-INF/savedObjects directory. These subdirectories are named with a time stamp of the time at which the import was performed.
Importing update.xml can create up to three subdirectories in the savedObjects directory. You can manually import the object XML files to restore object customizations.
You must rebuild all of your custom Java classes against the new product libraries. For example, you must rebuild any new JAR files or application server libraries.
If recompiling produces deprecation warnings, analyze each deprecation message, and read the Sun Identity Manager 8.1 Release Notes to determine whether you can resolve the deprecation issue immediately. If you cannot resolve the deprecation issue immediately, add an item to your project plan to resolve the issue in the future.
Identity Manager does not support deprecated APIs indefinitely. Deprecated classes and methods are generally removed in the next major product release.
Make any forms, rules, and workflows changes in XPRESS.
The forms, rules, and workflows supplied in new Identity Manager product versions are generally backward-compatible with older forms, rules, and workflows. The most common type of change required is to change invocations of Identity Manager Workflow Services or Form Utility methods.
For information about release-specific changes to Workflow Services or Form Utility methods, see the Identity Manager Release Notes for the release to which you are upgrading.
Restart the application server and test your Identity Manager application at least minimally to confirm that at least the basic functions are working as expected.
You must redeploy your web applications after upgrading Identity Manager because most application servers cache the web.xml file.
If you are using the Sun GlassFishTM Enterprise Server, for example, you would perform the following steps to redeploy a web application after upgrading Identity Manager:
Log in to the GlassFish administrator interface.
Choose Applications > Web Applications from the menu bar.
Locate your web application and click the Redeploy link.
Click the button next to the Local Packaged File or Directory That Is Accessible From the Application Server option.
Click the Browse Folders button and select the top-level folder for your installation.
For example:
C:\Sun\AppServer\domains\domain1\applications\j2ee-modules\idm
Click OK.
Restart the application server.
After successfully upgrading, you must restore the original settings for any Active Sync processes and reenable any scheduled reconciliations (if applicable).
Step 13 is optional, but performing this step is considered a best practice when upgrading the Production environment.
Also, if you perform Step 13 in your Production environment, make it a standard step when upgrading all of your other environments.
Merging changes back into source control is specifically listed here as a separate step to highlight its importance. In actual practice, you can merge changes back into source control as you perform Steps 9 through 12.
When merging changes back into source control, you must: