Upgrade Process

As of version 11.2 of the Automation Engine you can use the Zero Downtime Upgrade(ZDU) to upgrade your AE system with no downtime.
A wizard is provided to guide you through the whole process. There is no need for scripting or use of AE internals. You only need to follow the steps that are visible in the Automic Web Interface at each step.

Below you find a description of the steps necessary for upgrading your system without any downtime using the ZDU wizard.
This process equally applies to an upgrade of a major or minor version or a service pack.

Using ZDU from v11.2 to v12: Available directly in your client via a prompt. Note that you need to use the classical UserInterface for this purpose. Please download it directly from the Automic Download Center.

Using ZDU from v12 onwards: Available from client 0000 exclusively. Here you can use the new Automic web interface.

ZDU is possible when the alternative MS SQL Server schema is already in use. However, you cannot use it to switch to this schema.

Our consultants are experts in upgrading AE systems. Contact Automic, our experts will be pleased to assist you whenever it is necessary.

In order to print the whole contents of the collapsed pages below, use the button Expand all/Collapse all in the menu bar above.

Overview

Important Notes

It is possible to set the privilege for this kind of upgrade for any User object, but Automic recommends that upgrading will be coordinated and conducted by the system's administrators only.

You have to conduct the upgrade from start to finish in the same client.

Utilities cannot be rolled back once the database has been upgraded (step 2 in the upgrade wizard). You will have to use the target version utilities from then on.

System performance will be reduced considerably once the upgrade has been started and the compatibility mode is active.
As long as the compatibility mode is active, the performance will be about two thirds of ordinary runs.

Automation Engineutilities are external applications.
As administrator ensure that no utilities run during the ZDU process.

As two processing lines have been introduced, the following script elements might fail and throw a script error message (no. 20909), when you switch to parallel mode or initiate a ZDU rollback:

To prevent this error, take care not to have these elements in use, when switching modes and restart jobs as necessary.

You can log into a numbered client in the Automic Web Interface during the DB load. You cannot log into client 0, because initial data is inserted/updated until the commit is done at the end of DB Load.

Flowchart of upgrade and rollback steps:

Preliminary Steps

Requirements

ClosedA. System Setup

In a UNIX environment do not overwrite the existing installation, which is possible without warning on UNIX, even if the binaries are currently in use.

ClosedB. Set User Privilege

In order to upgrade your system you have to make sure that the respective user or users (usually the AE's administrators) have the necessary permissions.

The user (administrator) conducting the upgrade needs the privilege Execute system upgrades to be set in the corresponding User object.

For details on how to set privileges in User objects see Granting Privileges to Functions

ClosedC. Upgrade the Automic Web Interface

You have to install a new AWI instance every time you upgrade to a major or minor version of the Automation Engine.

For installing a service pack this step is only necessary if the SP contains changes or fixes for the AWI.

ClosedUpgrade the AWI

Upgrading ECC to AWI 12

Upgrading an existing ECC installation to the new release upgrades the AWI framework and all its plug‑ins at the same time. Use the same steps to install hot fix packages between releases.

Stop the Apache Tomcat Service

  1. Open your Windows Services manager.
  2. Stop the Apache Tomcat service.

Back Up Current Files

These steps are optional. You can make a safety copy of your entire ECC installation, or just the configuration files. Although you can use very little of the previous configurations in the new version, you might find it helpful to have a copy for later reference when you configure the upgrade.

  1. To backup your whole ECC installation, go to your Tomcat installation, open the webapps folder and make a backup copy of the entire Enterprise.Control.Center folder.
  2. To backup only the configuration files, go to the folder where you have the current ECC version installed and make a backup copy of the folder webapps/<ECC>/config.

Upgrade Apache Tomcat

Upgrade the Apache Tomcat web application server where you have ECC currently installed to the latest version that complies with the new release.

  1. Check the System Requirements in our online database, the Automic Compatibility Matrix to see which version of Tomcat you need.
  2. Go to the Tomcat home page and then download and install the required version. You will find the installation instructions and other relevant information on their home page.

    http://tomcat.apache.org/index.html

    For Windows: Download the package called "32-bit/64-bit Windows Service Installer." This will install Tomcat and a Windows service for it.

Restart the Apache Tomcat Service

  1. Open your Windows Services manager.
  2. Stop and restart the Apache Tomcat service.

Deploy the New AWI WAR File

Deploy the new version of the AWI on Tomcat.

  1. (Optional) Rename the WAR file to ECC.WAR, keeping the "war" extension. The name of the WAR file will also be the context path of your AWI installation.
  2. On the server where you have Tomcat installed, copy the WAR  file to the webapps folder of the Tomcat installation. If Tomcat is running, the WAR file will be deployed automatically, creating a folder with the same name.
  3. Warning: Do not delete the WAR file! If you do, Tomcat will also remove the corresponding subfolder, which also undeploys the AWI!

Configure the New AWI Version

  1. Configure your upgraded AWI using the file descriptions under Configuring AWI as a guide.

    If you made a backup before you started the upgrade, then you can retrieve the following files and settings from the backup files from the previous webapps/<ECC>/config folder:

    In the new webapps/<AWI>/configConfiguration from ECC that can be used for AWI 12
    uc4config.xml

    You can replace the new file with your backup. However, if you have more than one AE system connection defined, be aware that if the configuration.properties file has the setting the automationengine.index=0, then users will be able to log into only the first connection that is defined in the file. If you want to keep these settings in both files, then make sure to move the preferred connection to the first place in the uc4config.xml.

    configuration.properties

    Do not replace the file in your new installation with your backup. Instead, define the file as described in this guide. However, you can refer to your backup files for the following two parameters, which may have optionally been defined in ECC:

    • defaultHomeDashboard (This would be the "dashboard" attribute in the navigation.xml file.)
    • customHomeDashboardsFolder (This would be from the previous configuration.properties file.)

    logback.xml

    If you had changed the default setting for the severity level of ECC event messages (DEBUG) for the root element, then you might want to make the same change for AWI 12.

    The "theme" folder

    If you had customized the color or banner logo in ECC, then copy the contents of your backed up webapps/<ECC>/config/theme folder to the folder of the same name in AWI 12.

    For more information see the topics "Customizing the AWI User Interface" and "colors.properties."

Start the New AWI

  1. Enter the following URL in the address bar of your internet browser:

    http://host name:8080/webapp name/ where:

    host name = the name of the computer on which the Apache Tomcat web server runs

    8080= the default port for Apache Tomcat

    webapp name = the name of the WAR file (without the file extension).

  2. Login to the AWI with your user name and password.

The Upgrading Steps

In the course of the steps below you can leave the process any time and return to it later at the step you left off by calling the System Upgrade page. The Automation Engine system will store the information of the step where you left off and open the page at that step automatically as soon as you return.

Once you have finished the whole upgrade process by confirming Next in the final seventh step of the wizard, a rollback will no longer be possible!

ClosedProcedure

  1. Log on to the Automic Web Interface in system client 0000.
    If you granted the privilege Execute system upgrades to a user for the first time in the preliminary step, that user will have to log off and restart and then log on to the AWI of the AE with those credentials.
  2. Open the Administration perspective, in the Navigation pane on the left find the Automation Engine Management page, click to expand it and below that find the System Upgrade sub-page:


  3. In this page choosing the button Run System Upgrade Wizard will start the ZDU.
    This will start the compatibility mode and enables upgrading the database with the target version's schema and initial data, shown by the following page:


  4. As also contained in the page's instructions, leave the page open and use the external DB Load Utility to upgrade the database.
  5. When this step has been processed, the AE system has loaded the target version database schema and initial data.
    The following page also will notify you of that fact:


    When you have finished upgrading the database with DB Load, in this wizard confirm the step by clicking Next. This will start a check in the Automation Engine, if the initial data for base and target version are present and the target version data has been loaded correctly.

     Closed DB Load Utility in this step checks the following:

    Running System Check:

    • Should ZERO_DOWNTIME_UPGRADE be set to N and the system be running, DB Load will end the loading process with a corresponding message.

    Version Check:

    • DB Load checks, if the correct version for the ZDU function is installed and used. If the version is not correct, a message to that effect will be returned.

    New DB Schema and Initial Data - Check and Load:

    • If the key ZERO_DOWNTIME_UPGRADE is set to N and the system is not running, DB Load will load the new DB schema and initial data. For future reference records are written into the appropriate database table.
    • If the key UC_SYSTEM_SETTINGS / ZERO_DOWNTIME_UPGRADE = Y and the system is running, DB Load will also load the new DB schema and initial data, if a record of a previous load attempt is found in the database. Otherwise DB Load aborts and returns the corresponding message.
    • In addition DB Load checks, if CPs and WPs of the target version are already active. In case active CPs/WPs of the target version are found, DB Load will end and return the corresponding message.


  6. Install and start communication processes and work processes from the target version parallel to the already running ones.

    Use the second installation (see preliminary steps) for installing the new processes from the target version. Make sure not to use recurring names for processes you install. Best practice is the setup of two separate installations.

    The new processes at this point are not yet in use.

    When you have finished installing the CPs and WPs, confirm clicking Next.

  7. If you haven't upgraded your AWI as part of the preliminary steps, do so now. The wizard in this step provides a short overview of the upgrading procedure for the AWI:

     

  8. In this step the base and target version CPs will change places: The running tasks will finish on base version CPs, new tasks will be started on target version CPs, until all base version CPs are idle.
    • Therefore it is necessary for you to disconnect users still connected to base version AWIs, or to inform them to log off.
    • Disconnect agents connected with base version CPs manually so that they reconnect automatically with the new CP generation. Make sure that agents can be disconnected without interruption of running executions.

    The wizard in this step offers an interactive page with two panes, where you can disconnect users and agents yourself:

    Reconnect agents pane - Rollback Button (Pane in Rollback state)

    Disconnect Users - Restart Button (Pane in Rollback state)

    The screenshots above show the location of the buttons, after a Rollback has been started.
    The buttons for disconnecting users and restarting agents change the side of the pane and show up over the table for new or old version, depending on the function you are using:
    Upgrade or Rollback.

    To disconnect a user or several users or all users at once:

    1. Click Users, find the user or users you want to disconnect.
    2. You can multi-select user entries by using the default keys:
      • Use Strg+click to select only certain users.
      • Use Shift+click to select all users between first and last selection.
    3. Disconnect all or only certain users:
      • If only a certain number of users shall be disconnect, use the Disconnect User, which disconnects all users you selected in the previous step.
      • To disconnect all users in the list at once, use Disconnect all Users. In this case no selection is necessary.
    4. Users you disconnected will disappear from the lists.

    To reconnect an agent or several agents or all agents at once:

    1. Click Agents, find the agent or agents you want to reconnect.
    2. You can multi-select agent entries by using the default keys:
      • Use Strg+click to select only certain users.
      • Use Shift+click to select all agents between first and last selection.
    3. Reconnect all or only certain agents:
      • If only a certain number of users shall be disconnect, use the Reconnect Agent, which reconnects all agents you selected in the previous step.
      • To disconnect all agents in the list at once, use Reconnect all Agents. In this case no selection is necessary.
    4. Agents you reconnected will appear either in the new version or the old version list, depending on the version you reconnected them from.

    The system is now running with the target version initial data and processes, while the base version processes will be subsequently phased out.
    This parallel mode should last as long as needed for proper testing.
    Use it for testing the system to determine, if the upgrade has been successful and all processes or tasks run smoothly.
    This is necessary in order for you to decide, if you want to finish the upgrade by using the final step. For details refer to the ZDU FAQ page.
    At this point the option Rollback will be available as well, which is not visible in the previous steps.

    If you need to roll back the upgrade, because testing was not successful, find details in the Rollback section below.

  9. If testing was successful, you can proceed in the wizard, using Next again. This next step takes care of upgrading Plugins and additional components.
    The wizard will inform you of the fact and provide details about the steps you have to take outside the wizard:

  10. At this point the memory entries in the database have to be checked and the ones referring to the old version have to be deleted, using the wizard:

  11. Now the wizard will present you with an option to first upgrade your system's agents.

    As of v12, two ways are possible here:

    After you finished upgrading agents, or directly, if you choose not to upgrade agents, use the option Next to finalize the upgrade.

    This will end the parallel as well as the compatibility mode.
    Here Next will only be possible, if no base version processes are active anymore.
    When you click Next, the following error message may be displayed:

    "ZERO_DOWNTIME_UPGRADE - 'FINALIZE' not possible. Workprocesses to shut down are not idle yet./Please try again later."

    In that case scheduled tasks may be active.
    Wait for the scheduled tasks to change their execution period (usually the next day), then return to the wizard and try executing the option again.

    Once you have finished the whole upgrade by confirming Next in this final step, a rollback will no longer be possible!

Rollback Option

This rollback function is meant for a possible troubleshooting. Certain tasks or processes may not be running quite as expected while testing the new installation. Choosing this option allows you to check on those tasks or processes.
The option will be visible in the wizard in step 4, as soon as the new version CPs and WPs have been started and are running.
Using this option will roll back the processing to the base version.

Once you have finished the whole upgrade by clicking the option Next in the final seventh step of the wizard, a rollback will no longer be possible!

ClosedConduct a Rollback

In order to be able to conduct a rollback you have to be at step 4 of the System Upgrade wizard, Upgrade Mode, as shown below.

As always, if you left off at a certain step, you can return to it calling the System Upgrade sub-page.

  1. Open the Administration perspective, in the Navigation pane on the left find the Automation Engine Management page, click to expand it and below that find the System Upgrade sub-page.
  2. In step 4 of the wizard select the option Rollback at the bottom of the page:

    This image shows step 4 of the wizard, in Upgrade Mode.

  3. The system now switches back using CPs/WPs from the base version you started from while the new processes are subsequently phased out.
    A page like this one will be displayed:

    This image displays step 4 in the wizard in Rollback Mode.

    Exception:
    The primary role (PWP) remains with a new WP until Restart has been executed.

  4. Use this stage for analyzing the reason which caused you to execute the Rollback.

    Two possible main scenarios are identified by Automic, which may cause a rollback:

    1. Something in AE object definitions or environment settings has to be adapted in order to work correctly with the target version. In this case get the necessary work done and then continue with the upgrade procedure of the wizard, step 1
      • To return to step 1 of the wizard: In Rollback Mode of step 4 of the wizard (see above) click Next.
    2. The new processes / initial data from the target version have not been working as expected. In this case contact Automic Support for assistance in finding out what has to be done.
      • If new components have to be installed to solve the issue, execute the option Restart in step 4 of the wizard (Rollback Mode).
        Effect:
        This will end the parallel mode:
        It will switch back the PWP role to base version and shut down running components of the target version so that they can be replaced.
      • Install components you may have received from Automic Support and continue with the upgrade procedure step 1, clicking Next to start the check for initial data, as described above.
  5. Important!
    When you click Restart, the following error message may be displayed:

    "ZERO_DOWNTIME_UPGRADE - 'Restart' not possible. Workprocesses to shut down are not idle yet./Please try Restart again later."

    In that case scheduled tasks may be active.
    Wait for the scheduled tasks to change their execution period (usually the next day), then return to the wizard and try executing the option Restart again.

See also: