Patching and upgrading Red Hat Process Automation Manager 7.7
Red Hat Customer Content Services
brms-docs@redhat.com
Abstract
Preface
As a Red Hat Process Automation Manager user, you can apply updates to Red Hat Process Automation Manager as they become available in the Red Hat Customer Portal to keep your Red Hat Process Automation Manager distribution current with the latest enhancements and fixes. Red Hat provides update tools and product notifications for new product releases so you can more readily apply helpful updates to Red Hat Process Automation Manager and KIE Server.
Prerequisites
- You have a Red Hat Customer Portal account.
Red Hat Process Automation Manager 7.7 is installed. For installation options, see Planning a Red Hat Process Automation Manager installation.
NoteIf you are using Red Hat Process Automation Manager 7.6 and you want to upgrade to Red Hat Process Automation Manager 7.7, see Patching and upgrading Red Hat Process Automation Manager 7.6 .
Chapter 1. Red Hat Process Automation Manager versioning
Red Hat Process Automation Manager versions are designated with a numerical Major.Minor.Patch
format, such as 7.6.1
. In this example, the major release is 7.x.x
, the minor release is 7.6.x
, and the patch release is 7.6.1
. Major releases often require data migration, while minor release upgrades and patch updates are typically managed with update tools provided with the Red Hat Process Automation Manager release artifacts.
The following are the general types of releases for Red Hat Process Automation Manager:
- Major release migrations
Major releases of Red Hat Process Automation Manager include substantial enhancements, security updates, bug fixes, and possibly redesigned features and functions. Data migration is typically required when an application is moved from one major release to another major release, such as from Red Hat JBoss BPM Suite 6.4.x to Red Hat Process Automation Manager 7.0. Automated migration tools are often provided with new major versions of Red Hat Process Automation Manager to facilitate migration, but some manual effort is likely required for certain data and configurations. The supported migration paths are specified in product announcements and documentation.
For example migration instructions, see Migrating from Red Hat JBoss BPM Suite 6.4 to Red Hat Process Automation Manager 7.0.
- Minor release upgrades
Minor releases of Red Hat Process Automation Manager include enhancements, security updates, and bug fixes. Data migration may be required when an application is moved from one minor release to another minor release, such as from Red Hat Process Automation Manager 7.6.x to 7.7. Automated update tools are often provided with both patch updates and new minor versions of Red Hat Process Automation Manager to facilitate updating certain components of Red Hat Process Automation Manager, such as Business Central, KIE Server, and the headless Process Automation Manager controller. Other Red Hat Process Automation Manager artifacts, such as the decision engine and standalone Business Central, are released as new artifacts with each minor release and you must re-install them to apply the update.
Before you upgrade to a new minor release, apply the latest patch update to your current version of Red Hat Process Automation Manager to ensure that the minor release upgrade is successful.
- Patch updates
Patch updates of Red Hat Process Automation Manager include the latest security updates and bug fixes. Scheduled patch updates contain all previously released patch updates for that minor version of the product, so you do not need to apply each patch update incrementally in order to apply the latest update. For example, you can update Red Hat Process Automation Manager 7.6.0 or 7.6.1 to Red Hat Process Automation Manager 7.6.2. However, for optimal Red Hat Process Automation Manager performance, apply product updates as they become available. Occasionally, unscheduled patch updates may be released outside the normal update cycle of the existing product. These may include security or other updates provided by Red Hat Global Support Services (GSS) to fix specific issues, and may not be cumulative updates.
Automated update tools are often provided with both patch updates and new minor versions of Red Hat Process Automation Manager to facilitate updating certain components of Red Hat Process Automation Manager, such as Business Central, KIE Server, and the headless Process Automation Manager controller. Other Red Hat Process Automation Manager artifacts, such as the decision engine and standalone Business Central, are released as new artifacts with each minor release and you must re-install them to apply the update.
To ensure optimal transition between releases and to keep your Red Hat Process Automation Manager distribution current with the latest enhancements and fixes, apply new product releases and updates to Red Hat Process Automation Manager as they become available in the Red Hat Customer Portal. Consider also enabling product notifications in the Red Hat Customer Portal.
For information about enabling product notifications, see Chapter 2, Enabling Red Hat Process Automation Manager notifications in the Red Hat Customer Portal.
Chapter 2. Enabling Red Hat Process Automation Manager notifications in the Red Hat Customer Portal
You can enable notifications in the Red Hat Customer Portal to receive Red Hat Process Automation Manager updates and announcements. These notifications inform you of updated or added documentation, product releases, and patch updates related to Red Hat Process Automation Manager. With notifications enabled, you can more readily apply product updates to Red Hat Process Automation Manager as they become available in the Red Hat Customer Portal to keep your Red Hat Process Automation Manager distribution current with the latest enhancements and fixes.
Prerequisites
- You have a Red Hat Customer Portal account and are logged in.
Procedure
- In the top-right corner of the Red Hat Customer Portal window, click your profile name and click Notifications.
- Select the Notifications tab and click Manage Notifications.
- Next to Follow, select Products from the drop-down menu, and then select Red Hat Process Automation Manager from the next drop-down menu that appears.
- Click Save Notification to finish.
You can add notifications for any other products as needed in the same way.
Chapter 3. Migrating Red Hat JBoss Enterprise Application Platform 7.2 to 7.3
Red Hat Process Automation Manager 7.8 only supports Red Hat JBoss Enterprise Application Platform 7.3. If you want to upgrade Red Hat Process Automation Manager 7.7 instances to 7.8 you must first migrate Red Hat JBoss EAP from 7.2 to 7.3.
Prerequisites
- Your Red Hat Process Automation Manager and KIE Server instances are not running. Do not apply updates while you are running an instance of Red Hat Process Automation Manager or KIE Server.
- Red Hat JBoss Enterprise Application Platform 7.2 is installed.
Procedure
Download Red Hat JBoss EAP 7.3 to each Red Hat JBoss EAP instance:
Navigate to the Software Downloads page in the Red Hat Customer Portal (login required) and select the product and version from the drop-down options:
- Product: Red Hat JBoss EAP
- Version: 7.3
-
Click Download next to Red Hat JBoss Enterprise Application Platform 7.3. (
jboss-eap-7.3.0.zip
).
Extract the
jboss-eap-7.3.0.zip
file to the same base directory of Red Hat JBoss EAP 7.2.NoteThe base directory of the Red Hat JBoss EAP installation is referred to as
EAP_HOME
.Run the
jboss-server-migration.sh
script to migrate configurations and deployments from Red Hat JBoss EAP 7.2 to Red Hat JBoss EAP 7.3:$ ./bin/jboss-server-migration.sh -s ../jboss-eap-7.2/
Answer
yes
to all questions except the following question. Answerno
to this question:This tool is not able to assert if the non-persistent deployments found are compatible with the target server, skip scanner's deployments migration?
Copy the
.niogit
directory from Red Hat JBoss EAP 7.2 directory to the new.niogit
directory. For example:$ cp -r ../jboss-eap-7.2/.niogit .niogit
Change the
MaxMetaspaceSize
memory setting value to1024m
in thebin/standalone.conf
file. For example:-XX:MaxMetaspaceSize=1024m
Optional: To migrate unmanaged KIE Server instance configurations to Red Hat JBoss EAP, perform the following tasks:
ImportantProceed with this section only if there are unmanaged KIE Server instances configured in the migrated Red Hat JBoss EAP server instance that need to be migrated.
Locate the KIE Server state XML files for the unmanaged instances. The XML files should be located in the directory from where the Red Hat JBoss EAP server is launched. These are usually named after the KIE Server instance identifier, for example
example-kieserver.xml
. You can usegrep
to search forkie-server-state
, for example:$ grep -FR "<kie-server-state>"
- Copy the server’s state files to the directory where you will launch the new Red Hat JBoss EAP 7.3 instance.
Chapter 4. Applying patch updates and minor release upgrades to Red Hat Process Automation Manager
Automated update tools are often provided with both patch updates and new minor versions of Red Hat Process Automation Manager to facilitate updating certain components of Red Hat Process Automation Manager, such as Business Central, KIE Server, and the headless Process Automation Manager controller. Other Red Hat Process Automation Manager artifacts, such as the decision engine and standalone Business Central, are released as new artifacts with each minor release and you must re-install them to apply the update.
You can use the same automated update tool to apply both patch updates and minor release upgrades to Red Hat Process Automation Manager 7.7. Patch updates of Red Hat Process Automation Manager, such as an update from version 7.7 to 7.7.1, include the latest security updates and bug fixes. Minor release upgrades of Red Hat Process Automation Manager, such as an upgrade from version 7.6.x to 7.7, include enhancements, security updates, and bug fixes.
Red Hat Process Automation Manager 7.8 only supports Red Hat JBoss EAP 7.3. You must migrate Red Hat JBoss EAP 7.2 to 7.3 before upgrading Red Hat Process Automation Manager from 7.7 to 7.8. For more information about migrating Red Hat JBoss EAP 7.2 to 7.3, see Migrating Red Hat JBoss Enterprise Application Platform 7.2 to 7.3.
Only updates for Red Hat Process Automation Manager are included in Red Hat Process Automation Manager update tools. Updates to Red Hat JBoss EAP must be applied using Red Hat JBoss EAP patch distributions. For more information about Red Hat JBoss EAP patching, see the Red Hat JBoss EAP patching and upgrading guide.
Prerequisites
- Your Red Hat Process Automation Manager and KIE Server instances are not running. Do not apply updates while you are running an instance of Red Hat Process Automation Manager or KIE Server.
- Red Hat JBoss EAP is migrated from 7.2 to 7.3. For more information about migrating Red Hat JBoss EAP 7.2 to 7.3, see Migrating Red Hat JBoss Enterprise Application Platform 7.2 to 7.3.
Procedure
Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options.
If you are upgrading to a new minor release of Red Hat Process Automation Manager, such as an upgrade from version 7.6.x to 7.7, first apply the latest patch update to your current version of Red Hat Process Automation Manager and then follow this procedure again to upgrade to the new minor release.
Click Patches, download the Red Hat Process Automation Manager [VERSION] Update Tool, and extract the downloaded
rhpam-$VERSION-update.zip
file to a temporary directory.This update tool automates the update of certain components of Red Hat Process Automation Manager, such as Business Central, KIE Server, and the headless Process Automation Manager controller. Use this update tool first to apply updates and then install any other updates or new release artifacts that are relevant to your Red Hat Process Automation Manager distribution.
If you want to preserve any files from being updated by the update tool, navigate to the extracted
rhpam-$VERSION-update
folder, open theblacklist.txt
file, and add the relative paths to the files that you do not want to be updated.When a file is listed in the
blacklist.txt
file, the update script does not replace the file with the new version but instead leaves the file in place and in the same location adds the new version with a.new
suffix. If you blacklist files that are no longer being distributed, the update tool creates an empty marker file with a.removed
suffix. You can then choose to retain, merge, or delete these new files manually.Example files to be excluded in
blacklist.txt
file:WEB-INF/web.xml // Custom file styles/base.css // Obsolete custom file kept for record
The contents of the blacklisted file directories after the update:
$ ls WEB-INF web.xml web.xml.new
$ ls styles base.css base.css.removed
In your command terminal, navigate to the temporary directory where you extracted the
rhpam-$VERSION-update.zip
file and run theapply-updates
script in the following format:ImportantMake sure that your Red Hat Process Automation Manager and KIE Server instances are not running before you apply updates. Do not apply updates while you are running an instance of Red Hat Process Automation Manager or KIE Server.
On Linux or Unix-based systems:
$ ./apply-updates.sh $DISTRO_PATH $DISTRO_TYPE
On Windows:
$ .\apply-updates.bat $DISTRO_PATH $DISTRO_TYPE
The
$DISTRO_PATH
portion is the path to the relevant distribution directory and the$DISTRO_TYPE
portion is the type of distribution that you are updating with this update.The following distribution types are supported in Red Hat Process Automation Manager update tool:
-
rhpam-business-central-eap7-deployable
: Updates Business Central (business-central.war
) -
rhpam-kie-server-ee8
: Updates KIE Server (kie-server.war
) -
rhpam-controller-ee7
: Updates the headless Process Automation Manager controller (controller.war
)
Example update to Business Central and KIE Server for a full Red Hat Process Automation Manager distribution on Red Hat JBoss EAP:
./apply-updates.sh ~EAP_HOME/standalone/deployments/business-central.war rhpam-business-central-eap7-deployable ./apply-updates.sh ~EAP_HOME/standalone/deployments/kie-server.war rhpam-kie-server-ee8
Example update to headless Process Automation Manager controller, if used:
./apply-updates.sh ~EAP_HOME/standalone/deployments/controller.war rhpam-controller-ee7
The update script creates a
backup
folder in the extractedrhpam-$VERSION-update
folder with a copy of the specified distribution, and then proceeds with the update.-
After the update tool completes, return to the Software Downloads page of the Red Hat Customer Portal where you downloaded the update tool and install any other updates or new release artifacts that are relevant to your Red Hat Process Automation Manager distribution.
For files that already exist in your Red Hat Process Automation Manager distribution, such as
.jar
files for the decision engine or other add-ons, replace the existing version of the file with the new version from the Red Hat Customer Portal.If you use the standalone Red Hat Process Automation Manager 7.7.0 Maven Repository artifact (
rhpam-7.7.0-maven-repository.zip
), such as in air-gap environments, download Red Hat Process Automation Manager 7.7.x Maven Repository and extract the downloadedrhpam-7.7.x-maven-repository.zip
file to your existing~/maven-repository
directory to update the relevant contents.Example Maven repository update:
$ unzip -o rhpam-7.7.1-maven-repository.zip 'rhba-7.7.1.GA-maven-repository/maven-repository/*' -d /tmp/rhbaMavenRepoUpdate $ mv /tmp/rhbaMavenRepoUpdate/rhba-7.7.1.GA-maven-repository/maven-repository/ $REPO_PATH/
NoteYou can remove the
/tmp/rhbaMavenRepoUpdate
folder after you complete the update.- After you finish applying all relevant updates, start Red Hat Process Automation Manager and KIE Server and log in to Business Central.
Verify that all project data is present and accurate in Business Central, and in the top-right corner of the Business Central window, click your profile name and click About to verify the updated product version number.
If you encounter errors or notice any missing data in Business Central, you can restore the contents in the
backup
folder within therhpam-$VERSION-update
folder to revert the update tool changes. You can also re-install the relevant release artifacts from your previous version of Red Hat Process Automation Manager in the Red Hat Customer Portal. After restoring your previous distribution, you can try again to run the update.
Chapter 5. Enabling executable rule models when upgrading to Red Hat Process Automation Manager 7.7
Beginning in Red Hat Process Automation Manager 7.7, rule assets are built from executable rule models by default with the standard kie-maven-plugin
plugin. The executable model is a more efficient alternative to the standard asset packaging in previous versions of Red Hat Process Automation Manager.
When you install Red Hat Process Automation Manager 7.7, this default executable model behavior is configured for all new projects that you create going forward. However, if you are upgrading to Red Hat Process Automation Manager 7.7 from a previous version of the product and you have not already enabled executable rule models, you must add the required dependency to your existing Red Hat Process Automation Manager projects so that your rule assets are built from executable models in Red Hat Process Automation Manager 7.7. If you do not use the kie-maven-plugin
plugin or if the required drools-model-compiler
dependency is missing from your project, then rule assets are built without executable models.
For more information about executable rule models, see Packaging and deploying a Red Hat Process Automation Manager project.
Procedure
In the pom.xml
file of your Maven project or on the relevant class path of your Java project, add the following dependency to enable rule assets to be built from the default executable model:
<dependency> <groupId>org.drools</groupId> <artifactId>drools-model-compiler</artifactId> <version>${rhpam.version}</version> </dependency>
This dependency compiles the executable model into Red Hat Process Automation Manager internal data structures so that it can be executed by the decision engine.
The <version>
is the Maven artifact version for Red Hat Process Automation Manager currently used in your project (for example, 7.33.0.Final-redhat-00002).
Instead of specifying a Red Hat Process Automation Manager <version>
for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your project pom.xml
file. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.
Example BOM dependency:
<dependency> <groupId>com.redhat.ba</groupId> <artifactId>ba-platform-bom</artifactId> <version>7.7.0.redhat-00002</version> <scope>import</scope> <type>pom</type> </dependency>
For more information about the Red Hat Business Automation BOM, see What is the mapping between RHPAM product and maven library version?.
Chapter 6. Additional resources
Appendix A. Versioning information
Documentation last updated on Wednesday, Aug 05, 2020.