The process of importing differences from one IBM WebSphere Portal server to another is known as staging. This process is described in detail in the "Overview of staging your portal to production" section of the IBM WebSphere Portal Version 6.0 Information Center and can be as simple as creating an initial release or creating subsequent releases. Creating the initial release is more of a one-time effort and should be necessary only if you create a new server (for example, another production server on new hardware).

The simplest case occurs when you have the following four systems:

• A development system in which developers create new content or modify content.
• An integration system in which developers deploy fragments they developed.
• A staging system in which releases from the integration system are deployed for test.
• A production system in which all changes are finally deployed.

For the purposes of this Introduction, it is assumed that we do not have existing servers (staging, integration, production), which means those servers must be installed. The procedure to accomplish that is referred to as "empty portal" installation in the WebSphere Portal information center.

IMPORTANT: Copying the portal installations is not supported. It could potentially result in the same object ID being generated on different servers, and because the object IDs are key to the ReleaseBuilder tool, this could in turn result in objects being accidentally overwritten.

Creating an initial release

You constantly deploy content (artifacts) you created onto the integration system. Once a release on the integration system is considered final, you can export it with a release export, which can be imported in its entirety into the (empty) staging server. Most of the relevant processing, except the import of the release, occurs on the integration system.

After the release is tested and can go into production, you use the same process move the content from integration to production.

For this, you can directly import the export that you created from the integration system into the production server. The advantage of this is that you reproduce only what you did on the staging server, thus ruling out any handling or processing error that could occur if you created a new release export from the staging server and used that to move the changes to production.

After you create a production server, you must not perform any manual changes on it as this would result in changes becoming inconsistent. This is important when you think you create the same resource on both systems; you actually don't because new (and different) object IDs are generated on both systems.

Creating a subsequent release

Once the initial release is created, you start implementing new features, new portlets, and new pages, or you simply change things or fix issues in the current release.

Once you move all these artifacts to the integration system, you can create a new release. In this simple case, you can do this by:

• Producing a new release export on the integration system
• Running the ReleaseBuilder tool with the initial release export and the newly created release export, where the –inOld parameter represents the initial release export and the –inNew parameter is the newly created release export
• Importing the resulting XML file into the staging server for testing

After the test finishes successfully, you can transfer the release to production. Again, you can use the same ReleaseBuilder export that you used to deploy the release on the staging server.

NOTE: You should always create a release export and not a partial export of, for example, one page or one page with descendants. The ReleaseBuilder tool can handle only full release exports. A release export contains only artifacts that are considered public; it does not contain any private resources.

The ReleaseBuilder tool

To understand fully why a certain scenario is supported and another is not, it is important to know how ReleaseBuilder is designed and how it works internally.

ReleaseBuilder takes two release exports and compiles the difference between them. It is important to note that only release exports produce a valid result; an export such as a single resource export or page hierarchy export produces an invalid result, even if the tool may seem to process it successfully.

Internally, the tool maintains two lists, one for the old release (which is your current production release) and one for the new release. The process then starts to find a matching resource for each resource it finds in the new release list, using the object ID and assuming that equal (not necessarily identical) objects have identical object IDs. The objects to which this applies are:

• virtual-resource
• markup
• client
• skin
• theme
• wsrp-producer
• web-app
• content-node
• credential-segment
• url-mapping-context

After ReleaseBuilder finds a matching object, it analyzes the details and removes those parameters that didn't change, resulting in an output (difference) file that contains only the relevant changes.

Note that, if you are not sharing the same user repositories across your development, staging, integration, and production systems, you need to modify your XML files to reflect the changes that are required by that setup. For example, if User A is granted editor rights to a new page in LDAP1 and on the production system, the user must be User B on LDAP2, and you must create a style sheet and apply this mapping to the ReleaseBuilder output (difference) file to get it imported into the production system properly.

WebSphere Portal artifacts not covered by ReleaseBuilder

The list that follows contains all WebSphere Portal artifacts that must be manually installed on each system involved in the staging-to-production process. The installation instructions for each artifact can be found in the Information Center:

• Portlets (WAR files; for an example, see below)
• Themes and Skins (JSPs, images, CSS, etc.; or an example, see below)
• Portal screens (JSPs, images)
• Portlet services (Java libraries)
• J2EE artifacts (EAR files, Java libraries)
• Custom User Registry (Java libraries)
• Credential Vault Adaptors (Java libraries)
• Custom Credentials (Java libraries)
• JAAS log-in modules (Java libraries)

Items that cannot be staged with ReleaseBuilder

The following items cannot be staged with ReleaseBuilder:

• A document library to production (done by syndication)
• Application templates to production (done by backup/restore)
• Personalization to production (done by export/import or publish)
• Web content to production (done by syndication)

Refer to the WebSphere Portal Information Center for further details on how to perform staging.

Initial release setups

These setups describe the steps to bring a production server and staging server in sync initially.

Setup 1: Install everything from scratch

This is the easiest possible setup (see the Introduction section above), and it is also described in detail in the Information Center. Here's a summary of the steps:

1. Perform an empty WebSphere Portal installation for your production system.
2. Perform a full installation for your staging server.
3. Once your content is created and final on the staging server, export the release with XMLAccess.
4. Import the release export you created previously into your production system.

Setup 2: Existing production server

If you have an existing production server, the task is to create a new staging server. To create a new staging server, follow these steps:

1. Perform an empty WebSphere Portal installation for your staging server.
2. Perform a release export of your production system.
3. Import the release export into the staging server.

From now on, changes to release data must not be made on the production system.

Setup 3: Existing staging server

This is quite similar to Setup 2; only the roles are different:

• Perform an empty WebSphere Portal installation for your production server.
• Perform a release export of your staging system.
• Import the release export into the production server.

The same rule applies as above: No changes can be made to release data on the production server.

Setup 4: Existing production server and existing staging server

You must sync both servers, using one of these two ways:

1. If the resources have been previously moved to production manually and the object IDs have been moved along with them, it may be possible to again manually cross-check all resources from the staging server with the production server, and then sync those that should be the same but have different object IDs. Note, however, that this procedure is error prone and is not recommended.
2. Choose one of the servers as your baseline. Most likely, this is the production system, essentially putting you back to Setup 2 or 3. The existing staging server still can be used in the role of a development server.

Subsequent release scenarios

These scenarios let you keep your environments in sync. The key to remember here is the way in which resources are transferred; that is, in most cases the object IDs must be maintained, which is referred to as “object id preservation mode” in the WebSphere Portal Information Center.

It is important that you build the release difference at the earliest possible stage. This allows you to reproduce the deployment you already did for the staging or integration system on higher-level systems.

Scenario 1: Multiple development, one staging, one production environment

In this first scenario (see figure 1), you do the following:

1. Move fragments from the development systems to the staging server.
2. Export release on the staging server; this is considered release n+1.
3. Run ReleaseBuilder with release n and n+1.
4. Import ReleaseBuilder output into the production system.

Scenario 2: Multiple development, one integration, one staging, one production environment

In this scenario (see figure 2), you do the following:

1. Move fragments from the development systems to the staging server.
2. Export release on the integration server; this is considered release n+1.
3. Run ReleaseBuilder with release n and n+1.
4. Import ReleaseBuilder output into the staging system.
5. If errors occur that need to be fixed, start over at 1.
6. Once integration testing is successful, import ReleaseBuilder output from step 3 into the production system.

Scenario 3: Multiple development, multiple integration, one staging, one production environment

Here it is assumed that no two parties are working on the same resource at the same time (or at least their modifications must be coordinated). In this scenario, it can be challenging to keep the integration systems in sync when development organizations have dependencies on each other.

The multiple integration systems (see figure 3) indicate that different building blocks are developed and tested by different parties. After each party finalizes its portion, the partial release can be imported into the staging system (which therefore also acts as an integration system) and then into the production system.

This actually can be considered to be two different chains as shown in Scenario 1, one for development - integration - staging, and the other from integration - staging - production. For example:

• Chain 1
  1. Move fragments from the development systems to the integration server(s).
  2. Export release on integration server(s); this is considered release n+1 for this chain.
  3. Run ReleaseBuilder with release n and n+1 on each integration server.
  4. Import ReleaseBuilder outputs from integration server(s) into staging system.
• Chain 2
  1. Move fragments from the integration system(s) to the staging server.
  2. Export release on staging server; this is considered release n+1 for this chain.
  3. Run ReleaseBuilder with release n and n+1 on the staging server.
  4. Import ReleaseBuilder output into the production system.

IMPORTANT: Running two XMLAccess tasks (for example, two administrators importing different output files to the same portal environment) at the same time is not supported in WebSphere Portal versions earlier than V5.1. Version 5.1 was changed, however, so that now these tasks need to be coordinated.

Scenario 4: Multiple development, multiple integration, multiple staging, multiple production environments

The assumption here is that all the production systems need to be kept in sync. Scenario 1 can cover this scenario with a modified Step 4:

1. Move fragments from the development systems to the staging server.
2. Export release on the staging server; this is considered release n+1.
3. Run ReleaseBuilder with release n and n+1.
4. mport ReleaseBuilder output into all your production systems.

NOTE: This is not a recommended scenario as it does not provide reproducible steps to be imported into the production system(s). It basically makes the production system a staging or integration system (see figure 4).

Example scenario

For our example, we use a slightly modified Scenario 3 as shown in figure 5.

All environments are synchronized from production (see Initial Release Setup 2). It is assumed that all systems connect to the same user repository. Additionally, and to serve as a reference to the original configuration, an export file export_release_0.xml is created (see figure 6):

D:\IBM\WebSphere\PortalServer\bin>xmlaccess -user wpsadmin -password 
wpsadmin -url http://localhost:10038/wps/config/ -in 
D:/IBM/WebSphere/PortalServer/doc/xml-samples/ExportRelease.xml -out export_release_0.xml

Because all environments are synchronized, this reference configuration file can be copied to all systems. An example run of ReleaseBuilder proved that there were no differences between the environments.

Example 1: Adding a portlet

Example 1 was performed on the Test 1 system. After installing a portlet and setting the required user permissions, we placed the portlet on the desired page and configured it accordingly. After the modifications were satisfactory, we created a configuration file for release 1 (see figure 7):

D:\IBM\WebSphere\PortalServer\bin>xmlaccess -user wpsadmin -password 
wpsadmin -url http://localhost:10038/wps/config/ -in D:/IBM/WebSphere/PortalServer/
doc/xml-samples/ExportRelease.xml -out export_release_1_test1.xml

Note that a release represents the entire WebSphere Portal configuration, not just the modifications you’ve made.

Because this was the first release, we created an output (difference) file with ReleaseBuilder by comparing it with the reference configuration:

D:\IBM\WebSphere\PortalServer\bin>ReleaseBuilder.bat -inOld export_release_0.xml 
-inNew export_release_1_test1.xml -out diff_release_1_test1.xml

The output (difference) file diff_release_1_test1.xml was then copied to Staging, together with the portlet WAR file, which had to be copied to portal_server_root/installableApps.

When you install a new portlet, the import displays a warning that the Web application cannot be found in portal_server_root /deployed/archive. You can ignore this message because XMLAccess picks up the portlet from portal_server_root/installableApps as a fallback and installs it automatically.

In WebSphere Portal Version 6, you can also copy the portal_server_root/deployed/archive directory to prevent the warning message. Using XMLAccess, we then imported the output (difference) file to Integration (see figure 8):

D:\IBM\WebSphere\PortalServer\bin>xmlaccess.bat -in diff_release_1_integration1.xml 
-user wpsadmin -password wpsadmin -url http://localhost:10038/wps/config

After restarting the WebSphere Portal server, we verified that the release was deployed as intended.

Example 2: Rearranging pages

Example 2 was performed on the Test 2 system and consisted of only page arrangements and deletions. We then created the configuration file, and because it was the first release on the Test 2 system, it was also named release 1 (see figure 9):

D:\IBM\WebSphere\PortalServer\bin>xmlaccess -user wpsadmin -password wpsadmin 
-url http://localhost:10038/wps/config/ -in D:/IBM/WebSphere/PortalServer/doc/
xml-samples/ExportRelease.xml -out export_release_1_test2.xml

Again, we created an output (difference) file with ReleaseBuilder by comparing it with the original configuration (see figure 10):

D:\IBM\WebSphere\PortalServer\bin>ReleaseBuilder.bat -inOld export_release_0.xml 
-inNew export_release_1_test2.xml -out diff_release_1_test2.xml

The output (difference) file diff_release_1_test2.xml was then copied to Integration and imported with XMLAccess (see figure 11):

D:\IBM\WebSphere\PortalServer\bin>xmlaccess.bat -in diff_release_1_test2.xml -user 
wpsadmin -password wpsadmin -url http://localhost:10038/wps/config

After restarting the WebSphere Portal server, we verified that the release was deployed as intended.

By now, two releases had been imported to staging (see figure 12).

Because it was the first time that both releases were deployed on the same server, we verified they did not interfere with each other and then created a configuration file for a combined release 1 (see figure 13):

D:\IBM\WebSphere\PortalServer\bin>xmlaccess -user wpsadmin -password 
wpsadmin -url http://localhost:10038/wps/config/ -in D:/IBM/WebSphere/PortalServer/doc/
xml-samples/ExportRelease.xml -out export_release_1.xml

When the output (difference) file is created this time, it contains all the modifications from both previous imports (see figure 14):

D:\IBM\WebSphere\PortalServer\bin>ReleaseBuilder.bat -inOld export_release_0.xml 
-inNew export_release_1.xml -out diff_release_1.xml

Importing this file into the production environment completes the release chain (see figure 15). Remember that you must copy the portlet WAR file to portal_server_root/installableApps before running XMLAccess.

Example 3: Themes and skins

Staging themes and skins definitions with ReleaseBuilder is similar to installing new or updated portlets. (Note that the actual themes and skins, such as icons, jsps, and so on, are not staged by XMLAccess.)

After you add the theme in the WebSphere Portal administration and apply it to certain pages, you can create a WebSphere Portal configuration export and output (difference) file as shown previously.

As with WebSphere Portal WAR files, themes and skins must be copied manually to the next environment. To do this, copy the required subfolders from …/themes and …/skins from your source environment to <wp_profiles>/installedApps/…/wps.ear/wps.war on the target environment. Make sure to restart WebSphere Portal after the import so that it can pick up new or updated JSPs.

General release workflow

Figure 16 shows a general workflow when using ReleaseBuilder, reflecting the example scenario.

Special considerations

Now let’s discuss some of the special considerations you should be aware of.

Clustered environments

In the case of clustered environments, distribution of portlets, themes, and skins is handled by the WebSphere Application Server Deployment Manager (DM). You should select a single deployment node, in which all your deployments take place, because resources may not yet be available on all nodes at the same time. Thus you need to import only the output (difference) file on one node of the cell; however, be aware that you must activate the portlets by issuing WPSconfig.<bat|sh> activate-portlets from portal_server_root/config.

Reverting a release

If you need to revert an accidentally deployed release, you have two options:

1. If no other release has been subsequently imported to the production environment, you need to reverse the releases only when using ReleaseBuilder. For example, if the last working release was release <n> and release < n+1> should be removed, use ReleaseBuilder like this:

   ReleaseBuilder.bat -inOld release_ <n+1>.xml -inNew release_ <n>.xml-out remove_release_ <n+1>.xml

   
   This yields the output (difference) file remove_release_ <n+1>.xml that you can apply using XMLAccess to delete what was added accidentally.
2. If, however, one or more releases have already been imported to the production environment and now an older release should be removed, handle it as a new release. Make the required changes to the integration or staging environment to reflect what was added earlier, and then import the new release to the production environment as usual.

Another possible (but not recommended) approach to removing a release in case of an emergency change request is to create an output (difference) file out of the current release and the release previous to the accidentally deployed release. You then must reapply all output (difference) files except the one to be removed to establish the current status.

For example, to remove release <n+1>:

ReleaseBuilder.bat -inOld release_ <n+3>.xml -inNew release_ <n>.
xml -out remove_all_since_release_n.xml

Then apply output (difference) files < n+2> and < n+3>, again using XMLAccess. Reverting a release assumes that all release export files and all output (difference) files in the production environment have not been deleted or are archived.

Note that old binaries (for example, portlet WAR files) properties -- generally all resources not managed by XMLAccess -- must also be reverted.

Deleting and recreating resources with uniquenames

If an existing resource with, for example, a page with a certain uniquename is deleted and recreated with the same uniquename, the import step may result in a DuplicateKeyException. This occurs because upon deletion, the page is marked as deleted in the database but, in fact, it is still there; it's just not visible. To avoid the issue, first stage the delete, run the cleanup task, recreate the page, and then stage that creation again.

Staging based on partial exports

Using ReleaseBuilder on partial exports is usually not supported for the following reason:

When a partial export is done using

<content-node action=”export” uniquename=”myUniqueName” export-descendants=”true”/>

you probably have some items (web-apps, servlets, portlet-apps, and portlets) with an action=”locate”, which ReleaseBuilder does not recognize. It is implied that an input file for ReleaseBuilder contains only items with action=”update”.

When a portlet is changed on a page, the partial release export looks something like the code shown in listings 1 and 2.

<web-app action=”locate” uid=”webapp1”…>
    <portlet-app action=”locate uid=”webapp1.1”>
      <portlet action=”locate” name=”My Portlet” objectid=”_5_xx”>
    </portlet-app>
</web-app>
<content-node action=”update”…>
:
       <portletinstance action=”update” portletref=”_5_xx”/>
:
</content-node>

<web-app action=”locate” uid=”webapp2”…>
    <portlet-app action=”locate uid=”webapp2.1”>
      <portlet action=”locate” name=”A Portlet” objectid=”_5_yy”>
    </portlet-app>
</web-app>
<content-node action=”update”…>
:
	  <portletinstance action=”update” portletref=”_5_yy”/>
:
</content-node>

This may make ReleaseBuilder think that web-app webapp1 was removed, causing it to generate a delete operation for that web-app.

So, yes, you can use partial exports but, at the very least, you must carefully review the resulting output (difference) file before using it because content may be deleted accidentally.

Conclusion

When using ReleaseBuilder, you must plan around the desired scenarios that the environment should be handling, after which you must create the initial release and then start creating delta releases. It is essential to remember that ReleaseBuilder relies on object IDs and that, except for the upcoming changes, source and target systems must be synchronized.

Always keep in mind that you must not make manual updates through the Admin interfaces on the production system because doing so could yield unwanted results. Also, if your systems need to resync, you can use the procedure for creating an initial release.

Resources

• Participate in the discussion forum.
  
  
• Using ReleaseBuilder effectively IBM KnowledgeBase technote
  
  
• Consult the WebSphere Portal for Multiplatforms V5.1 information center
  
  
• WebSphere Portal V6 information center
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Creating an initial release
• Creating a subsequent release
• The ReleaseBuilder tool
• Initial release setups
• Subsequent release scenarios
• Example scenario
• General release workflow
• Special considerations
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers