CAU - Upgrade Procedure

As a system administrator working in client 0000 you use CAU to upgrade the agents.

This page includes the following:


The steps to follow are:

  1. Download the PM package for the CAU for the desired agent version you want to upgrade to.

  2. Import the PM package into client 0000.

  3. Filter and multi-select all agents to be upgraded in the Agents page of the Administration perspective. Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.

  4. Select the context menu item Upgrade for these agents and specify the desired agent target version.

  5. Look up the CAU related statistics / reports for more information, in the Upgrade History page.

  6. Refresh the Agents page to check:
    Successfully upgraded agents will be listed with their new version.

Downloading and Importing Plugin Manager Packages for CAU

The necessary agent resources for the CAU are kept in storage objects (AE object type = STORE). Therefore you have to make these objects available in the AE before performing CAU actions.

You can get these objects via Plugin Manager packages, which are available for each released agent version on


To Import PM Packages for CAU

  1. Download the Plugin Manager package for CAU for the desired target agent version from
  2. Logon to AWI in client 0000.
  3. Navigate to the Packs view in the Administration perspective.
  4. Import the Plugin Manager package downloaded previously.
  5. Click on Replace, if needed.
  6. After the Plugin Manager package was successfully imported, the new agent target version is available for the CAU.


Selecting Agents to be Upgraded and Specify Version

  1. In the Agents page of the Administration perspective, select one or more agents you want to upgrade to the new version and select Agent Upgrade from the context menu.

    Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.

    If the import of Plugin Manager packages was successful, you find a list of the new versions of agents you upgrade to. The list displays the following information:

    • Number of Agents: Number of all agents available for the platform in the second column.

    • Platform: The respective platform of the agents you selected in the Agents page.

    • Target Version: The target versions available for that 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 there.

  2. Optionally, enter a custom upgrade text in the field below the list. This text will be part of the related CAU statistic record name.

  3. Select the appropriate option, Agents with ServiceManager Link Only or All Selected Agents.

    Agents with ServiceManager Link Only starts the upgrade only for agents that have been started via Service Manager. This option guarantees that the agents are restarted after the upgrade.

    All Selected Agents starts the upgrade of all agents you selected in the previous dialog, if they are CAU compatible, regardless of a link to the ServiceManager.


    • Java agents: CAU is available for Java agents as of v12.3. They must be started by a Service Manager of v12.3 or later in order to be upgradeable via CAU.
    • OS agents: If the agent is not started by a Service Manager, the agent will end and the binaries will be upgraded, but it cannot start automatically after the process. Upgrade statistics records will remain active until the agent has been started again.

    If none of the selected agents is linked to the ServiceManager, the option Agents with ServiceManager Link Only is hidden.

  4. Click Upgrade, if you are ready to perform the upgrade. A dialog displays the upgrade status for all selected agents per platforms.

    For detailed reports, see Upgrade History.

Checking Reports and Upgrade History

Upon starting the upgrade, the Upgrade History page displays detailed information and reports. For more information, see Upgrade History.

The Upgrade History page of the Agents & Groups section in the Administration perspective displays a list of all agents that are currently being upgraded or whose upgrades have recently finished. If the page is empty, no upgrades have been started or run yet.

The status is also displayed to provide more information. 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.

The Upgrade History displays the following information:

The following actions are available in the context menu for agent listings.

Execute Objects on Upgrade

You can configure the necessary AE system modules to execute objects on the CAU's completion automatically.

Note: You have to be logged in into system client 0000 to be able to configure the necessary variables and keys.

Execute on Upgrade - Configuration

In order to configure the automatic execution of objects after the CAU has been completed, the system variables UC_HOSTCHAR_DEFAULT and UC_EX_HOSTCHAR have to be edited or created. For more information, see UC_HOSTCHAR_DEFAULT - Host Characteristics and UC_EX_HOSTCHAR - Assigning Agents to Host Characteristics.

You first have to create the object or objects to be executed after the upgrade has been finished.
Afterward you set the values in the respective UC_HOSTCHAR_DEFAULT key, following these steps:

  1. In the Process Assembly, find the HOST_VARIABLES folder. The system variable UC_HOSTCHAR_DEFAULT is located inside it. Double click the variable to open and edit it.
  2. In the Variable page you will see a list of keys you can edit.
    • If you want to execute an object of your choice after the entire deployment run has been finished, use EXECUTE_ON_DEPLOYMENT_RUN.
    • If you want to execute an object of your choice after a particular agent upgrade has been finished, use EXECUTE_ON_DEPLOYMENT_AGENT.
  3. This step applies to both keys:
    On the right hand side in the table use the column Value 1 to enter the name of the object that should be executed after the upgrade.
    In case you want to execute more than one object, use the object defined here in the necessary Automation Engine setup to trigger consecutive object executions.
  4. Save the system variable.

In order to read or print the report contents of CAU runs, you can use script functions and available script variables.

Using Scripts and Script Variables

There are script variables available that you can use in scripts in the Process page of an object you referenced to read the respective values, namely:

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

Use with EXECUTE_ON_DEPLOYMENT_AGENT, which will return the following values:


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):

For processing the detailed report of a single agent upgrade use "REP" as parameter report type in PREP_PROCESS_REPORT.




:          PRINT &LINE#


Cleanup Trigger

After the agent upgrade has run, the Automation Engine triggers a cleanup of all binaries that are now not needed anymore. This means, the agent that has been upgraded re-connects to the AE. If its target version agrees with 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.

Note: Because of this cleanup function which will be triggered on the agent's re-connect, it is necessary that you provide the binaries as CAU packages of previous versions in case you want to revert the CAU. Take care to import them should they not be present in the system yet.

Skipping the Upgrade

It is possible to skip the upgrade of agents that you initially registered for an upgrade, if they are in the status Waiting for host.

You can skip the upgrade in two different ways:

Reverting to a Previous Version

You may want to revert the agent's upgrade in case your preferences or system occurrences make it seem appropriate.
This function is technically an upgrade to another agent version.
Therefore you just have to follow the steps described above for the CAU itself.

To Revert to a Previous Version

  1. Import the corresponding packages into the system to make them available for reverting to a previous version.
  2. Select the agent version you want to revert to and finish the upgrade procedure as described.
  3. To check the details of the previous version, open the Upgrade History page. Follow the steps described above in Checking Reports and Upgrade History.

System Behavior during a Centralized Agent Upgrade (CAU)

See also: