Sun[TM] Identitiy Manager 8.0 Upgrade |
Chapter 2
PlanningCareful preparation allows for a smoother upgrade. Listing your goals for the upgrade can help you make decisions that are appropriate for your company’s needs.
The Planning phase of the upgrade process includes the following tasks:
Task 1: Review Your Production Environment
Task 2: Choose the Target Identity Manager Version
Task 3: Prepare Your Test Plan
Task 4: Prepare Your Upgrade Procedure
Task 1: Review Your Production EnvironmentUpgrading to a newer Identity Manager release might require changes to the platform in your environment. You can determine the best upgrade path and estimate the complexity of the upgrade by assessing and documenting your Production environment.
This section describes the steps you perform when reviewing your Production environment:
Step 1: Document Your Platform
Step 2: Document Your Identity Manager Installation
Step 3: Document Your Custom Components
Step 1: Document Your Platform
To determine the best upgrade path, use the worksheets provided in Appendix B, "Assessment Worksheets" to inventory the components of your current platform, including:
Note
Verify that you are using the correct version of these components for the upgrade version you want to install. Check the “Supported Software and Environments” sections in the Identity Manager Installation and Identity Manager Release Notes provided for the Identity Manager version to which you want to upgrade.
Caution
If you are using an Oracle repository, the Identity Manager 8.0 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 oracle11g_jdbc.jar drivers for Identity Manager to work properly.
Application Servers
Record the application server version and note any additional patches or service packs. In addition, record the following:
Database Servers
Record the database server version and note any additional patches or service packs.
Sun Identity Manager Gateway
Verify which Sun Identity Manager Gateway version you are running by performing the following steps:
Java Runtime Environment
Record the currently installed JRE version required by the lh console.
Supported Resources
Record supported resources names, versions, and note any additional patches or service packs.
Web Servers
Record the Web server version and note any additional patches or service packs.
Step 2: Document Your Identity Manager Installation
To determine the best upgrade path, use the worksheets provided in Appendix B, "Assessment Worksheets" to inventory the components of your current Identity Manager installation.
The following sections describe methods for collecting this information:
Identity Manager Version
Use the Identity Manager Console to verify the version number of your current Identity Manager installation.
Identity Manager Assessment Tools
Identity Manager provides the following utilities to list and record your installation information:
- installed Utility: Searches the $WSHOME/bin directory for manifests and provides version information for releases, patches, service packs, and hotfixes.
- inventory Utility: Inspects the file system for files that were added to or deleted from the system, using files that are packaged in the release. This utility determines which files were changed based on the manifest that shipped with Identity Manager.
You can access both utilities as follows:
The following tables describe the options you can use with the installed and inventory utilities.
Table 2-1 installed Utility Options
Option
Function
Description
-h
help
Display usage.
-r
releases
Display only installed releases.
-p
patches
Display only installed patches.
-s
service packs
Display only installed service packs.
-f
hotfixes
Display only installed hotfixes.
Note
Be sure to record the manifest file names that are associated with all service packs or patches. For example:
Identity_Manager_8_0_0_0_20080530.manifest
Table 2-2 inventory Utility Options
Option
Function
Description
-a
added
Display only added files.
-d
deleted
Display only deleted files.
-h
help
Display usage.
-m
modified
Display only modified files.
-u
unchanged
Display only unchanged files.
Step 3: Document Your Custom Components
Use the worksheets provided in Appendix B, "Assessment Worksheets" to inventory your custom components, including:
Note
- If you are using the Identity Manager IDE or an older version Consolidated Build Environment (CBE), these component customizations should already be part of your baseline. In this case, the CBE baseline serves as your documentation.
- If your current Identity Manager installation has a large amount of custom work, contact Sun Professional Services for assistance with your upgrade.
Customized Database Table Definitions
Identity Manager version 7.1 and version 8.0 made significant changes to Identity Manager’s database table definitions.
If you previously modified the database table definitions for the Identity Manager repository, you must carefully decide whether to make the same modifications to the new and updated tables.
Custom Filesystem Objects
You might need to update your customized filesystem objects to enable them to function properly with later Identity Manager releases. List any customized filesystem object names that are in your environment, including:
Modified JSPs
Recent Identity Manager versions might contain API changes. If you have modified JSPs in your installation, you might have to update them when upgrading. You must update any JSP that was supplied by Identity Manager and changed during a deployment (or a custom JSP that uses Identity Manager APIs) to work with the new JSP structure and API changes for the target release.
Note
For a detailed description of API changes, see the Identity Manager Release Notes for the release to which you are upgrading.
Use the inventory -m command (described on (more...) ) to identify any JSP modifications made in your deployment.
For more information about JSP customizations, see Appendix A, “Working with Configuration Objects,” in the Sun Identity Manager Technical Deployment Overview.
Modified Waveset.properties File
Record any changes that you made to the default Waveset.properties file.
Modified WPMessages.properties File
Record any changes that you made to the default WPMessages.properties file.
Customized Property Files
Record any changes that you made to other property files on your system.
Custom Resource Adapters (and Other Custom Java)
You might have to recompile your custom resource adapters, depending on the target Identity Manager version. All custom Java that uses Identity Manager APIs (including custom resource adapters) require a recompile during upgrading. Also, consider other Java classes that use the Identity Manager library.
Modified Stylesheets
Record any changes that you made to Identity Manager stylesheets.
Custom Repository Objects
You might have to maintain customized repository objects to enable them to function properly with target Identity Manager releases. Record any customized repository objects that are in your environment, including:
Note
You can use Identity Manager’s SnapShot feature to create a baseline or snapshot of the customized repository objects in your deployment, which can be very useful when planning an upgrade. See Step 5: Take a Snapshot for more information.
Modified Forms
You might have to update customized forms to take advantage of current product enhancements.
Modified Workflows
You might have to update customized workflows to take advantage of current product enhancements.
Modified Email Templates
You might have to export customized email templates to take advantage of current product enhancements.
Custom Repository Schema
Significant schema changes occurred between Identity Manager version 7.0 and version 8.0. If you are upgrading from an earlier version of Identity Manager, you must update your schema.
Other Custom Repository Objects
Record the names of any other custom repository objects that you created or updated. You might have to export these objects from your current installation and then re-import them to the newer version of Identity Manager after upgrading.
Note
The SPML 2.0 implementation in Identity Manager has changed in Identity Manager 8.0. In previous releases, the SPML objectclass attribute used in SPML messages was mapped directly to the objectclass attribute of Identity Manager User objects. The objectclass attribute is now mapped internally to the spml2ObjectClass attribute and is used internally for other purposes.
During the upgrade process the objectclass attribute value is automatically renamed for existing users. If your SPML 2.0 configuration contains forms that reference the objectclass attribute, you must manually change those references to spml2ObjectClass.
Identity Manager does not replace the sample spml2.xml configuration file during an upgrade. If you used the spml2.xml configuration file as a starting point, be aware that this file contains a form with references to objectclass that you must change to spml2ObjectClass. Change the objectclass attribute in forms (where it is used internally), but do not change the objectclass attribute in the target schema (where the attribute is exposed externally).
You can use Identity Manager’s SnapShot feature to copy the following, specific object types from your system for comparison:
For specific instructions, see Step 5: Take a Snapshot.
Task 2: Choose the Target Identity Manager Version
Note
For the most current description of Identity Manager upgrade paths, see the “Upgrade Paths and Support Policies” section in the Identity Manager Release Notes.
In general, you should upgrade to the most recent Identity Manager release that is available during your testing time frame. For example, assume that you are testing now with Identity Manager 7.1.1, as this version was the most current release available when you started your current test cycle. Assume further that the next new Identity Manager release, 7.1.2, is scheduled for July 10th, and that July 15th is the projected start date of your next test cycle. You should plan to upgrade to 7.1.2 when you start your next test cycle.
Be sure that the platform in your Production environment supports the new version of the Identity Manager product. If not, plan to update the platform in each environment before you upgrade your Identity Manager application. Reset each target environment to match the Production platform before upgrading that target environment. In general, you must update your platform as part of the upgrade procedure that you follow in each target environment.
In cases where both your current Identity Manager product version and the target Identity Manager version support the updated platform, then you can update your platform as a separate change and promote this change all the way to your Production environment before upgrading your Identity Manager application.
The standard upgrade processes that are part of each full-release of Identity Manager generally upgrade an existing installation from any version of the previous major release.
Review the Identity Manager Release Notes for the target version of Identity Manager to which you plan to upgrade. The Release Notes document release-specific upgrade considerations. They also contain documentation addenda, bug fixes, and known issues.
Consider your configurations and customizations, and then identify any changes in the Identity Manager product that might affect those configurations and customizations.
Check your current release to see which hotfixes you have installed. Find the bug number associated with each hotfix, and check the Release Notes to confirm that the new, target Identity Manager version contains all of the hot fixes you need.
Note
Sun's new patch process replaces the older hot-fix process. The patch process is cumulative, so you can expect fewer problems with unique fixes. The patch process also makes it easier for you to track a fix by its actual bug number. However, it is still possible that a fix made against an older version might not yet be available in a newer version. Regardless of which process your current version of Identity Manager follows, you must confirm that the new, target Identity Manager version contains all of the bug fixes that you need.
Note
If you want to upgrade your Identity Manager application more than one level (that is, beyond the next major version from your current version), you must read Appendix A, "Skip-Level Upgrade Considerations." This appendix describes how a skip-level upgrade changes the tasks described in this section.
Task 3: Prepare Your Test PlanBefore proceeding to the next phase of the upgrade, be sure you have prepared a current, comprehensive test plan. The goal of a test plan is to confirm that all your current Identity Manager application functionality remains intact through the upgrade process.
- If you have an existing test plan, read Review Your Existing Test Plan.
- If you have not a prepared test plan yet, create one now using the guidelines described in Create a Test Plan.
Review Your Existing Test Plan
Does your existing test plan address everything you want to test? Is it up-to-date? Is it specific? If not, you must revise your test plan appropriately.
If you are particularly concerned with the performance of a particular set of functions or with items such as the amount of system memory or database space the Identity Manager application consumes, then be sure your test plan also measures these items.
After upgrading the Identity Manager product or after making any significant change to your Identity Manager configurations or customizations be sure to retest your Identity Manager application.
Create a Test Plan
You must create a test plan if you do not already have one prepared for your Identity Manager application. A generic test plan includes:
Task 4: Prepare Your Upgrade ProcedureBefore proceeding to the next phase of the upgrade, be sure you have prepared a current, comprehensive upgrade procedure. See Upgrade Process and Upgrade Procedure.
The goal of an upgrade procedure is to specify exactly who does what as you upgrade your Identity Manager application in each environment. You will develop and maintain this upgrade procedure as you upgrade your Identity Manager application in each environment.
- If you have an existing upgrade procedure, read Review Your Existing Upgrade Procedure.
- If you have not yet prepared an upgrade procedure, create one now using the guidelines described in Create an Upgrade Procedure.
Review Your Existing Upgrade Procedure
Does your existing upgrade procedure specify exactly who does what and when as you upgrade your Identity Manager application in each environment? Is it clear how and why the procedure differs in each environment? Is your procedure up-to-date? Does your upgrade procedure contain the same steps for your Test environment and for your QA environment that it does for your Production environment? If not, you must revise your upgrade procedure appropriately.
Are there important considerations that are unique to your Production environment? If so, then your upgrade procedure must rehearse the same steps in your QA environment. See Special Considerations for Production. If the duration of the upgrade procedure in your Production environment is important, then be sure your upgrade procedure says to record the duration of each step in each environment. Upgrading your QA environment should give you a particularly good indication of how long it will take to upgrade your Production environment.
Create an Upgrade Procedure
You must create an upgrade procedure if you have not already prepared one for your Identity Manager application.
An upgrade procedure generally:
- Takes the form of a checklist. Your upgrade procedure may include supporting documentation, but the administrator who performs the upgrade procedure will want a clear, complete, and concise set of instructions.
- Includes most, if not all, of the steps described in Task 8: Execute Your Upgrade Procedure. Your upgrade procedure is generally far more specific, spelling out exactly who must do what in each environment. For example, your procedure must include specific commands and specific parameter values that an administrator must issue in each environment.
- Includes additional steps. For example, you might have to stop and restart external processes if your Identity Manager application integrates with external applications. You might also be required to notify users or systems personnel before taking the Identity Manager application or other affected applications offline.
- Is the same for each target environment. Specific parameter values, such as hostnames and connection information, might vary from environment to environment. The steps in the procedure, however, should be the same in each environment. Even if, for example, there is no one to notify about application downtime in a Test environment or a QA environment, you should rehearse this step in each environment.
- Includes a timetable. Estimate the expected duration for each step, and record the actual duration of each step. The durations that you see in your QA environment are particularly important for predicting the durations that you will see in your Production environment.