Upgrading

Overview

When upgrading your HCL Workload Automation environment, it is a good practice to start with the upgrade of the Dynamic Workload Console first. If you upgrade the console to the new product version level, you can then use it to verify that your environment is working after upgrading the remaining components.

The upgrade procedure varies depending on the product version you currently have installed:

if you have installed version 9.5.0.x or 10.x.x and want to upgrade to the General Availability version with a direct upgrade procedure, see Performing a direct upgrade from v 9.5.0.x or v 10.x.x to v 10.2.3.
if you have installed version 9.5.0.x or 10.x.x and want to upgrade to the General Availability version with a parallel upgrade procedure, see Parallel upgrade from version 9.5.0.x or 10.x.x to version 10.2.3. This procedure might be useful when you have you have some of your components installed on operating systems which are no longer supported in version 10.2.3 and therefore cannot perform a direct upgrade.
if you have installed version 9.4.0.x and want to upgrade to version 10.2.3. In this case, only a parallel upgrade is supported. For more information, see Parallel upgrade from version 9.4.0.x to version 10.2.3.

In a direct upgrade procedure from version 9.5.0.x or 10.x.x, you upgrade the Dynamic Workload Console and its database, then upgrade the dynamic domain manager and its backups and the database, then master domain manager and its backups and the database, and finally the domain managers and their backups, and the agents.

In a parallel upgrade procedure from version 9.5.0.x or 10.x.x, you upgrade WebSphere Application Server Liberty, upgrade the Dynamic Workload Console and its database, then upgrade the database for the server components and install a new dynamic domain manager and master domain manager configured as a backup, then switch them to become the master. You then upgrade agents and domain managers.

In a parallel upgrade procedure from version 9.4.0.x, you install the Dynamic Workload Console at v 10.2.3. You then upgrade the database tables for the server components and their backups and install a new backup dynamic domain manager, switch the manager to the new backup, install a new backup and switch back the manager capabilities, so that the newly installed backup dynamic domain manager becomes the current dynamic domain manager.

You then proceed to running the serverinst script to install a version 10.2.3 master domain manager configured as a backup. The installation process is able to detect the presence of an existing master domain manager and automatically configures the second one as the backup master domain manager. The new backup master domain manager is configured to point to the existing database instance. You then perform a switch with the previous version master domain manager, so that the newly installed backup master domain manager becomes the current active master domain manager.

You then install a second master domain manager to act as the new backup master domain manager. Each Dynamic Workload Console, backup dynamic domain manager, dynamic domain manager, master domain manager and backup master domain manager installation requires its own installation of Open Liberty. The upgrade process concludes with upgrading agents. Agents can be upgraded with minimal disruption to scheduling activities.

Using the new features introduced with the latest release creates new records in the database which are not compatible with previous versions and therefore you cannot roll back your environment to a previous version.

If you upgrade HCL Workload Automation to version 10.2.x, and the HCL Workload Automation database was created with DB2, change the DB2 configuration parameter EXTENDED_ROW_SZ to ENABLE, or create a new buffer pool and table space with a page size of 16 kilobytes and migrate the tables to the new table space. For more information, see Error in upgrading the HCL Workload Automation database when using a DB2 database.

Before upgrading, ensure that you have stopped workload processing on the master domain manager.

If you have previously customized the tws_env script, merge your changes into the new version of the script. Ensure you do not overwrite the parameters related to OpenSSL libraries during the merge.

Choosing how to upgrade your network

After upgrading the Dynamic Workload Console, there are different approaches to upgrading the remaining components in your HCL Workload Automation environment. Because HCL Workload Automation supports compatibility with earlier versions, after upgrading the console, you can decide to proceed with upgrading in one of the following ways, depending on the type of your network:

Top-down

Upgrade components in the following order:

backup domain managers and domain managers
dynamic domain managers
backup master domain manager
master domain manager
agents

This order ensures that events involving folders are correctly managed by the master domain manager and sent to agents at a supported version level.

When you have a backup master domain manager at the V9.5 Fix Pack 2, or later, but the master domain manager is still at a previous product version level, problems can occur when monitoring objects that support the definition in a folder such as, prompts, workstations, and resources, as well as objects that contain the workstation in their object identifier, for example, job streams. More specifically these objects are not displayed in the results of the monitoring query on the plan if you use filters in your query. To solve this problem, upgrade the master domain manager to the V9.5 Fix Pack 2 level, or later, and then run planman resynch.

Many of the new functions that are introduced in the current version become available for each agent as it is upgraded. The disadvantage is that the same functions are not available to all agents at the same time.

Bottom-up

Upgrade components in the following order:

agents
backup domain managers and domain managers
dynamic domain managers
backup master domain manager
master domain manager

The new functions that are introduced in the current version are not available until the whole network is upgraded.

In the typical upgrade procedures documented in this manual, the top-down order is used.

Note: Due to new support of the UPN Windows user, if you have Windows domain users that are defined in the logon fields as domain\username, after performing an upgrade to this version, update the Security file before starting the HCL Workload Automation instance. Insert the escape character '\' before the '\' character in the domain\username value. For example, if you use the MYDOMAIN\user1 value in the logon field, after the upgrade, in the Security file you must update the line in following way:

..............
logon=MYDOMAIN\\user1
...............

For details, see Configuring the Security File.

Migrating custom events

When you perform an upgrade, custom events are not migrated. Therefore you must add custom events by following the manual procedure described below:

On the master domain manager, create a new XML file <file_name> where you can save custom events:
```
$ evtdef dumpdef <file_name>
```
Run the switchmgr command to switch from the master domain manager to the backup master domain manager.
Copy the XML file created in step 1 on the backup master domain manager.
Load the custom event definition on the backup master domain manager by running the following command:
```
$ evtdef loaddef <file_name>
```
Where <file_name> is the name of the XML file that you copied from the master domain manager and saved on the backup master domain manager.
Stop WebSphere Application Server Liberty on the Dynamic Workload Console.
Start WebSphere Application Server Liberty on the Dynamic Workload Console by running the following command:
```
<DWC_HOME>/appservertools/startAppServer.sh -directclean
```