This chapter provides an overview of the SunTM Identity Manager upgrade process and covers the following topics:
Access to advanced features and functionality
A more secure environment for your servers
Continued eligibility for full support and services
This section provides the following information:
To determine the upgrade path you must follow when upgrading to a newer version of Identity Manager, see Upgrade Paths and Support Policies in Sun Identity Manager 8.1 Release Notes. Generally, use the latest available patch or service pack for the version to which you are upgrading.
The Identity Manager standard upgrade process performs steps that are necessary to convert existing repository objects into the format that the newer version of Identity Manager expects. In particular, the updater programs that are shipped with each version of Identity Manager 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 Identity Manager version.
If you are upgrading Identity Manager, you must follow the required upgrade path noted in Upgrade Paths and Support Policies in Sun Identity Manager 8.1 Release Notes.
Even if you plan to perform a clean installation of Identity Manager and migrate your customizations to the new Identity Manager version, you must apply the standard upgrade process for each version of Identity Manager to properly update existing repository objects. The updater programs that are shipped with each version of Identity Manager 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.
For details about the End of Service Life (EOSL) policy for Identity Manager software see End of Service Life for Software Support in Sun Identity Manager 8.1 Release Notes.
For details about the deprecation policy for Identity Manager software see Identity Manager Deprecation Policy in Sun Identity Manager 8.1 Release Notes.
Deprecations are announced in Chapter 6, Deprecated APIs, in Sun Identity Manager 8.1 Release Notes.
Basically, how easy or how difficult it is to upgrade Identity Manager depends on how much you customize Identity Manager and what kind of customizations you make. Some customizations are highly backward-compatible. For example, older workflows, forms, and rules tend to work without modification on newer versions of Identity Manager. Other customizations are more volatile and require additional work to integrate them with new versions of Identity Manager. For example, you might have to recompile or rewrite integration code that invokes Java classes that are part of the Identity Manager product.
The most significant effect of customization, however, is that customization changes how you must approach upgrading Identity Manager. Note that the following discussion uses terminology and concepts described in Terminology and Concepts.
Upgrading Identity Manager can be relatively simple if you use the product as shipped—that is, if you configure Identity Manager 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 Identity Manager product was originally designed to be run in each environment. The product upgrade process automatically preserves your configuration settings as it updates the Identity Manager 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 Identity Manager, as the vast majority of customers do, then you cannot run the standard Identity Manager product upgrade in each environment. You must maintain and must retest your customizations after you upgrade the Identity Manager product, and you want to be certain that exactly what you tested goes into each environment. Because Identity Manager is often customized extensively, those who deploy Identity Manager have developed sophisticated practices for managing their customizations. For more information, see Source Control and CBE.
If you customize Identity Manager, the most common approach is to manage your customizations by maintaining a baseline and then to generate and promote an image of your Identity Manager application into each target environment. See Baseline and Image. You apply the standard Identity Manager product upgrade process only in your Development environment. You then apply to your application baseline most of the changes that the upgrade makes. See Identity Manager Product Compared With Identity Manager Application. However, your upgrade procedure also must include some pieces of the Identity Manager 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 Identity Manager repository table definitions.
Because the vast majority of customers do customize Identity Manager, and because many customize Identity Manager extensively, this document assumes that you have customizations and that you manage your customizations with this approach.
This section describes some specialized terminology that relates to upgrading Identity Manager.
Identity Manager product means the product as shipped, with standard samples, JSP files, JARs, and configuration objects.
Identity Manager application means the customer’s deployment of Identity Manager, which will be uniquely configured and might be customized, might include custom code and modified JARs, might be relabeled, and so forth.
A Development environment is where you configure, customize, and use source control to build an image of the Identity Manager application to be promoted to another environment. You also write an upgrade procedure in this environment that you follow in each target environment.
A QA environment is where you test your upgrade procedure against data, hardware, and software that closely simulate the Production environment and where you allow intended users to test the resulting Identity Manager application.
In this document, promotion refers to the process of generating a particular version of your Identity Manager application and moving that version from Development to Test, from Test to QA, and finally from QA to Production.
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 Identity Manager 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 Identity Manager 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 Identity Manager IDE plug-ins for NetBeansTM and Eclipse to generate a tailored version of the Identity Manager 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 Identity 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 Identity Manager 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 Identity Manager application for each target environment using a process that is predictable and repeatable.
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 Identity Manager application. Your CBE can generate from this baseline an image of the Identity Manager 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 Identity Manager application that is currently deployed in your Production environment. Your source control can also contain baselines for previous versions of your Identity Manager application and baselines for versions of your Identity Manager 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 Identity Manager application. Some customers include the Identity Manager product itself within that baseline. Other customers save the Identity Manager product image separately and use the baseline artifacts to overlay that product image with their own configurations and customizations.
A skip-level, or multi-hop, upgrade updates your Production environment to an Identity Manager 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 Identity Manager version.
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 Sun Professional Services for assistance with planning and executing your upgrade.
In this document, the term configuration means editing configuration objects in the Identity Manager product. You can edit configuration objects by using the Identity Manager 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 Identity Manager 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 Sun Professional Services defines these terms somewhat differently. For example, Sun Professional Services might consider customer-specific workflows to be configurations.
In this document, however, the key distinction is that the Identity Manager 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 Identity Manager product upgrade does not attempt to modify customer-written code or objects. These are customizations.
In this document, upgrade process refers to the upgrade mechanisms that are part of every version of the Identity Manager product. Each new version of Identity Manager 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 Identity Manager 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 Identity Manager application. See Task 4: Prepare Your Upgrade Procedure.
This document describes phases in an upgrade project. An upgrade project is your effort to upgrade your Identity Manager application to work with a new version of the Identity Manager product on which your application is based. An upgrade project includes your efforts to maintain and retest your configurations and customizations after executing the Identity Manager 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.
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.