Chapter 2 Planning

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:

Task 1: Review Your Production Environment

Upgrading to a newer Waveset 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 Waveset installation and for your custom components. Review the information and familiarize yourself with the various environments in which you deploy your Waveset application, giving particular attention to your Production environment.

Step 1: Document Your Platform

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 Oracle Waveset 8.1.1 Release Notes for details.

If you are using an Oracle repository, the Waveset 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 Waveset to work properly.

Application Servers

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 (JDK) version required by your application server. When upgrading Waveset, you must use a JDK supplied by the same vendor.

Database Servers

Record the database server version, and note any additional patches or service packs.

Waveset Gateway

Verify which Waveset Gateway version you are running by performing the following steps:

1. Open a command window and execute the following command on each of the Gateway servers:

   gateway -v

2. Record the results.

3. Record the operating system version of each Gateway server.

   ---

   Note –

   The Gateway server version should always be the same as the Waveset version.

   ---

Java Runtime Environment

Record the currently installed JRE 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 Waveset, you must use a JRE supplied by the same vendor.

Supported Resources

Record supported resource names and 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 Waveset Installation

To determine the best upgrade path, use the worksheets provided in Chapter 7, Assessment Worksheets to inventory the components of your current Waveset installation.

The following sections describe methods for collecting this information:

Waveset Version

To verify the version number of your current Waveset installation, use the Waveset Console .

1. From the command line, type:

   lh console

2. To display the Waveset version number, type:

   version

Waveset Assessment Tools

Waveset 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 Waveset.

To access the installed and inventory utilities, follow these steps:

1. Open a command window and change directories to $WSHOME/bin.

2. At the prompt, execute the following command:

   ./lh assessment

3. 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

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

Step 3: Document Your Custom Components

Use the worksheets provided in Chapter 7, Assessment Worksheets to inventory your custom components, including the following:

• Customized Database Table Definitions

• Custom File System Objects

• Custom Repository Objects

• 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 Waveset installation has a large amount of custom work, contact Sun Professional Services for assistance with your upgrade.

Customized Database Table Definitions

Version 7.1 and version 8.0 of Waveset made significant changes to the Waveset database table definitions.

If you previously modified the database table definitions for the Waveset repository, you must decide whether to make the same modifications to the new and updated tables.

Custom File System Objects

You might need to update your customized file system objects to enable them to function properly with later Waveset releases. List any customized file system object names that are in your environment as explained in the following sections.

Modified JavaServer Pages Files

Recent Waveset 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 Waveset and changed during a deployment (or a custom JSP that uses Waveset APIs) to work with the new JSP structure and API changes for the target release.

For a detailed description of API changes, see the Waveset Release Notes for the release to which you are upgrading.

Use the inventory -m command (described on Waveset 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.

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 Waveset version. All custom Java code that uses Waveset APIs (including custom resource adapters) requires a recompile during upgrading. Also, consider other Java classes that use the Waveset library.

Modified Stylesheets

Record any changes that you made to the Waveset stylesheets.

Custom Repository Objects

You might have to maintain customized repository objects to enable them to function properly with target Waveset releases. Record any customized repository objects that are in your environment as explained in the following sections.

You can use the Waveset 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 Version 7.0 and Version 8.0 of Waveset. If you are upgrading from an earlier version of Waveset, 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 reimport them to the newer version of Waveset after upgrading.

The SPML 2.0 implementation in Waveset changed in version 8.0. In previous releases, the SPML objectclass attribute used in SPML messages was mapped directly to the objectclass attribute of Waveset 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.

Waveset 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 Waveset 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 Waveset Version

For a current description of Waveset upgrade paths, see the Oracle Waveset Upgrade Paths in Oracle Waveset 8.1.1 Release Notes.

In general, you should upgrade to the most recent Waveset release that is available during your testing time frame. For example, assume that you are testing now with version 7.1.1, as this Waveset 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 Waveset product. If not, plan to update the platform in each environment before you upgrade your Waveset 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 Waveset product version and the target Waveset 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 Waveset application.

The standard upgrade processes that are part of each full release of Waveset generally upgrade an existing installation from any version of the previous major release.

Review the Release Notes for the target version of Waveset 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 Waveset 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 Waveset version contains all of the hotfixes you need.

If you want to upgrade your Waveset 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.

Task 3: Prepare Your Test Plan

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 Waveset 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.

Review Your Existing 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 Waveset application consumes, then be sure that your test plan also measures these items.

After upgrading the Waveset product or after making any significant change to your Waveset configurations or customizations, be sure to retest your Waveset application.

Create a Test Plan

You must create a test plan if you do not already have one prepared for your Waveset application. A generic test plan includes:

1. Introduction

   • Description of this document

   • Related documents

   • Schedule and milestones

2. Resource requirements

   • Hardware

   • Software (test tools)

   • Staffing

3. Features you are going to test and the test approach

   • New features testing

   • Regression testing

4. Features you are not going to test

5. Test deliverables

6. Dependencies and risks

7. Entrance and exit criteria

Task 4: Prepare Your Upgrade Procedure

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 Waveset application in each environment. You will develop and maintain this upgrade procedure as you upgrade your Waveset 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.

Review Your Existing Upgrade Procedure

Does your existing upgrade procedure specify exactly who does what and when as you upgrade your Waveset 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.

Create an Upgrade Procedure

You must create an upgrade procedure if you have not already prepared one for your Waveset 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 Waveset application integrates with external applications. You might also be required to notify users or systems personnel before taking the Waveset 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.