Using ReleaseBuilder effectively

This document describes the ReleaseBuilder tool in IBM WebSphere Portal and the scenarios in which it is used.

Introduction
ReleaseBuilder is an IBM WebSphere® Portal utility that was introduced in version 5.1 to simplify the task of updating one Portal environment with changes made in another, that is, to "stage" a Portal release between environments.

ReleaseBuilder eliminates the need to export and import entire configurations which can take considerable time, or partial configurations generated using hand-written XML. ReleaseBuilder can also account for Portal artifacts that have been deleted from the source Portal, something that the XML Configuration Interface (XMLAccess) cannot do.

The use of ReleaseBuilder is the recommended "best practice" to synchronize changes between Portal environments.

A general overview and definition of terms for ReleaseBuilder can be found in the WebSphere Portal Information Center topic, "Deploying your Portal overview".

Before using ReleaseBuilder, make sure that you are running Portal 5.1.0.1 or later. A number of ReleaseBuilder code fixes have not been and will not be released for Portal 5.1.0 due to the complexity of the code changes and the large number of prerequisites that would have to be installed on 5.1.0.

Using ReleaseBuilder
The most common ReleaseBuilder problem is the attempt to create a release using XMLAccess exports from two different WebSphere Portal hosts. ReleaseBuilder is designed to generate a proper release only when run against two XML files exported from the same Portal environment.

Running ReleaseBuilder against exports from two different Portal environments may not cause an error immediately, but doing so is not supported, has not been tested, and will lead to unexpected results.

The typical ReleaseBuilder process flow to deploy a release from a staging server to a production server is usually similar to the steps listed below. The steps apply to virtual portals as well as the "base" Portal server configuration.

1. Install the target (production) Portal environment as an empty Portal (with no portlets).

2. Prepare the production system to receive future releases by importing an XMLAccess export taken from the staging Portal generated using ExportRelease.xml. Use XMLAccess to create an export of staging using ExportRelease.xml as the input file and import the resulting output file to the production Portal.

Note that ExportRelease.xml must be used to generate the export files for use by ReleaseBuilder. No other xml file should be used, including Export.xml.

After Step 2, the staging and production portals should have the same content (minus any customizations made on the staging portal. Refer to "A note on customizations" below for a discussion of ReleaseBuilder and user-defined customizations).

3. Save the export generated in Step 2 above to use as a baseline file for ReleaseBuilder.

4. Make changes to the staging portal over time.

5. When it is necessary to generate a release, take a new export from the staging portal using ExportRelease.xml.

The XML files to be compared by ReleaseBuilder must be created using the XML file, ExportRelease.xml. ExportRelease.xml can be found on a Portal host in the directory, <WP_Root>/doc/xml-samples.

6. Run ReleaseBuilder against the XML files taken in Steps 2 and 5 to generate a release.

A sample command line is:

UNIX:
./releasebuilder.sh -inOld stagingserverREV1_config.xml -inNew stagingserverREV2_config.xml
-out outputfile.xml

Windows:
releasebuilder.bat -inOld stagingserverREV1_config.xml -inNew stagingserverREV2_config.xml
-out outputfile.xml

The file specified after the parameter, " -inOld", is the baseline export from the staging Portal. The file specified after the parameter, " -inNew", is the export from the staging Portal that contains the changes made to the staging Portal since the baseline export was done.

The file, " outputfile.xml", will contain all the changes made to the staging Portal between the time the baseline export was taken (Step 3 above) and the export in Step 5 was created.

7. Import outputfile.xml to the target Portal using XMLAccess to update the target production Portal.

xmlaccess -user -pwd -url http://portal.domain.com/wps/config -in outputfile.xml -out importNewRelease.xml

After Step 7 is completed, the production Portal should contain the changes made to the staging server.

Once a Portal begins to receive releases generated by ReleaseBuilder, it is important that the target Portal (the system to which the releases are imported) no longer be modified manually, or modified by importing an XMLAccess export taken from a third Portal environment.

Updating the target manually will cause the target to become out of sync with the Portal from which releases are generated. Similarly, importing XML configuration files from another Portal, one that is neither the staging or production system (whether these imports are "differences" files created using ReleaseBuilder or not), can cause new object IDs to be created and/or existing artifacts to be updated. This can lead to unexpected results.

A note on customizations
By definition, a staging server does not contain user-defined customizations that should be transferred to a production server. ReleaseBuilder is designed to create a release by generating an XML file that contains the changes made to the pages and other Portal artifacts over time, not to capture user-defined additions to a source Portal.

Technically, a user-defined customization in this context is any resource that has the private="true" flag in its access-control tag of an XMLAccess export, for example:

<access-control externalized="false" owner="username" <private="true"/>

This also applies to pages that are created by users.

This means that exports taken using ExportRelease.xml specifically exclude customizations made on the staging or source Portal and releases generated will not include these data. If you must transfer customizations made on the source server to another environment the only option is to use standard XMLAccess export and import.

For additional information, refer to the WebSphere Portal Information Center pages below.

A detailed description of staging scenarios can be found in the developerWorks article, " IBM WebSphere Portal Version 6.0 staging scenarios using ReleaseBuilder." The article applies to all versions of WebSphere Portal in which ReleaseBuilder is available.