Upgrading Universal Controller from 5.2.0
- Former user (Deleted)
- Stonebranch (Deactivated)
- IT Stonebranch
Overview
For Universal Controller 7.2.x, upgrading refers to the increase of a currently installed 5.2.0 version of the Controller to a 7.2.x version (for example, upgrading Controller 5.2.0.5 to Controller 7.2.0.0).
You can upgrade to Universal Controller 7.2.x only from Universal Controller 5.2.0; you cannot upgrade to 7.2.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.2.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.2.x, applying maintenance refers to the increase from a currently installed 6.1.x or later release of the Controller to a 7.2.x release of the Controller (for example, increase Controller 6.1.3.1 to Controller 7.2.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.2.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 | |
|---|---|
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
8 | |
9 | |
10 | |
11 | |
12 | |
13 | |
14 | |
15 |
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.2.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 [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 |
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: net stop [name of Tomcat service] service [name of Tomcat service] stop 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. |
Step 3 | Back up the Passive Controller deployment directories in any folder other than one under the Tomcat installation. [tomcat-install]\webapps\uc |
Step 4 | Repeat steps 1 through 3 for the Active Controller. |
Step 5 | Delete the deployment directory and [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. 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 |
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:
|
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 |
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).