Oracle Waveset 8.1.1 Upgrade

Chapter 1 Overview of the Upgrade Process

This chapter provides a general introduction to the upgrade process.

Why Upgrade?

Upgrading your release of Sun Identity Manager software (Identity Manager) to Oracle Waveset provides several advantages, including the following:

Upgrade Paths and Support Policies

Waveset Upgrade Paths

To determine the upgrade path you must follow when upgrading to Waveset, see Oracle Waveset Upgrade Paths in Oracle Waveset 8.1.1 Release Notes. Generally, use the latest available patch or service pack for the version to which you are upgrading.

Using nonstandard upgrade techniques is strongly discouraged because serious, nonobvious consequences can result.

The standard upgrade process performs steps that are necessary to convert existing repository objects into the format that the newer version of Waveset expects. In particular, the updater programs that are shipped with this version of Waveset contain special logic that preserves the original meaning and behavior of these objects. Each updater program updates a specific type of configuration object, and each updater is invoked by an ImportCommand within update.xml or within a file that update.xml includes. Updated versions of preexisting objects often use slightly different mechanisms than those used in the sample objects that ship with the new Waveset version.


Caution – Caution –

If you are upgrading Waveset, you must follow the required upgrade path noted in Software Support and Software Deprecation Policies in Oracle Waveset 8.1.1 Release Notes. The updater programs that are shipped with each version of Identity Manager and Waveset work only with that version.

Simply comparing the objects that are produced by importing the new init.xml file with the objects that are produced by importing the old init.xml file is not a sufficient way to detect the changes that must be made in order to upgrade existing repository objects. Comparing these two sets of objects is a quick way to estimate the effort associated with an upgrade, but the standard upgrade path is the best way to achieve a safe and complete upgrade.


End of Service Life for Software Support

For details about the End of Service Life (EOSL) policy for Waveset software see End of Service Life for Software Support in Oracle Waveset 8.1.1 Release Notes.

Waveset Deprecation Policy

For details about the deprecation policy for Waveset software see Oracle Waveset Deprecation Policy in Oracle Waveset 8.1.1 Release Notes.


Note –

Deprecations are announced in Chapter 6, Deprecated APIs, in Oracle Waveset 8.1.1 Release Notes.

When upgrading, always check the Release Notes for the new Waveset version to get the latest information about deprecated features.


How Easy Is Upgrading?

Basically, how easy or how difficult it is to upgrade to Waveset depends on the customizations that you have made. Some customizations are highly backward-compatible. For example, older workflows, forms, and rules tend to work without modification on newer versions of Waveset. Other customizations are more volatile and require additional work to integrate them with new versions of Waveset. For example, you might have to recompile or rewrite integration code that invokes Java classes that are part of the Waveset product.

The most significant effect of customization, however, is that customization changes how you must approach upgrading Waveset. Note that the following discussion uses terminology and concepts described in Terminology and Concepts.

Upgrading Waveset can be relatively simple if you use the product as shipped—that is, if you configure Waveset but do not customize it. If you are unfamiliar with these terms, see Configurations and Customizations. The upgrade process that is part of each version of the Waveset product was originally designed to be run in each environment. The product upgrade process automatically preserves your configuration settings as it updates the Waveset configuration objects and other repository objects to work with the newer version of code. The upgrade process, however, does not know how to update your customizations. In fact, the upgrade process ignores most customizations. The upgrade process does save off the customized version of any file that the upgrade process intends to replace, but this is the most that the upgrade process can do automatically.

If you customize Waveset, as the vast majority of customers do, then you cannot run the standard Waveset product upgrade in each environment. You must maintain and must retest your customizations after you upgrade the Waveset product, and you want to be certain that exactly what you tested goes into each environment. Because Waveset is often customized extensively, those who deploy Waveset have developed sophisticated practices for managing their customizations. For more information, see Source Control and CBE.

If you customize Waveset, the most common approach is to manage your customizations by maintaining a baseline and then to generate and promote an image of your Waveset application into each target environment. See Baseline and Image. You apply the standard Waveset product upgrade process only in your Development environment. You then apply to your application baseline most of the changes that the upgrade makes. See Waveset Product Compared With Waveset Application. However, your upgrade procedure also must include some pieces of the Waveset product upgrade. For example, your upgrade procedure will include some subset of update.xml to update repository objects that are not managed as part of your baseline. Your upgrade procedure might also include database table scripts to update the Waveset repository table definitions.

Because the vast majority of customers do customize Waveset, and because many customize Waveset extensively, this document assumes that you have customizations and that you manage your customizations with this approach.

Terminology and Concepts

This section describes some specialized terminology that relates to upgrading Waveset.

Waveset Product Compared With Waveset Application

In some sections, this document distinguishes between the Waveset product and your Waveset application.

Development, Test, QA, and Production Environments

This document assumes that you are using the following, different types of environments:

Promotion

In this document, promotion refers to the process of generating a particular version of your Waveset application and moving that version from Development to Test, from Test to QA, and finally from QA to Production.

Source Control and CBE

You should use source-control tools to manage your configuration settings, any custom configuration objects, any custom code, any test plans, and any automated tests. Any source-control tool, such as CVS or Subversion, should allow you to track changes to any number of individual, text, or binary files and to reproduce a particular version of the Waveset application. This document refers to these tools generically as source control.

Some of these source-controlled files must be tailored for each environment. In particular, configuration objects contain values that often change for each environment. A particular Waveset resource object might point to one host machine in your Development environment, to another host machine in your Test environment, and to a third host machine in your Production environment.

Many customers use the Sun Identity Manager plug-ins for NetBeans and Eclipse to generate a tailored version of the Waveset application for each environment. The Identity Manager IDE plug-ins include a Configuration Build Environment (CBE). Some customers use older versions of the CBE that predate the Identity Manager IDE plug-in. A few customers use other tools and approaches, including proprietary or home-grown mechanisms. This document refers to these tools generically, and to the Role Manager IDE specifically, as CBE.

The Identity Manager IDE plug-in and older CBE versions parameterize configuration objects (and can parameterize code) by replacing environment-specific values with placeholder values. To generate an image of the Waveset application that is appropriate to each environment, these tools replace the placeholder values with configured values that are appropriate to each environment. If you manage the parameterized objects in source control, you can “build out” the same version of the Waveset application for each target environment using a process that is predictable and repeatable.

Baseline and Image

In this document baseline refers to a tagged level of artifacts, which includes configuration objects, libraries, and custom code in source control, that corresponds to a particular version of your Waveset application. Your CBE can generate from this baseline an image of the Waveset application that is appropriate to each target environment. An image is a complete, working copy of the application that has been tailored for a specific environment.

At a minimum, your source control must contain a baseline for the version of your Waveset application that is currently deployed in your Production environment. Your source control can also contain baselines for previous versions of your Waveset application and baselines for versions of your Waveset application that you are still developing in preparation to roll out new functionality (such as modified configurations, modified workflows, modified forms, and new custom code for integrations).

Any baseline should be complete enough that you can use it to rebuild the corresponding version of your Waveset application. Some customers include the Waveset product itself within that baseline. Other customers save the Waveset product image separately and use the baseline artifacts to overlay that product image with their own configurations and customizations.

Skip-Level Upgrade

A skip-level, or multi-hop, upgrade updates your Production environment to an Oracle Waveset product version that is beyond the next major release from its current version. A skip-level upgrade typically requires a series of upgrades, but it is technically possible, and some customers find it feasible, to develop a single upgrade procedure that updates a target environment directly to the target Waveset version.


Note –

Chapter 6, Skip-Level Upgrade Considerations describes special considerations for a multi-hop upgrade. If you are uncertain about how to proceed, or if these considerations seem unclear to you, contact Professional Services for assistance with planning and executing your upgrade.


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

Configurations and Customizations

In this document, the term configuration means editing configuration objects in the Waveset product. You can edit configuration objects by using the Waveset Administrator Interface or by editing repository objects in accordance with published documentation. For example, configuration includes specifying values in System Configuration or in a Reconciliation Policy. Configuration also includes defining Resource objects that represent the target systems and applications that Waveset will manage.

For the purposes of this document, the term customization refers to any code, file, or repository object that you write. Customizations include adding your own Java code, adding or modifying JSP files, and writing your own XPRESS code such as workflow, forms, and rules. Creating your own configuration objects or message catalogs is also considered customization.

Note that Professional Services defines these terms somewhat differently. For example, Professional Services might consider customer-specific workflows to be configurations.

In this document, however, the key distinction is that the Waveset product upgrade automatically preserves and updates customer-specified values within certain well-known objects and within instances of certain well-known types of objects. These are configurations. The Waveset product upgrade does not attempt to modify customer-written code or objects. These are customizations.

Upgrade Process and Upgrade Procedure

In this document, upgrade process refers to the upgrade mechanisms that are part of every version of the Waveset product. Each new version of Waveset contains not only updated code, but also an update.xml script. This update.xml script carefully preserves your configuration settings as it updates existing repository objects to work with the updated code. Any full release of Waveset might also contain sample database table scripts. These sample database table scripts carefully migrate existing data and update your database table definitions to work with the updated code.

This document uses the term upgrade procedure to refer to a document that you develop and maintain. An upgrade procedure often takes the form of a checklist. Your upgrade procedure states exactly what you plan to do in each target environment to upgrade your Waveset application. See Task 4: Prepare Your Upgrade Procedure.

Upgrade Project

This document describes phases in an upgrade project. An upgrade project is your effort to upgrade your Waveset application to work with a new version of the Waveset product on which your application is based. An upgrade project includes your efforts to maintain and retest your configurations and customizations after executing the Waveset upgrade process in your Development environment. An upgrade project also includes your efforts to maintain and retest the upgrade procedure that you will follow in each target environment.

Phases of the Upgrade Project

The following figure shows the major phases of the upgrade project, summarizing the tasks that you must perform to complete each phase. The rest of this document guides you through each phase.

Figure 1–1 Upgrade Phases

Flowchart showing the four upgrade phases.