Using ReleaseBuilder effectively

Technote (troubleshooting)

Problem

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

Resolving the problem

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.

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 is not supported. Doing so may not cause an error immediately but the procedure has not been tested, and may lead to unexpected results such as data becoming out of sync, potential system downtime or data loss.

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.

Note: These instructions do not apply if you are using syndication to update content between Portal version 8 servers. See Updates using ReleaseBuilder.

1. Install the target (production) Portal environment and then empty it of content using the ConfigEngine task empty-portal.

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

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.

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 "difference" or diff files created using ReleaseBuilder or not), can generate different unique identifiers (object IDs). This can lead to unexpected results.

Customizations By definition, a staging server does not capture user-defined customizations (for example, pages that are owned by a and visible only to individual users). 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 that may have been created during Testing or QA.

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 the standard XMLAccess export and import process.

Custom scripts Use cases in which custom scripting code examines the XML input files must not rely on existence of elements that may be common to both files. If data element is required (for example a web application URL) retrieve it from the input files, do not depend on a particular output in the difference XML.