CAU - Upgrade Process

This page guides you through the prerequisites and necessary steps to carry out a Centralized Agent Upgrade (CAU). It also provides information on the how to revert to a previous version and different configuration issues

This page includes the following:


There are many prerequisites that you have to fulfill before carrying out a Centralized Agent Upgrade (CAU). These prerequisites apply to different components of your system.

  • Set User Privileges

    Make sure the system administrator or User that carries out the Centralized Agent Upgrade (CAU) has the privilege Execute system upgrades set in the corresponding User object. For more information, see Granting Automation Engine Privileges.

  • Plugin Manager Installation

    The Plugin Manager is an extension to the AWI that can be used to install, upgrade, and remove Packs to enhance the functionality of your system.

    You have to install the Plugin Manager to see the Packs page in the Administration perspective and install the relevant packs. For more information, see Configuring the Plugin Manager.

  • Automation Engine Installation

    Make sure that the Automation Engine is installed and/or upgraded (either manually or using the ZDU) and that the relevant number of Java communication processes (JCPs) are up and running.

    Important! It is not possible to carry out a Centralized Agent Upgrade (CAU) parallel to a Zero Downtime Upgrade.

    More information:

  • Manual Agent and ServiceManager Installation

    You have to manually install an Agent and ServiceManager in the following cases:

    • There is no Agent and/or ServiceManager installed. This does not constitute and upgrade, but a very first installation.

      It is best practice to use separate binaries in different directories for different Agents, not shared ones. Otherwise, errors may occur.

    • An Agent is installed but it does not support CAU.

      The upgrade to version 12.0 or higher must be done manually, before CAU can be used to upgrade automatically to subsequent versions.

      When you try to update an Agent that does not support CAU, the target version displays the message Manual Upgrade Required.

    • You want to carry out a manual installation for any reasons.

      Do not use manual and automated CAU steps at the same time, as errors may occur.

    • Install a ServiceManager version 12.1 or higher to restart Agents after the CAU, thus ensuring that the Agents restart automatically after upgrading

      Using a different method to start Agents is possible, but you yourself have to make sure the Agents restart they will not restart automatically.

    More information:

  • Agent and ServiceManager CAU - Storage Objects

    Once you have an Agent that support the CAU installed:

    • Download the Storage objects packs containing the resources (binaries) of the desired target version.

    • Make sure you also download Packs for the version from which you are upgrading, just in case you need to revert to it.

    • Make sure the ServiceManager version is 12.1 or higher, thus ensuring that your ServiceManager is able to upgrade itself during the CAU.

      If you have a ServiceManager version 12.0 and use the CAU to upgrade Agents to version 12.1 or higher, some ServiceManager binaries remain in the bin directory of the Agent because this ServiceManager version is not able to upgrade itself by processing those files. However, these remaining binaries have no effect on the Agent.

    More information:

  • CAU Pack Installation - Packs Page

    In Client 0, install the Packs that you downloaded for the CAU from the Packs page of the Administration perspective. For more information, see Working with Packs and Plug-ins.

Upgrade Steps

Before starting the CAU process, make sure you fulfill all prerequisites.

The CAU comprises the following steps:

  1. If you have not done it yet, download the CAU Pack for the desired Agent target version from the marketplace (see and install it in Client 0. Make sure you also download Packs for the version from which you are upgrading, just in case you need to revert to it. For more information, see Installing Packs.

    Note: Removing a Pack using the Plugin Manager does not remove Agent target versions that are already available for CAU. The versions of all imported Packs are accumulated in the AE.

  2. In the Administration perspective, go to the Agents & Groups > Agents page and select the Agent or Agents that you want to upgrade. The filter page is open by default. You can use the Agent Name field to filter and then select the relevant Agents.

  3. Right-click the selected Agents and select Upgrade Agent. The Upgrade Agent dialog opens and displays the following information:

    • Number of Agents: Number of Agents selected for the respective platform.

    • Platform: Agent platforms selected for the CAU.

    • Target Version: Target versions available for the respective Agent type ordered in descending order, so the latest version is shown at the top. A dropdown arrow at the end of the row indicates that you can select the appropriate version. If the Pack installation was successful, the respective Agents are listed here.

  4. Select the Target Version from the dropdown list.

  5. Optionally, enter a Custom Upgrade Text. This text is part of the related CAU statistic record name.

  6. Select the appropriate option:

    • Agents with ServiceManager Link Only: Starts the upgrade only for Agents that have been started via Service Manager and guarantees that the Agents are restarted after the upgrade.

      If none of the selected Agents is linked to the ServiceManager, this option is hidden.

    • All Selected Agents: Starts the upgrade of all selected Agents if they are CAU compatible, regardless of a link to the ServiceManager.


      • Java Agents: CAU is available for Java Agents version 12.3 and higher. These Agents must be started by a Service Manager version 12.3 or higher, otherwise they cannot be upgradeable with the CAU.

      • OS Agents: If the Agent is not started by a Service Manager, the Agent ends. The binaries are upgraded, but the Agent cannot start automatically after the upgrade. Statistics records remain active until the Agent has been started again.

  7. Click Upgrade, if you are ready to perform the upgrade. A dialog displays the upgrade status for all selected Agents per platform.

    Upgrading triggers the following actions:

    • The Automation Engine triggers all Agents to perform the upgrade.

    • Each triggered Agents load all required upgrade resources kept in Storage objects in Client 0.

    • Each Agent replaces the existing binaries with the new ones.

    • After the binaries have been replaced successfully, each Agent shuts itself down providing a specific return code.

    • The corresponding ServiceManager restarts the Agent(s) based on this return code.

    • Each upgraded Agent starts up and reconnects to the AE with its new Agent target version.

    • The upgrade resources also contain binaries for the corresponding ServiceManager. After the ServiceManager restarts the Agent, it checks for those binaries and subsequently upgrades itself.

      Note: This automatic upgrade is only possible if a ServiceManager version 12.1 or higher is already installed.

  8. Refresh the Agents page to check if the upgrade was successful and if the Agents are listed with their new version.

  9. Optionally, look up the CAU related statistics and reports on the Upgrade History page.

    Upon starting the upgrade, the Upgrade History page displays a list of all Agents that are currently being upgraded or whose upgrades have recently finished. The status is also displayed.

    For example, Waiting for host means that the Agent is busy so the upgrade has been postponed to wait for the Agent to become available.

    If the page is empty, no upgrades have been started or run yet. For more information, see Upgrade History.

  10. Optionally, in the Upgrade History page, right-click the relevant upgrade record and select one the following options from the context menu:

    • Open Report: Opens the detailed report of the upgraded Agent

      There are two report types available:

      • CAU: AE reports triggering an upgrade for each Agent, as well as the end status, or a skipped upgrade process.

      • DEPLOY: An Agent reports all steps during an upgrade such as downloading / upgrading binary resources as well as its termination for restart.

    • Skip Upgrade: As long as an Agent waits for an upgrade to be started, for example, if the Agent is down or still busy processing workload tasks, you can use this action to skip the upgrade.


  • You can also carry out the CAU for Agents that are not connected to the Automation Engine. The AE remembers that the Agent was selected for an upgraded and triggers the process as soon as the Agent connects to the AE and is available again. This is also true for Agents that are already installed, but have never been started/connected to the AE and therefore have no current version information available. They are upgraded to the target version when they connect to AE for the very first time.

  • When you use Agents in a cluster, Agent 1 is terminated once the upgrade run is completed successfully. Then, the redundant Agent 2 starts up with the same Agent name but using the old version and is upgraded to the same version as Agent 1.

  • An Agent cannot be upgraded and run Agent jobs at the same time. If the Agent is busy, for example, executing a job or a file transfer, the upgrade process is put on hold until the Agent is idle again and ready to perform the upgrade.

  • While an Agent is performing an upgrade it is suspended and tasks to be executed change to the status Waiting for Host.

  • Some server-side Script functions on the server side request data from Agents. They are suspended during the Agent upgrade and resumed after the upgrade is completed.

Skipping the Upgrade

If an upgrade cannot be triggered immediately, the Agent remains in the status Waiting for Host. As long as the upgrade is pending, you can skip it. Once the Agent starts carrying out the upgrade (downloading and replacing files, restart, and so on) it cannot be skipped anymore.

You can do so two different ways:

  • Create a script using the MODIFY_SYSTEM Script function, see MODIFY_SYSTEM.

  • Directly in the AWI in the Agents & Groups > Upgrade History page in the Administration perspective, see Upgrade History.

    Find the Agents with the status Waiting for host. Select and right-click the Agent or Agents you do not want to upgrade and select Skip Upgrade from the context menu.

Reverting to a Previous Version

You can revert to a previous version if necessary. That is why it is recommended to also download Packs for the version from which you are upgrading, just in case you need to revert to it. Technically, this is a regular upgrade to another Agent version.

To revert to a previous version, select the lower target Agent version to which you want to downgrade from the dropdown list and click Upgrade. The related ServiceManager is downgraded at the same time.

No source / target version checks are performed thus preventing downgrading..

Cleanup Trigger

After the Agent upgrade run is done, the Automation Engine triggers a cleanup of all binaries that are not needed anymore. The Agent that has been upgraded re-connects to the AE. If its target version corresponds to the CAU record of the AE, the AE sends a cleanup message to the Agent.

The Agent then removes the binary file of the previous version from the system. Therefore, it is recommended to also download Packs for the version from which you are upgrading, just in case you need to revert to it.

Agent Connects to Wrong Target Version after the CAU

If the CAU run was successful but an Agent connects to the AE with the wrong target version the CAU is repeated. This means that an upgrade is forced to bring the Agent to the target version that was selected in the last CAU run.

In this case, the Agents & Groups > Upgrade History page in the Administration perspective displays REPAIR entries to indicate that the Agent was repaired by a forced upgrade to the desired target version.

Execute Objects on Upgrade

You can configure the necessary AE system modules to execute objects automatically once the Centralized Agent Upgrade (CAU) is completed.

Note: You can only configure the necessary variables and keys in Client 0.

You can also use Script functions and Script variables to read or print the content of the reports of CAU runs.

Execute on Upgrade - Configuration

First, you have to create the object or objects to be executed after the upgrade is done and then define the relevant parameters on the UC_HOSTCHAR_DEFAULT and UC_EX_HOSTCHAR system variables:

  1. In the Process Assembly perspective, go to the HOST_VARIABLES folder and open the UC_HOSTCHAR_DEFAULT variable.

  2. On the Variables page, define one of the following options, depending on what you want to do:

    • EXECUTE_ON_DEPLOYMENT_RUN if you want to execute an object after the entire deployment run is finished

    • EXECUTE_ON_DEPLOYMENT_AGENT if you want to execute an object after a particular Agent upgrade is finished

  3. Regardless or the option you selected, in the Value 1 column, enter the name of the object that should be executed after the upgrade.

  4. If you want to execute more than one object, use the object defined here to trigger consecutive object executions.

  5. Save your changes.

More information:

Using Scripts and Script Variables

There are different Script variables that you can use in Script functions to read different values. You can define them in the Process pages of an object definition. For more information, see Process Pages

Use with EXECUTE_ON_DEPLOYMENT_RUN, so that the variables listed return the values as described here:

  • &UC_EX_CAU_NAME# - Custom text of Agent upgrade
  • &UC_EX_CAU_RUNID#  - RunId of the CAU run (the parent of the Agent upgrade)
  • &UC_EX_CAU_STATUS#  -  Status of whole CAU run (it can be ENDED_OK or ENDED_NOT_OK)

Use with EXECUTE_ON_DEPLOYMENT_AGENT, which return the following values:

  • &UC_EX_HOST# - Agent / host name. (For compatibility reasons the variable name without "#" works as well here.)
  • &UC_EX_CAU_NAME#  - Custom text of an Agent upgrade run.
  • &UC_EX_DEPLOYMENT_RUNID# - RunId of a child / Agent upgrade
  • &UC_EX_DEPLOYMENT_STATUS# - Status (number) of child / Agent upgrade
  • &UC_EX_CAU_RUNID# - RunId of the CAU run (the parent of the Agent upgrade)


This script reads all variables from the read buffer and uses / prints them (single Agent deployment):


:P "CAU custom text=",&UC_EX_CAU_NAME#

:P "Agent=",&UC_EX_HOST#
:P "Agent deployment RunID=",&UC_EX_DEPLOYMENT_RUNID#
:P "Agent deployment status=",&UC_EX_DEPLOYMENT_STATUS#

Use PREP_PROCESS and this example script for a CAU report (an entire CAU run):

For a whole CAU run, use CAU as parameter report type in PREP_PROCESS_REPORT.


Use PREP_PROCESS and this example script for a "REP" report (single Agent deployment):

To process the detailed report of a single Agent upgrade, use "REP" as parameter report type in PREP_PROCESS_REPORT.


See also: