Overview

For Universal Controller 7.4.x, upgrading refers to the increase of a currently installed 5.2.0 version of the Controller to a 7.4.x version (for example, upgrading Controller 5.2.0.5 to Controller 7.4.0.0).

You can upgrade to Universal Controller 7.4.x only from Universal Controller 5.2.0; you cannot upgrade to 7.4.x from any version earlier than 5.2.0 (for example, 5.1.1).

Note

To increase a currently installed 6.1.x or later release of the Controller to a 7.4.x release, you do not have to perform an upgrade; you only have to apply maintenance to the 6.1.x or later version.

Upgrading vs. Applying Maintenance

For Universal Controller 7.4.x, applying maintenance refers to the increase from a currently installed 6.1.x or later release of the Controller to a 7.4.x release of the Controller (for example, increase Controller 6.1.3.1 to Controller 7.4.0.0).

The procedures for upgrading differ from the procedures for applying maintenance (see Applying Maintenance to Universal Controller).

Database Permissions

In order to install or perform upgrades of Universal Controller, the database user configured for the Controller will require DDL (Data Definition Language) permission in the database during the install or upgrade.

Once the install or upgrade has been completed successfully, the configured database user requires only DML (Data Manipulation Language) permissions for running the Controller.

Supported Upgrade Paths

You can use these instructions for the supported upgrade paths shown in the following table. For any other upgrade path, consult your Stonebranch representative.

Upgrade Controller to...	1.6.0	1.7.0	5.1.0	5.2.0	6.1.x	6.2.x	6.3.x	6.4.x	6.5.x	6.6.x	6.7.x	6.8.x	6.9.x	7.0.x	7.1.x	7.4.x
From 1.5.0
From 1.6.0
From 1.7.0
From 5.1.0
From 5.2.0

Upgrade Procedures

These instructions comprise the following procedures:

1	Make Sure No Records Are Being Processed
2	Stop OMS
3	Back Up Your Database
4	Run an Export on the Active Controller
5	Stop Tomcat and Remove All Controllers
6	Prepare Your Database
7	Download the New Controller
8	Install the Controller
9	Verify the Active Controller Installation
10	Run an Import on the Active Controller
11	Check Your Data
12	LDAP Synchronization
13	Verify the Passive Controller Installations
14	Start OMS
15	Verify the Upgrade

Note

These instructions assume that you are running a High Availability Universal Controller system: a system configured with Active and Passive Controllers (cluster nodes). If you are running a single Controller, disregard the steps for Passive Controllers.

Make Sure No Records Are Being Processed

Warning

If the Controller is processing task instances when you launch an export, the results are unpredictable.

Step 1	Log in with ops.admin or a user with administrator privileges.
Step 2	Disable all active triggers (after making a record of each) to make sure no tasks are being processed.
Step 3	Check the Activity Monitor to verify that there are no active task instances. If there are, wait until they complete before you start the export process. If necessary, you can force finish tasks.

Stop OMS

Stop Universal Message Service (OMS).

The start/stop procedure for Universal Agent components (such as OMS) may differ depending on your platform. For instructions, see Starting and Stopping Agent Components.

Back Up Your Database

Important

Before upgrading your Controllers, back up your database. The database backup is a fail-safe measure; you will be using the Controller 5.2.0 export and Controller 7.4.x import, as described below, to migrate your data.

Run an Export on the Active Controller

In this procedure, you are performing a bulk export of data that you will import to your upgraded system in a later procedure using the bulk import.

Export Scripts

Export scripts in the Controller copy and save records to one or more XML files. The exported files then can be imported into the upgraded system.

The following scripts are available for exporting different sets of records:

uc_bulk_export.js	Exports all current record definitions, without versions.
uc_bulk_export_with_versions.js	Exports all current record definitions and older (non-current) versions of record definitions.
uc_bulk_export_history.js	Exports task instance history, which includes all task instances in an "end" status (cancelled, failed, skipped, finished, success).
uc_bulk_export_activity.js	Exports all unfinished activity; that is, task instances in the Activity display. (Not recommended for migration.)

Running the Export

Perform the following steps to run the bulk export:

Step 1	From the navigation pane, select Automation Center Administration > Configuration > Maintenance Scripts. The image below shows export script options for Controller 5.2.0.
Step 2	Select an export script and click Run.
Step 3	The Controller prompts for a confirmation. Click Yes. As your data is exported, the output from the script is written to the screen, as shown here.
Step 4	Check the output for error messages. If there are any, copy the output to a file and email it to Customer Support.
Step 5	Zip or tar the contents of: [tomcat directory]/webapps/uc/WEB-INF/plugins/com.uc/backup/unload/
Step 6	Copy the zip/tar file to a safe place for use after the upgrade process.
Step 7	Copy your `glide.properties` file to a safe place. You may need to consult this file later. The file is located here: [tomcat directory]/webapps/uc/WEB-INF/properties
Step 8	Copy your license key from the Properties list and store it in a safe place.
Step 9	Copy the LDAP mapping file to a safe place for use after the upgrade process. [tomcat directory]/webapps/uc/WEB-INF/properties/users/ldapmap.xml You can use this file for reference when creating LDAP mappings on the LDAP Settings page of the Controller 7.4.x user interface.

Stop Tomcat and Remove All Controllers

Important

Make sure you have copied to a safe location all of the exported files from the bulk export before continuing here, where you will stop Tomcat and remove the Controller.

Step 1	Stop the Tomcat containers in which all Passive Controllers are deployed: Windows Use the services application to stop Tomcat. You also can issue the stop command on a command line: net stop [name of Tomcat service] UNIX Stop the daemon using the script found in the `/etc/init.d` directory for Tomcat. service [name of Tomcat service] stop Windows or UNIX Stop the service using the `$CATALINA_HOME\bin\shutdown.bat` or `$CATALINA_HOME/bin/shutdown.sh` scripts: Windows cd $CATALINA_HOME\bin shutdown Linux/Unix cd $CATALINA_HOME/bin ./shutdown
Step 2	Confirm that the Tomcat processes where the Passive Controllers are deployed are not running. Windows Use the Windows Task Manager. Linux/Unix Use the `ps` command.
Step 3	Back up the Passive Controller deployment directories in any folder other than one under the Tomcat installation. The Controller installation process renamed the unpacked war file (`universal-controller-N.N.N.N-build.N.war`) as `uc.war`, so the following would be your deployment directory: [tomcat-install]\webapps\uc
Step 4	Repeat steps 1 through 3 for the Active Controller.
Step 5	Delete the deployment directory and `uc.war` file for all Controllers. The following would be your deployment directory and `uc.war`: [tomcat-install]\webapps\uc [tomcat-install]\webapps\uc.war Note If you want to rename the deployment directory and *uc.war* for back-up, you must do so outside of the Tomcat folder.

Prepare Your Database

Delete or drop your database using the appropriate database admin tool. You also can create a new database, using a different database name.

Important

Before dropping your existing database, make sure you have created a backup, as mentioned earlier in these procedures.

Download the New Controller

From the Stonebranch Customer Portal, download a Universal Controller package (for instructions, see Downloading Universal Controller Software).

Install the Controller

The Universal Controller is a Java application running within Apache Tomcat. For this reason, the Controller software and installation procedure is basically the same for all platforms.

If you will be running the Controller in a High Availability environment, complete the Controller installation for the targeted Active cluster node before installing the Controller for the targeted Passive node(s).

Note

If you have deployed any JDBC driver jar files (or in the case of DB2, a JDBC driver license jar file) to the $CATALINA_HOME/webapps/uc/WEB-INF/lib directory, you must recopy these files to this directory and restart tomcat after your initial validation.

Verify the Active Controller Installation

Step 1	Start Tomcat where the Active Controller is deployed. When the database initialization is complete and the Controller is running, you will see the following (for example) in the log: 2012-09-12-12:53:07:339 INFO [Ops.Cluster.Monitor.0] Server is now Running in Active mode. Previous mode was Passive. 2012-09-12-12:53:07:339 INFO [Ops.Cluster.Monitor.0] Setting server to ACTIVE.
Step 2	As a precaution, clear the browser cache.
Step 3	Log in to the Active Controller with `ops.admin` (password is not set). On the Universal Controller Home Dashboard, verify that the Overview specifies the correct release.

Run an Import on the Active Controller

In this procedure, you are performing a bulk import of the data that you exported earlier using a bulk export.

Step 1	Unzip/untar the backup file that you created earlier using the export.
Step 2	Copy the XML files to any directory on the Controller that it has access to.
Step 3	From the Administration navigation pane, select Configuration > Server Operations.
Step 4	Locate and run the Bulk Import Server Operation.
Step 5	The utility prompts for a confirmation. Click Yes.
Step 6	As your data is imported, the output from the operation is written to the screen. Look over the output for any error messages. If you see any, copy the output to a file and email it to Customer Support.
Step 7	Due to technology and feature changes in Universal Controller 6.7.x, a number of XML files will not be imported. These include but may not be limited to: Activity History Audit Reports Cluster nodes
Step 8	Apply your 7.3.x license key.

If you experiencing problems with the bulk import, do not continue; please contact Customer Support for guidance.

Check Your Data

At this point, your previous definitions, users and passwords have all been restored. Log out and in again, and review your records to make sure all your previous definitions, users, and passwords have been restored successfully.

LDAP Synchronization

Do not perform LDAP Synchronization until you have successfully bulk imported your data.

In order to log in to the Controller using LDAP credentials, you must set the LDAP Synchronization Enabled Universal Controller System property (Administration > Configuration > Properties in the Controller user interface) to true.

Verify the Passive Controller Installations

Step 1	Start Tomcat where each Passive Controller is deployed.
Step 2	Log in to the Passive Controller with `ops.admin` or a user with equivalent authorization. On the Universal Controller Home Dashboard, verify that the Overview specifies the correct release.

Start OMS

Do not start OMS until you have successfully bulk imported your data.

Start Universal Message Service (OMS).

The start/stop procedure for Universal Agent components (such as OMS) may differ depending on your platform. For instructions, see Starting and Stopping Agent Components.

Verify the Upgrade

Verify that the Controller is installed and running properly (see Verifying a Controller Installation).

Verify that your Agent components are communicating with the Active Controller (see Verifying Universal Agent Installation).