Upgrading an AE System from Version 10 to Version 12.3

Upgrade Utilities

Always use a separate directory in order to avoid mixing files of the different Automation Engine versions. Depending on the computer, you will either install one or several components.

1. First create a folder whose name represents the Automation Engine version. Then create an individual sub-folder for each component.

2. Install the utilities, see Installing the Utilities - UNIX or Installing the Utilities - Windows.

3. Copy the DB folder from the downloaded package to the directory of the utilities. It includes the files for loading the AE database. The DB folder must be a parallel folder of the utilities' BIN directory.

Example for Windows

Utility in C:\AUTOMIC\UTILITY\BIN

Database files in C:\AUTOMIC\UTILITY\DB

Upgrade AE and ServiceManager

1. Install the Automation Engine to a new directory, see Installing the AE - UNIX or Installing the AE - Windows.
2. Install the new ServiceManager version. Use a new name for the ServiceManager environment (phrase).

Upgrade Framework Integration (optional)

If you use a Framework Integration such as "AE Smart Plug-In for HP OpenView", it is best to install it in the new Automation Engine version.

Upgrade the Automic Web Interface

Upgrading an existing 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.

1. Stop the Apache Tomcat Service.

   1. Open your Windows Services manager.

   2. Stop the Apache Tomcat service.

2. Back up current files.

   These steps are optional. You can make a safety copy of your entire AWI 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.

   • To backup your whole AWI installation, go to your Tomcat installation, open the webapps folder and make a backup copy of the entire awi folder.

   • To backup only the configuration files, go to the folder where you have the current AWI version installed, and make a backup copy of the folder webapps/awi/config.

3. Upgrade the application server.

   Important: AWI runs only on Tomcat. If you want to use another application server for the Automic Web Interface, see Installing the Automic Web Interface.

   Before upgrading the application server, check the Automic Compatibility Matrix to see which version is compatible with AWI.

   You will find the upgrade instructions and other relevant information on the homepage of your application server provider. For more information, see Compatibility Information.

4. Restart the application server.

   You will find the relevant information on the homepage of your application server provider.

5. Deploy the new AWI version (WAR file) on your application server.

   If you are using Tomcat, copy the awi.war file to the webapps folder of the Tomcat installation. If the Tomcat is running, the awi.war file will be deployed automatically, creating a folder with the same name.

   Important! Deleting the awi.war file removes the corresponding subfolder, which also undeploys the AWI.

   If you are using WebSphere or WebLogic, please refer to their official documentation for more information.

   If you use WebSphere 8.5.5.x, make sure to delete the following files from the AWI folder before deploying the WAR file:

   • WEB-INF/lib/jaxb-api-2.2.11.jar

   • WEB-INF/lib/jaxb-core-2.2.11.jar

   • WEB-INF/lib/jaxb-impl-2.2.11.jar

6. Configure the new AWI version.

   For more information on how to configure your upgraded AWI, see Configuring Automic Web Interface.

   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 to the new webapps/<AWI>/config folder:

   • uc4config.xml:

     You can replace the new file with your backup.

     If you have more than one AE system connection defined, you can allow your users to choose their connection at login, or you can specify any of the defined connections as the only valid connection. You defined this in the automationengine.index setting of the configuration.properties file.

     Previously, users could not choose a connection and you had to be sure that your one valid connection was defined first in uc4config.xml.

   • configuration.properties:

     Important: 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 your AWI environment:

     • defaultHomeDashboard (This would be the dashboard attribute in the navigation.xml file.)

     • customHomeDashboardsFolder (This would be from the previous configuration.properties file.)

   • logback.xml:

     Do not restore your backed up version.

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

   • Theme folder:

     If you had customized the color or banner logo in your previous environment, then copy the contents of your backed up webapps/awi/config/theme folder to the folder of the same name in your current AWI version.

     For more information, see colors.properties.

Stop all clients

Stop all clients when your are about to upgrade. This is easily done in the system control of client 0000.

Stop the Automation Engine

Note: If you work in a distributed server environment, all server processes on all participating computers are deactivated. Also pay attention to programs such as Watchdogs, cluster monitoring etc. before ending the server processes. They might raise an alarm or restart the Automation Engine.

Back up the AE Database

As already described in the section on preparations, creating a database copy provides many advantages. Duplicate it now if you have opted for this step but have not yet executed it. If a database duplicate was already made at an earlier point in time, check if this duplicate must be upgraded.

Upgrade the AE Database

If you have created a duplicate, it is recommended to upgrade it now in order to make sure that the original instance remains operable. Keep in mind to enter the correct database connection in the INI files of the utilities.

Database Upgrade with AE DB Load Utility

Notes:

• It is recommended that a database administrator execute the following steps.

• Direct modifications that are made in database contents without using AE programs will result in an inconsistent database.

• Always make a database backup before you process any work steps.

• This process can take a while depending on the database size and upgrading complexity.

• Ensure there is sufficient disk space for the \AUTOMIC\DB directory and that the database's LOG section can store all this data.

• Schemes that provide access to the database should be removed after the updating process in order to avoid unintended database modifications.

• (DB2) After updating the AE database, check the size of the tablespaces and if required, run the following SQL statement:

  alter tablespace <UC4 tablespace name> reduce max:

• The DB directory of the installation image can include several versions of SQL scripts and database files. They are required if you upgrade several versions. Be sure to use the correct version if <vers> is indicated in the document.

• Modifications that should be made are available in the special_rt.sql file. Also execute the new_mq.sql file.

To Upgrade the Database with AE DB Load Utility

1. Change the database scheme and loading new initial data to the database.
• On the server computer, all server processes must be stopped. Pay special attention if server processes run on several computers. Close all components and end all active tasks such as Events, Schedules and so on. The EH table should not contain any data sets. This also applies when you move the AE to a different OS. For more information, see Process Monitoring.
• On the admin computer, the directory containing the database files must be stored at the location that has been specified in the INI file parameter INPUT of the AE DB Load utility (see AE DB Load). The folder that includes the BIN directory of the utilities is the default folder. 

Windows example:

• Utility in C:\AUTOMIC\UTILITY\BIN
• Database files in C:\AUTOMIC\UTILITY\DB
• For Windows utilities, the files for the AE database are provided in IMAGE:DB. Copy the complete DB folder to the above directory.
• For UNIX utilities: 
• The database files are included in the archive db.tar.gz, which is provided in the folder IMAGE:DB. To unpack the archive, use the following commands:
  gzip -d db.tar.gz or gunzip db.tar.gz
  tar xvfo db.tar
  (Linux: tar -zxvf db.tar.gz)
  Copy the unpacked files to the defined directory.
• Start the program AE DB Load to upgrade the database.Select the file <DB directory>\GENERAL\<vers>\UC_UPD.TXT
• The current database version is identified and the database upgraded. As this happens, the database structure and data are changed. Objects of client 0000 are automatically replaced or amended.

2. Select the authentication method

   On the admin computer, the AE.DB Load utility displays a dialog in which you must select an authentication method.

   This dialog is only displayed if the database is upgraded to a new Automation Engine version.

3. (Optional) Install partitioning with ILM

   On the admin computer, a dialog opens in which you can select the settings for partitioning with ILM. For more information, see ILM - Information Lifecycle Management.

   Important! You cannot undo an AE database partitioning process.

Configure and Start the Java Work Process (JWP)

As of version 11.2 of the Automation Engine the Export with references function and the full text search in the AWI require a JWP. For more information, see Installing the JWP.

Notes:

• As of version 12.0, the JWP installation is mandatory.
  
• As of version 12.1, it is mandatory to use and enable the JDBC section in the UCSRV.INI file.

The JWP is provided in the same directory as all the other Automation Engine files. The directory /configuration/ is created automatically when the JWP is first started and contains the OSGI bundle's cache.

Unpacking the files

In Windows, the JWP files are automatically copied from the SETUP.EXE program to the BIN directory. In UNIX, the files are located in the respective TAR archive.

Copy the provided "plugin" and "lib" directories into the BIN directory of the Automation Engine.

Important! If the bin directory for this installation already has a "plugin" and/or "lib" directory make sure to delete them before copying the new ones.

The subsequent installation steps depend on the database type used.

Java Cryptography Extension (JCE) (Optional - Only for SSO with Kerberos)

Important! JDK requires these policy files only if you work with Java 8. Java 9 and later versions include and use these files by default.

1. Install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.

   The JCE Unlimited Strength Jurisdiction Policy has to be installed on the machines where:

   • The Automic Web Interface runs.
   • The Automation Engine (JWP) runs.

   Download at Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy

   For IBM Java, you must use the policy files of IBM. The unlimited jurisdiction policy files are located in directory SDK /demo/jce/policy-files/unrestricted/. For more information, see https://www.ibm.com/support/knowledgecenter/en/SSYKE2_7.1.0/com.ibm.java.security.component.71.doc/security-component/sdkpolicyfiles.html.

   The Readme file contains the installation instructions on how to copy the .jar files to appropriate location (e.g. <java-home>\lib\security). If there are multiple Java installations on the same computer, setting up a policy file for all installations is recommended.

MS SQL Server

1. Install JDBC driver.

   1. Download Microsoft JDBC Driver for SQL servers.

   2. Follow the installation instructions on the page (download the .exe file, run it and enter and installation directory).

   3. After installing, copy the .jar file from the appropriate JRE destination folder to the <server>\bin\lib directory of the Automation Engine. Make sure to use the latest JDBC driver available for your Java version.

      Check the Automic Compatibility Matrix to find out which Java versions are supported. For more information, see Compatibility Information.

2. Activate TCP/IP in the MS SQL server. To do so:

   1. Open the SQL Server Configuration Manager.
   2. Expand SQL Server Network Configuration.
   3. Select Protocols for MSSQLSERVER under SQL Server Network Configuration.
   4. The TCP/IP must be set to Enabled in the right-hand section.
   5. Restart the SQL Server Services.

3. Determine the MS SQL server port.

   The default port of the MS SQL server port is 1433.

   Note: If you are not sure of the port of your MS SQL server instance, you can find this out from its ERRORLOG file (MSSQL > LOG). One of these messages: "Server is listening on [ 'any'<ipv4> port number]" or "Server is listening on [ 'any'<ipv6> port number]" should be found in the current log file, which contains the port.

4. Configure the database connection.

   The JWP uses the same INI file (UCSRV.INI, see Automation Engine) as all the other WPs of the Automation Engine system.

   JDBC connection to the database

   Define a separate database connection string for the JWP in the [JDBC] section. You can automatically generate this string by using the following command:

   java -jar ucsrvjp.jar -setup

   The system then verifies that the JDBC driver is available and that the database connection could be established.

   The advantage here is that the connection string of the other WPs ([ODBC] section) does not need to be changed or restarted.

   If you want to use Windows authentication, you must append ;IntegratedSecurity=true to the JDBC connection string in the [JDBC] section of the AE INI file.

   Example

   SQLDRIVERCONNECT=jdbc:sqlserver://localhost:1433;databaseName=AUTOMIC;IntegratedSecurity=true

   Note: When you install the JDBC driver and have to use Windows authentication, you must also copy the sqljdbc_auth.dll file to the BIN directory of the Automation Engine.

   DSN-less ODBC Connection

   This option uses the same database connection string that is also used by all the other WPs in the Automation Engine system. When installing a JWP for an existing system, all WPs must subsequently be restarted.

   A connection string is required in the [ODBC] section of the configuration file, the syntax of which does not require DSN. The server and database name must be specified directly in this case.

   SQLDRIVERCONNECT=ODBCVAR=SNNNNNRN,Driver={SQL Server Native Client VERSION};Server=tcp:SRVNAME,PORT;Database=DBNAME;UID=DBUSER;PWD=DBPWD

   • VERSION- Version of SQL Server Native Client. Is displayed in the SQL Server Configuration Manager.
   • SRVNAME - Name of the database computer.
   • PORT - port of the MS SQL server instance.
   • DBNAME - Database name.
   • DBUSER - Database user.
   • DBPWD - Database password.

   Example

   [ODBC]
   SQLDRIVERCONNECT=ODBCVAR=SNNNNNRN,Driver={SQL Server Native Client 11.0};Server=tcp:dbsrv01,1433;Database=AEV10;UID=user;PWD=password
   

   The entry should be on one line (no break).

Oracle

1. Install JDBC driver.

   1. Copy the JDBC driver ojdbc8.jar from the Oracle database client installation to the lib folder of the JWP.
      The file is located here: ORACLE_HOME/jdbc/lib/ojdbc8.jar.

   2. Copy the xdb6.jar, or xdb.jar, and xmlparserv2.jar files to the lib folder of the JWP to ensure that XML variables are processed correctly.

      The files are either part of the Oracle database or can be downloaded from the Oracle SQL Developer website. They are located here:

      • $SQLDEVELOPER_HOME/modules/oracle.xdk/xmlparserv2.jar

      • $SQLDEVELOPER_HOME/rdbms/jlib/xdb6.jar or $SQLDEVELOPER_HOME/rdbms/jlib/xdb.jar

2. Configure the database connection

   JDBC connection to the database

   Define a separate database connection string for the JWP in the [JDBC] section. You can automatically generate this string by using the following command:

   java -jar ucsrvjp.jar -setup

   The system then verifies that the JDBC driver is available and that the database connection could be established.

   More information on installing the JDBC driver is available in the Oracle JDBC installation instructions.

DB2

1. Install JDBC driver.

   Copy the file db2jcc4.jar (JDBC driver) into the lib directory of the JWP.

   This file is part of the DB2 client and is located in the sub-directory SQLLIB/java.

2. Configure the database connection

   JDBC connection to the database

   Define a separate database connection string for the JWP in the [JDBC] section. You can automatically generate this string by using the following command:

   java -jar ucsrvjp.jar -setup

   The system then verifies that the JDBC driver is available and that the database connection could be established.

PostgreSQL

1. Install the JDBC driver.
   

   Download the appropriate *.jar file from https://jdbc.postgresql.org/download.html and copy it into the lib directory of the JWP.

2. Configure the database connection

JDBC connection to the database

Define a separate database connection string for the JWP in the [JDBC] section. You can automatically generate this string by using the following command:

java -jar ucsrvjp.jar -setup

The system then verifies that the JDBC driver is available and that the database connection could be established.

SSL certificates for LDAP (Optional)

In order to use SSL, the certificate(s) of the LDAP server must be available to the Java Work Process. The JWP uses the default keystore file cacerts in the lib/security directory of the JRE.

Keystore file configuration options

Using an alternative keystore file:

If you want the JWP(s) to use an alternative keystore file, you have to define the file name and path to a centrally stored file in the JWP_KEYSTORE_PATH key in the UC_SYSTEM_SETTINGS variable. In case the defined path is not accessible or invalid, a log message will be written to the default log location and the JWP will use the default keystore file. For more information, see JWP_KEYSTORE_PATH.

Creating an individual keystore file using the JWP:

If you want to use an individual keystore file, you can create it using the following command:

java -jar ucsrvjp.jar -installcert host:port keystorePath

In case the defined path in keystorePath does not exist, the JWP creates a new keystore file in that location. You can then define a password for that keystore file.

Using an alternative password for keystore file access:

The default password used by the JWP is the default password of the JRE keystore. If you want the JWP to use a different password, you have to define a Login object containing that password by following these steps:

• Create a Login object (or use an existing one).
• Use the JWP_KEYSTORE_LOGIN key in the UC_SYSTEM_SETTINGS variable to enter the name of that Login object. For more information, see JWP_KEYSTORE_LOGIN.
• Open the referenced Login object, select the Login page and add a new row there.
• In the column Name, select "*", in the column Type select JWP_KEYSTORE.
• The Login info is optional for this function, but as this column cannot be empty by default, you have to enter something here.
• Enter the password you chose for the keystore file.

Adding the certificates

1. Add certificates using the keytool.

   1. To use the default keystore of the JRE, go to the jre\lib\security folder of the Java installation and import the certificate with the keytool command:

   keytool -keystore cacerts -importcert -alias ldapServer -file certficate.cer

   2. To use your own keystore file defined in the UC_SYSTEM_SETTINGS variable using the JWP_KEYSTORE_PATH key, go to the defined path and import the certificate with the keytool command:

   keytool -keystore <keystore> -importcert -alias ldapServer -file certficate.cer

   When prompted to trust this certificate respond by typing "Y".

   For more information, see JWP_KEYSTORE_PATH.

2. Add certificates via download.

   1. Another option to install the certificate is the command line parameter -installcert of the Java Work Process.

   java -jar ucsrvjp.jar -installcert <host>:<sslport>

   • This assumes that the Java Work Process has write access to the cacerts file of the Java installation.
   • This command detects the path of cacerts, connects to the specified host and port and tries to create an SSL connection.
   2. This command to add a certificate via download will set an optional parameter for the file name of the keystore:

   java -jar ucsrvjp.jar -installcert <host>:<sslport> <keystorePath>

   Notes:

   • When the parameter JWP_KEYSTORE_PATH is valid but the file doesn't exist, JWP creates a new keystore file in the same location. For more information, see JWP_KEYSTORE_PATH.
     During this process the user can define an individual password.

   • If a certificate is missing, the message "unable to find valid certification path to requested target" is printed and the missing certificate is downloaded and stored in the cacerts file.

Starting the JWP

Use this kind of command to start the JWP via the command line

java -Xmx2G -jar ucsrvjp.jar -Iucsrv.ini

The file ucsrvjp.jar is provided in the same directory as the other Automation Engine files. It is used exclusively to start the JWP.

The JWP can also be started via ServiceManager.

java -Xmx2G -jar ucsrvjp.jar -svc%port% -Iucsrv.ini

The -svc parameter should be omitted when starting directly via the command line.

The parameter -I to specify the INI file is optional. If the parameter is missing, the JWP attempts to find the file "ucsrv.ini" in the current working directory (= directory in which the file "ucsrvjp.jar" is located).

Start the Automation Engine and Clients

Cold-start the server processes when all installation and configuration step have successfully been completed. Do so in the INI file of the server processes by setting the parameter StartMode= to COLD. Now the processes can start.

Monitor the AE System

Do not yet replace the agents. Older agent versions run smoothly with newer Automation Engine versions. In order to take advantage of new features to the full make sure to upgrade agents as well.

Important! Do not change anything in your processing and carefully monitor your AE system over an extended period of time. A few hours or days are not enough. It can take a while before problems occur, especially if they are the result of a particular constellation in your processing.

Install the Agents

• We recommend using agents of the same service pack version as the Automation Engine. In general, use the latest service pack.
• You can connect agents of an older service pack, minor or major version to an Automation Engine of a newer service pack, minor or major version. The following preconditions need to be considered:
  • The agent version must still be under maintenance.
  • Functions and features introduced with a newer version of the agent cannot be used with a particular agent of an older version.
  • There might be exceptions. Check the Incompatibilities between versions sections in the relevant upgrade documentation, see Upgrade Installation.
• You cannot connect agents of a newer minor or major version to an Automation Engine of an older minor or major version.

Examples:

• Automation Engine v12.1.1 and agent v12.1.1
  Supported, best choice.
• Automation Engine v12.1.1 and agent v12.1.2
  Supported because the agent is on the same version, just a newer service pack
• Automation Engine v12.1.1 and agent v12.2.0
  Not supported because the agent is on a newer minor version.
• Automation Engine v12.1.1 and agent v11.2.7
  Supported when the agent version is still under maintenance.
• Automation Engine v12.1.1 and agent v11.1.8
  Not supported when the agent version is already out of maintenance.

Important!

• This information is valid for OS agents, application agents, and other Java-based agents such as the Rapid Automation core agent. However, it is not valid for Rapid Automation Solutions. Check the compatibility of RA Solutions in the Automic Compatibility Matrix, see Compatibility Information. Even if the currently used RA Solution is compatible, make sure that the RA Solution is still under maintenance. See Component Support Lifecycle.
• Do not remove or overwrite the installation directories of your agents. Back up the corresponding folder in order to make sure that you can quickly return to your old version.
• The new agents must be installed in a separate directory. An adequate monitoring period is essential. It is best not to replace all agents by the new version. Replace one platform after the other, for example. First replace UNIX and only replace the next one when the agents have proven to run stably for some time.

To ensure that jobs call the new Job Messenger, follow the steps below:

1. Correct the file name of the Job Messenger in the INI file when you upgrade the agent (variable UC_EX_JOB_MD).
2. When installing the new agent in the same directory as the old one, you must delete the old Job Messenger after the installation process.
3. Instead of adjusting the INI file during the upgrading process, you can also create a link that points to the new messenger. Use uppercase letters for the old messenger names. Example for Linux: ln -s ucxjli3m UCXJLI3M

Install the Remaining Components

Now you can replace components such as the CallAPIs. Keep in mind to monitor the newly installed version for some time.

Use the New Functions

• Monitor your upgraded AE system for a time. The upgrading process is complete if no problems occur.
• Now you can upgrade your production system. Repeat the steps made when upgrading your test system.