Careful 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:
Upgrading 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 that you perform when reviewing your Production environment:
If you use source control and CBE to manage this information, these can serve as the documentation for your Identity Manager installation and for your custom components. Review the information and familiarize yourself with the various environments in which you deploy your Identity Manager application, giving particular attention to your Production environment.
To determine the best upgrade path, use the worksheets provided in Chapter 7, Assessment Worksheets to inventory the components of your current platform, including the following:
Verify that you are using the correct version of these components for the upgrade version that you want to install. Check Supported Software and Environments in Sun Identity Manager 8.1 Release Notes for details.
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.
Record the application server version, and note any additional patches or service packs. In addition, record the following:
Operating system version and any additional patches or service packs.
Java Development Kit (JDKTM) version required by your application server. When upgrading Identity Manager, you must use a JDK supplied by the same vendor.
Record the database server version, and note any additional patches or service packs.
Verify which Identity Manager Gateway version you are running by performing the following steps:
Open a command window and execute the following command on each of the Gateway servers:
gateway -v |
Record the results.
Record the operating system version of each Gateway server.
The Gateway server version should always be the same as the Identity Manager version.
Record the currently installed JRETM version required by the lh console. Also record the name of the vendor that supplied the installed JRE (for example, Sun, IBM, Oracle, and so on). When upgrading Identity Manager, you must use a JRE supplied by the same vendor.
Record supported resource names and versions, and note any additional patches or service packs.
Record the Web server version, and note any additional patches or service packs.
To determine the best upgrade path, use the worksheets provided in Chapter 7, Assessment Worksheets to inventory the components of your current Identity Manager installation.
The following sections describe methods for collecting this information:
To verify the version number of your current Identity Manager installation, use the Identity Manager Console .
lh console
To display the Identity Manager version number, type:
version
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.
To access the installed and inventory utilities, follow these steps:
Open a command window and change directories to $WSHOME/bin.
At the prompt, execute the following command:
At the prompt, type one of the following commands:
installed [option] [option]...
inventory [option] [option]...
The following tables describe the options that you can use with the installed and inventory utilities.
installed Utility Options
Option |
Function |
Description |
---|---|---|
-h |
Help |
Displays usage. |
-r |
Releases |
Displays only installed releases. |
-p |
Patches |
Displays only installed patches. |
-s |
Service packs |
Displays only installed service packs. |
-f |
Hotfixes |
Displays only installed hotfixes. |
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 |
inventory Utility Options
Option |
Function |
Description |
---|---|---|
-a |
Added |
Displays only added files. |
-d |
Deleted |
Displays only deleted files. |
-h |
Help |
Displays usage. |
-m |
Modified |
Displays only modified files. |
-u |
Unchanged |
Displays only unchanged files. |
Use the worksheets provided in Chapter 7, Assessment Worksheets to inventory your custom components, including the following:
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.
Version 7.1 and version 8.0 of Identity Manager made significant changes to the Identity Manager database table definitions.
If you previously modified the database table definitions for the Identity Manager repository, you must decide whether to make the same modifications to the new and updated tables.
You might need to update your customized file system objects to enable them to function properly with later Identity Manager releases. List any customized file system object names that are in your environment as explained in the following sections.
Recent Identity Manager versions might contain API changes. If you have modified .jsp files 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.
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 Identity Manager Assessment Tools) to identify any JSP modifications made in your deployment.
For more information about JSP customizations, see Chapter 11, Editing Configuration Objects, in Sun Identity Manager 8.1 Technical Deployment Overview.
Record any changes that you made to the default Waveset.properties file.
Record any changes that you made to the default WPMessages.properties file.
Record any changes that you made to other property files on your system.
You might have to recompile your custom resource adapters, depending on the target Identity Manager version. All custom Java code that uses Identity Manager APIs (including custom resource adapters) requires a recompile during upgrading. Also, consider other Java classes that use the Identity Manager library.
Record any changes that you made to the Identity Manager stylesheets.
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 as explained in the following sections.
You can use the Identity Manager 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.
You might have to update customized forms to take advantage of current product enhancements.
You might have to update customized workflows to take advantage of current product enhancements.
You might have to export customized email templates to take advantage of current product enhancements.
Significant schema changes occurred between Version 7.0 and Version 8.0 of Identity Manager. If you are upgrading from an earlier version of Identity Manager, you must update your schema.
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 reimport them to the newer version of Identity Manager after upgrading.
Admin group |
Resource form |
Admin role |
Role |
Configuration |
Rule |
Policy |
Task definition |
Provisioning task |
Task template |
Remedy configuration |
User form |
Resource action |
|
The SPML 2.0 implementation in Identity Manager changed in version 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 the Identity Manager SnapShot feature to copy the following, specific object types from your system for comparison:
AdminGroup |
ResourceAction |
AdminRole |
Resourceform |
Configuration |
Role |
EmailTemplate |
Rule |
Policy |
TaskDefinition |
ProvisionTask |
TaskTemplate |
RemedyConfig |
UserForm |
For specific instructions, see Step 5: Take a Snapshot.
For the most current description of Identity Manager upgrade paths, see the Upgrade Paths and Support Policies in Sun Identity Manager 8.1 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 version 7.1.1, as this Identity Manager version was the most current release available when you started your current test cycle. Assume further that the next new 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, 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 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 hotfixes you need.
Sun’s new patch process replaces the older hotfix 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.
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 Phases of a Skip-Level Upgrade, which describes how a skip-level upgrade changes the tasks described in this section.
Before proceeding to the next phase of the upgrade, be sure that 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, create one now using the guidelines described in Create a Test Plan.
Does your existing test plan address everything that 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 that 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.
You must create a test plan if you do not already have one prepared for your Identity Manager application. A generic test plan includes:
Introduction
Description of this document
Related documents
Schedule and milestones
Hardware
Software (test tools)
Staffing
Features you are going to test and the test approach
New features testing
Regression testing
Features you are not going to test
Test deliverables
Dependencies and risks
Entrance and exit criteria
Before proceeding to the next phase of the upgrade, be sure that you have prepared a current, comprehensive upgrade procedure. See Upgrade Process and Upgrade Procedure for more information.
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 prepared an upgrade procedure, create one now using the guidelines described in Create an 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, 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 that 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.
You must create an upgrade procedure if you have not already prepared one for your Identity Manager application.
The following is generally true of an update procedure:
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 host names 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.