Chapter 8. Patching and Upgrading Red Hat JBoss BPM Suite

8.1. About Patches and Upgrades

Red Hat JBoss BPM Suite patches can be either an asynchronous update, or a planned update:

  • Asynchronous updates: Individual patches which are released outside the normal update cycle of the existing product. These may include security patches, as well as other individual patches provided by Red Hat Global Support Services (GSS) to fix specific issues.
  • Planned updates: The cumulative patches of an existing product, which includes all previously developed updates for that version of the product.

To download Red Hat JBoss BPM Suite patches:

  1. Navigate to the Software Downloads section of the Customer Portal.
  2. Click Security Advisories.

The following files are included as part of a Red Hat JBoss BRMS and Red Hat JBoss BPM Suite patch release.

  • Red Hat JBoss BRMS customers — jboss-brms-VERSION-patch.zip.
  • Red Hat JBoss BPM Suite customers — jboss-bpmsuite-VERSION-patch.zip.
  • Maven repository updates (same for both Red Hat JBoss BRMS and Red Hat JBoss BPM Suite customers) — jboss-brms-bpmsuite-VERSION-incremental-maven-repository.zip.

8.2. Applying Patches in Red Hat JBoss BPM Suite 6.4

Important

6.4 Update 6 introduces a small change into the database schema. You must apply the bpms-6.4-to-7.0.sql script to your database before you run Red Hat JBoss BPM Suite or Red Hat JBoss BRMS 6.4.6. This script is located in the upgrade-scripts/<database-type> directory, available from the Red Hat JBOSS BPM Suite 6.4 Update 6 and the Red Hat JBOSS BRMS 6.4 Update 6 zip files which you can download from the Red Hat Customer Portal.

In Red Hat JBoss BPM Suite, the client patching tool is distributed as a ZIP file that includes .sh and .bat scripts, allowing for easy and automatic application of updates to an existing Red Hat JBoss BPM Suite 6.1 (or better) installation.

Important

The patching tool is for use with Red Hat JBoss BPM Suite 6.1 or better, and should not be used for earlier versions. For more information, see the Maintenance Release Changes in BRMS and BPM Suite 6.1+ article at Red Hat Knowledgebase.

The script requires two mandatory parameters: <path-to-distribution-root> and <type-of-distribution>. For example, the following command applies the updates to the specified Red Hat JBoss EAP bundle:

Note

Patch updates should not be applied while you are running an instance of Red Hat JBoss BPM Suite. Make sure that the server is shut down before running the following command.

$ ./apply-updates.sh ~/EAP_HOME/jboss-eap-6.4 eap6.x

The following distribution types are supported:

  • eap6.x
  • eap6.x-bc
  • eap6.x-dashbuilder
  • eap6.x-kie-server
  • generic
  • generic-bc
  • generic-dashbuilder
  • generic-kie-server
  • was8
  • was8-bc
  • was8-dashbuilder
  • was8-kie-server
  • wls12c
  • wls12c-bc
  • wls12c-dashbuilder
  • wls12c-kie-server
  • bpmsuite-engine
  • planner-engine
  • supplementary-tools

The quickstarts and migration tool are also included in the patch and are available for download as a ZIP file.

Note

Only updates for Red Hat JBoss BRMS or Red Hat JBoss BPM Suite are included in the patch distribution. Patches to EAP itself must be applied using the EAP patching mechanism. See the Red Hat JBoss EAP Installation Guide.

Backup Feature

Before applying any updates, the client script takes a backup of the specified distribution. It copies the distribution file or directory into the backup/CURRENT_TIMESTAMP subdirectory. The top-level backup directory is created at the same filesystem level as the apply-updates script.

Blacklist Feature

The client patching tool provides a blacklist feature that allows you to tell the script the files that must not be updated. This is a feature that helps you preserve your configuration files from being overwritten automatically by the update process. You can specify non-configuration files as well if required.

To specify the blacklisted files, open the file blacklist.txt present within the patch distribution. Enter the relative path to the files that must not be updated. Each file must be specified on a line by itself.

# Lines with a '#' are comment lines, like this one.
# Blank lines are ignored.

# We have made changes to the web.xml that must be preserved:
WEB-INF/web.xml

# This file has custom modifications:
styles/base.css

Files specified in the blacklist.txt file that have updated content in the patch, are not touched by the update tool. Instead, the tool copies the new, updated file in the same location and appends the new suffix to it. For example, after running the patch tool, both these files will exist in the styles folder, continuing with the blacklist.txt file in the example above.

$ ls styles
base.css base.css.new

Now, compare the contents of the two files and merge the changes.

If there are files that are no longer being distributed but you want to preserve them, put them into the blacklist.txt file as well. The patch update tool will not delete these files, and instead create an empty marker file with the suffix removed. You can then choose to either keep or delete these files manually.

Continuing with the previous example, if the base.css file was removed and you had this file listed in the blacklist.txt file, then after the patch tool has run, the contents of the styles directory would be similar to:

$ ls styles
base.css base.css.removed

8.3. Patching Other Platforms and Applications

Use the following commands for updating other supported platforms and common applications in Red Hat JBoss BPM Suite.

Important

On a Microsoft Windows system, run ./apply-updates.bat instead of ./apply-updates.sh.

Patch EAP 6.x Business Central WAR

$ ./apply-updates.sh PATH/jboss-eap-6.4/standalone/deployments/business-central.war eap6.x-bc

Patch Generic KIE Server WAR

$ ./apply-updates.sh PATH_TO_TOMCAT_HOME/webapps/kie-server.war generic-kie-server

Patch Whole WebLogic 12c Bundle

$ ./apply-updates.sh PATH_TO_UNZIPPED_wlsc12c_BUNDLE wls12c

Patch Planner Engine Bundle

$ ./apply-updates.sh PATH_TO_UNZIPPED_PLANNER_BUNDLE planner-engine

Patch IBM WebSphere Application Server Bundle

$ ./apply-updates.sh PATH_TO_UNZIPPED_WAS_BUNDLE was8

Note

When patching the IBM WebSphere Application Server, do not extract the target WAR files.

See Section 8.2, “Applying Patches in Red Hat JBoss BPM Suite 6.4” and Section 8.4, “Upgrading to Latest Minor Release” for more information.

8.4. Upgrading to Latest Minor Release

Apart from supporting upgrade to the latest micro release, Red Hat JBoss BPM Suite also supports upgrading between minor releases. For example, upgrading from:

  • Red Hat JBoss BPM Suite 6.2.2 to Red Hat JBoss BPM Suite 6.3.0
  • Red Hat JBoss BPM Suite 6.1.5 to Red Hat JBoss BPM Suite 6.3.0

The Red Hat JBoss BPM Suite upgrade tool is distributed as ZIP files with naming convention that states the upgrade path. For example, jboss-bpmsuite-6.2.2-to-6.3.0-patch.zip is used to upgrade from 6.2.x to the 6.3.0 version. These ZIP files can be downloaded from the Red Hat Customer Portal:

  • Use jboss-bpmsuite-6.2.2-to-6.3.0-patch.zip to upgrade from Red Hat JBoss BPM Suite 6.2.2 to Red Hat JBoss BPM Suite 6.3.0.
  • Use jboss-bpmsuite-6.1.5-to-6.3.0-patch.zip to upgrade from Red Hat JBoss BPM Suite 6.1.5 to Red Hat JBoss BPM Suite 6.3.0.

Each ZIP file contains the following scripts:

  • apply-updates.bat
  • apply-updates.sh

To upgrade to the next minor release using these upgrade scripts, you must specify arguments indicating the path of distribution and the type of distribution you want to upgrade in your command:

$ ./apply-updates.sh DISTRIBUTION_PATH DISTRIBUTION_NAME

For example:

$ ./apply-updates.sh ~/EAP_HOME/jboss-eap-6.4 eap6.x

The supported distribution types are:

  • eap6.x
  • eap6.x-bc
  • eap6.x-dashbuilder
  • eap6.x-kie-server
  • generic
  • generic-bc
  • generic-dashbuilder
  • generic-kie-server
  • was8
  • was8-bc
  • was8-dashbuilder
  • was8-kie-server
  • wls12c
  • wls12c-bc
  • wls12c-dashbuilder
  • wls12c-kie-server
  • bpmsuite-engine
  • planner-engine
  • supplementary-tools

The upgrade tool allows you to upgrade the entire distribution, or only a part of the distribution as per your requirement. For example, for the eap6.x distribution, you can choose to patch the entire eap6.x or choose to patch any of the war files (eap6.x-bc, eap6.x-dashbuilder, eap6.x-kie-server) that the patch contains.

Note that the upgrade tool does not upgrade the configuration files if you have your custom updates in them. The upgrade tool checks if the configuration files have any changes. If there are no changes made to the configuration files, the tool replaces the configuration files with the latest version. However, if the tool finds custom changes made to any of the configuration files, it adds those files to blacklist, and does not replace them with the latest version. So you do not need to manually compare the configuration files and place them in the blacklist to ensure that your custom configurations are intact.

Note

It is recommended that you add your custom changes to the .new files instead of trying to update the current configuration files with changes from the new Red Hat JBoss BPM Suite version. For example, if you have custom changes such as data source name/location in the persistence.xml file, the recommended approach is to add your custom changes to the .new files created by the upgrade tool. Once you have updated the .new files with all the required changes, rename them to their original names (without the .new suffix). This ensures that the applications pick the updated configuration files containing your custom changes.