Upgrading an AE System from Version 11.1 to Version 12.1

Guidelines for upgrading to a new Automation Engine version.

If you want to upgrade from an Automation Engine version that is out of maintenance, please contact support!

For help with your upgrade, contact Automic Technical Support.

If you would like to print this page, click in the menu bar above to expand the steps below:

Preliminary Information

When changing the version of the Automation Engine, the utility AE DB Load processes and monitors all the required steps for changing the database. This is necessary, because it also modifies data that cannot be changed with SQL. All steps that the utility processes during the upgrading process are logged in the file uc_upd.txt. The file chngdb.sql also informs about the database-relevant statements that were set. These statements must be processed by the utility. Refer to the Release Notes of the relevant Automation Engine version for changing the database and preparing the necessary steps.

The upgrading process comprises of several stages:

Planning the conversion time and creating a plan for a possible re-conversion.

Never change to a new Automation Engine version without having planned a re-conversion scenario.

Make a backup of the AE database and all the components' directories.
Upgrade your system step by step WITHOUT using the new functions.
Only use the new functions when every component has been converted to the new version and after a particular system-monitoring period.

Each stage consists of many small steps. Your AE system is not upgraded all at once but step by step. The old components are not overwritten and the new files are installed in separate directories. Only the AE database is directly upgraded with the utility AE DB Load. This method has two main advantages:

You can quickly re-convert to the old AE-component version if problems occur in your system environment. Therefore, there is almost no risk for your processing.
Depending on the size of your AE system, the complete upgrading process can take some time. The advantage of upgrading step by step is that you can do so in individual and shorter periods of time which makes it easier to coordinate the upgrading process with other departments and processes. And it is also easier to locate errors that might occur.

First upgrade your test system. Possible problems can so be recognized and solved before they occur in your production system. Test the individual upgrading steps, thereby setting up a plan for upgrading your production system.

The AE system is not available while the database is being upgraded.

After each step of the upgrade installation, it is essential to monitor the new components for some time. Only continue the upgrading procedure when they have proven to run stably.

Note that the upgrading process Automic recommends enables production to be continued in the old Automation Engine version at any time. The only requirements are a parallel installation of the components and the provision of a second database instance.

Use the message-comparing program if you require a list of all changed messages.

Objects can be exchanged between different Automation Engine systems or between individual clients via the Import/Export function. The object information is stored in an XML file. Since this is not a supported interface for any other propose than that, the documentation of the XML file structure was removed from the documentation. Changes to the XML file structure may happen anytime.”

Requirements

Done	Condition
	Carefully read the Release Notes of the relevant Automation Engine version. Pay special attention to changes that would affect your installation. Check the System Requirements in our online database, the Automic Compatibility Matrix
	Upgrade a test system first.
	Test your workflows in the test system before upgrading the production system.
	Make sure access to the computers and database is granted for administration.
	Decide your type of upgrade: backup/restore the whole environment (in place upgrade) or duplicate the environment (parallel upgrade) and decide if agents will be updated along with the engine.
	You can request assistance from consultants or even 24x7 support when you upgrade your system. Our experts are trained in providing excellent support when action is taken in critical and sensitive areas of your AE system. Contact your Account Manager or the Technical Support Team as soon as you know when you are going to start the upgrading process.
	If the database scheme derives from the standard, the AE Scripts must be adopted according to the modifications.
	Ensure that you have the phone number and email address of Technical Support and your login data for the Download Center.

The Installation Steps

1. Check Incompatibilities between Version 12 and 12.1

The table below lists new features that might lead to compatibility issues or should be taken care of when upgrading - it does not list all new features of this AE version.
New features are described in full in the release highlights.

Description of the table columns:

Topic - Name of the general topic or new feature
Changed behavior - What has been changed
Possible incompatibilities - Impact the change may have
Actions/Countermeasures - What can be done to identify and/or remove possible incompatibilities

Topic	Changed Behavior	Possible Incompatibilities	Actions/Countermeasures
General DB change Information and the checking instructions apply to all versions, between your existing installation and the latest you want to upgrade to, respectively.	The DB scheme/structure has been changed.	Custom SQL queries on AE DB do not work anymore.	Check chngdb.sql for general changes Check and adapt relevant SQL/SQLI/SQLJOBS objects accordingly Check and adapt relevant DB queries used in external tools/programs
Java Communication Porcess (JCP)	Installation of JCP(s) is mandatory for AE operations.	JCP/REST API is a required component as of 12.1 but it is not installed.	Install JCP(s)
Java >= 1.8 required	As of version 12.1 all components using Java (except RA solutions) have been lifted from Java 1.7 up to 1.8 compile compatibility.	Java components will not run on computers with Java Version 1.7 or lower.	Upgrade Java Runtime to version >= 1.8.0.
IPv6	Support for IPv6	None	The system runs either in IPv4/IPv6 only environment, or a dual-stack environment where both is allowed.
500k agent support	AE supports up to 500k agents: changed default for srvquery (ucsrv.ini) from 0 to 1, but has no impact on the AE CP writes job reports directly into the database	CPs now write job reports directly into the report tables within the AE database instead of passing it to the RWP. The load on CP side will therefore increase, but poses no problem at all.	If the customer experiences a performance drop due to this change of behavior, it is best to start more CPs to distribute the load.
Remove deprecated ResourceAdapter from ApplicationInterface	ResourceAdapter is no longer supported after being deprecated.	ResourceAdapter no longer available.
AE REST API introduced	The completely new AE REST API is introduced. Some of its functional parts replace existing functions (e.g. object search). If the JCP does not work properly, the user will not be able to use specific functions.	If the new JCP is not set up and configured properly, AWA will not work as expected after an upgrade.	JCP has to be installed. Its INI file has to be configured properly (Object Search, REST WS).
New PS Agent	The tech stack of the PS agent has been changed to Java and some new functions have been added (as of V12.0.1). The new agent works with existing/old PS jobs and INI files without incompatibilities.	The new PS agent supports JVM 64 bit It is built on Java (not on C like the old one). It doesn't support the "native interface"(only the Automic-speific one) anymore (PS agents configured to use the "native interface" do not start up and an according message is written to the agent log).	If a PS job uses the "native interface" it has to be changed to use the Automic-specifc interface instead. There is no need to use JVM 32 bit anymore The installation/upgrade of a PS agent replaces previous versions entirely

2. Check Incompatibilities between Version 11.2 and 12

Description of the table columns:

Topic - Name of the general topic or new feature
Changed behavior - What has been changed
Possible incompatibilities - Impact the change may have
Actions/Countermeasures - What can be done to identify and/or remove possible incompatibilities

Topic	Changed Behavior	Possible Incompatibilities	Actions/Countermeasures
General DB change Information and the checking instructions apply to all versions, between your existing installation and the latest you want to upgrade to, respectively.	The DB scheme/structure has been changed.	Custom SQL queries on AE DB do not work anymore.	Check chngdb.sql for general changes Check and adapt relevant SQL/SQLI/SQLJOBS objects accordingly Check and adapt relevant DB queries used in external tools/programs
Java Workprocess (JWP)	Installation of JWP(s) is mandatory for several functions in Automation Engine and AWI.		Install JWP(s)
UserInterface	The UserInterface has been replaced by the Automic Web Interface. The new features for v12 have been implemented for the AWI exclusively.
Service Level Management (SLM)	The Service Level Management via the Service Level Objective objects (SLOs) is a new function as of v12. The general Automation Engine behavior has not changed but the SLOs' monitoring may affect system performance. The monitoring has been implemented by checks via CPs and JWPs.
Zero Downtime Upgrade in AWI	As of v12 the ZDU is available in the AWI. Take care not to conduct the ZDU steps using UI and AWI alternately. Perform the ZDU either via AWI or UI exclusively.
Change of script function behavior: PREP_PROCESS_FILENAME PRE_PROCESSS_FILE PREP_PROCESS GET_FILESYSTEM	In connection with the new feature Centralized Agent Upgrade (CAU) the behavior of these script functions has been changed. They do not abort anymore, if an agent is not available but stay in "Waiting for host" instead.
All ServiceManager actions require a password.	The password defined in the ServiceManager settings is now required for all possible actions in the ServiceManager.	You will be prompted for a password when: moving an entry up or down opening properties editing/deleting/duplicating an entry	Enter the correct password when prompted.
Rapid Automation (RA) agent solutions	In order to edit RA objects in the AWI, you must upgrade your RA agent solutions to versions that support the AWI. The latest version of most, but not all, RA solutions support the AWI. For information on specific RA solutions, see the Automic Compatibility Matrix.		Contact Technical Support.
Web Service agent changes	New versions of the Web Service agent were split into separate RA solutions for SOAP (4.0.0) and REST (4.0.0).	Existing objects of version 3 are not automatically migrated to objects of version 4.	To migrate existing jobs from version 3 to 4 do the following : For SOAP migrate objects manually. For REST use the migration assistant.
DB Load and upgrade on SQL-Server	If the parameter in the SQL database READ_COMMITED_SNAPSHOT = FALSE then: The upgrade has to be done by a user who has dbowner rights. During the database upgrade no additional users besides DB Load are allowed. Therefore in such cases the Zero Downtime Upgrade (ZDU) is not available.		Set READ_COMMITTED_SNAPSHOT = TRUE
Automic File Transfer from/to z/OS Agent	During the file transfer, switching between the agent and the file transfer user is enabled by default.	Note that you may need additional permissions for the file transfer and the agent user. The function call seteuid()/setegid() may fail.	Make sure that the permissions specified in the installation documentation of the z/OS agent are granted. Workaround: Set parameter ft_thread_level_security=no in the Agents’s INI file at the (GLOBAL) section.

3. Check Incompatibilities between Version 11.1 and 11.2

Description of the table columns:

Topic - Name of the general topic or new feature
Changed behavior - What has been changed
Possible incompatibilities - Impact the change may have
Actions/Countermeasures - What can be done to identify and/or remove possible incompatibilities

Topic	Changed Behavior	Possible incompatibilities	Actions/Countermeasures
General DB change Information and the checking instructions apply to all versions, between your existing installation and the latest you want to upgrade to, respectively.	The DB scheme/structure has been changed.	Custom SQL queries on AE DB do not work anymore.	Check chngdb.sql for general changes Check and adapt relevant SQL/SQLI/SQLJOBS objects accordingly Check and adapt relevant DB queries used in external tools/programs
Release Packaging	The Release Packaging (zip files, folder structure and its content) have been changed. The following files and folders have been removed: Folder ./11/ (the content, e.g. UserInterface, AutomationEngine) are now directly in the base directory and no longer in the sub folder. The uc4setup files and the CD image files have been removed. There is a new installer available for single box installation in the product bundles.	Possibly automated installation routines using release images will not work.	If there are scripts relying on the old package structure, you have to adapt the paths.
CP/WP routing	FORMS request routing to RA agents has been changed.	When you edit RA connection objects, a corresponding RA agent has to be active in the same client to retrieve data.	Assign an RA agent for relevant clients.
Third party monitoring via External Monitoring Interface	The new state-of-the-art JMX interface EMI (External Monitoring Interface) has been introduced. The existing SNMP interface is still available, but the third party integration with BMC Patrol, HP OpenView, and Tivoli has been de-supported.	There is no incompatibility, but the integration with BMC Patrol, HP OpenView, and Tivoli is not available anymore.	Integrate third party monitoring systems via the new EMI instead.
Doubled MQ tables	MQ tables have been doubled and renamed.	MQ tables might not be considered when you use DB Reorg and existing scripts might fail due to changed table names.	Adapt DB Reorg scripts.
Proxy INI file extensions	Parameters and the format of some parameter values have been changed in the INI file due to functionality improvements.	You will not be able to reuse INI files of Proxy versions prior to v2 without adaptions.	Adapt INI file parameters according to the Proxy user documentation.

4. Prepare for Upgrade

Done	System available:	Work steps
		Deny New Job Starts Inform all affected persons about the upgrading process and make sure that processing is not changed. Create a user group that explicitly denies everything and assign all users to this group. If the Revision Report is activated in your AE system, the assignment to the user group must be made in the User object because the tab is locked in the user group object in this case. Processing must not be changed during the whole upgrading procedure. If a problem occurs in your system environment during a particular step, you can either restore the AE database or directly use the original one if you made a copy. In doing so, there is almost no risk for your processing. Statistical data, reports, and modifications made to Variable object and Sync object contents are lost.
		Prepare the Upgrading Process of Core Components Determine a point in time for upgrading the core components. Note that the Automation Engine must temporarily be stopped which interrupts processing. For this reason Automic recommends determining a time during which only a few activities take place. The duration of the upgrading process depends on the size of your AE system. Your experiences when upgrading the test system will help you estimate the required time to upgrade your productive system. Ensure that you have the phone number and email address of Technical Support and your login data for the Download Center. Carefully think about requesting temporary 24x7 support, if sensitive systems should be upgraded or if the upgrade is not made during the regular business hours of our support team. Our experts are trained in providing excellent on-site support in upgrading your AE system. Contact your Account Manager or the Automic Support Team. Your request will be forwarded to the relevant expert in order to make an appointment. During the upgrade process, you require access to the AE database and to all computers with AE core components (such as the Automation Engine, utilities etc.). Access to all affected computers is required, if you work in a distributed Server environment. Ensure that the responsible administrators are available and that the login data (such as passwords) is correct.
		Maintain the AE database Automic generally recommends that you maintain your AE database with our utilities and database-specific tools on a regular basis. However, reorganize your database before you upgrade it. The smaller the database, the faster the upgrading process to the new Automation Engine version will be. Carefully read the AE Scripts that refer to the AE database and prepare adjustments (e.g., tablespaces). In doing so, you see the actions that will take place and respond to them in the database and on the computer on which the database has been installed (e.g., by providing disk space). These scripts are provided in the directories IMAGE:DB\GENERAL\<version> and IMAGE:DB\<database type>\<version>. The files uc_upd.txt and chngdb.sql are especially important.
		Duplicate the AE database For company-critical processing in the AE system Automic recommends duplicating and backing up your database. In doing so, you may leave one of the databases unchanged and easily re-access your old database, if any problems occur in your system environment. The database can be duplicated in several ways: For smaller databases: Duplicate the database in offline mode. This can be done during the upgrading process of the core components. During this time, the AE system is not available anyway. For larger/complex databases: Upgrade in online mode before the core components are upgraded. Inform your database-administration group because the current log files must be stored in the duplicated database.

5. Upgrade the core components

Do not remove or overwrite the installation directories of your Automation Engine, ServiceManager or Utilities. Back up the corresponding folder in order to make sure that you can quickly return to your old version.

Done

System
available:

Work steps

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.

First create a folder whose name represents the Automation Engine version. Then create an individual sub-folder for each component.
Install the utilities (UNIX or Windows).
Copy the folder "DB" from the CD 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

Install the Automation Engine (UNIX or Windows) to a new directory.
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", Automic recommends installing it in the new Automation Engine version.

Upgrade the Automic Web Interface

Upgrading ECC to AWI 12.1

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

Open your Windows Services manager.
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.

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.
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.

Check the System Requirements in our online database, the Automic Compatibility Matrix to see which version of Tomcat you need.
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

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

Deploy the New AWI WAR File

Deploy the new version of the AWI on your application server.

(Optional) Rename the WAR file to AWI.WAR, keeping the "war" extension. The name of the WAR file will also be the context path of your AWI installation.
Do one of the following:
Tomcat installation
On the server where you have the Tomcat installed, copy the WAR file to the webapps folder of the Tomcat installation. If the Tomcat is running, the WAR file will be deployed automatically, creating a folder with the same name.
Do not delete the WAR file! If you do, the application server will also remove the corresponding subfolder, which also undeploys the AWI!
WebSphere installation
Please refer to the IBM WebSphere official documentation for details.

Configure the New AWI Version

Configure your upgraded AWI.

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>/config	Configuration 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."

Stop all clients

Stop all clients when the upgrading time is ripe. This is easily done in the system control of client 0000.

Stop the Automation Engine

If you work in a distributed server environment, note that all server processes on all participating computers are deactivated.

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, Automic recommends upgrading 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.

Notes on Upgrading the AE Database

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;

Important Notes:

Automic recommends 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;

Database Upgrade with AE DB Load Utility

Notes on Upgrading the AE Database

Important Notes:

It is recommended that a database administrator executes the following steps.
Direct modifications that are made in database contents without using AE programs will result in an inconsistent database.
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.

Database Upgrade with AE DB Load Utility

Notes:

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

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 Automation Engine to a different OS.
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 utility 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 bzw. 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.

Select the authentication method

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

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

(Optional) Install partitioning with ILM

On the admin computer, a mask opens in which you can select the settings for partitioning with ILM.

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 function Export with references and the full text search in the AWI require a JWP.

General

As of v12, several important functions in the Automation Engine and thus AWA depend on the JWP being installed and running.
Therefore the JWP's installation is mandatory.

As of v12.1.1, it is mandatory to use and enable the JDBC section in the UCSRV.INI file.

Files Provided

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.

To Install the JWP

Unpack 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.

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)

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/. 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

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.
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.
Determine the MS SQL server port.

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

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.
Configure the database connection

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

JDBC connection to the database

Define a separate database connection string is 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.

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

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 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
Configure the database connection

JDBC connection to the database

Define a separate database connection string is 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

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.
Find the installation steps below.

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 key JWP_KEYSTORE_PATH, 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.

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).
In the UC_SYSTEM_SETTINGS variable, using the key JWP_KEYSTORE_LOGIN, enter the name of that Login object.
Open the referenced Login object, select the Login tab 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

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:
2. To use your own keystore file defined in the variable UC_SYSTEM_SETTINGS using the key JWP_KEYSTORE_PATH, go to the defined path and import the certificate with the keytool command:
Add certificates via download.
1. Another option to install the certificate is the command line parameter -installcert of the Java Work Process.
2. This command to add a certificate via download will set an optional parameter for the file name of the keystore:
When the parameter "keystorePath" is valid but the file doesn't exist, JWP creates a new keystore file in the same location.
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.

Start the JWP

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

java -Xmx512M -jar ucsrvjp.jar -IC:\temp\ucsrv.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 -Xmx512M -jar ucsrvjp.jar -svc%port% -IC:\temp\ucsrv.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).

Configure and Start the Java Communication Process (JCP)

The files needed for JCP are the same as the files provided for JWP in the same directory as all the other Automation Engine files.

Since the JWP's installation is mandatory and the files necessary for the JCP are the same as those used to install the JWP, there is no need to unpack any files nor to carry out any other installation step.

The JCP installation is relevant for the AE REST API as well as for the advanced object search. Therefore, make sure to configure the REST section of the Automation Engine configuration file (ucsrv.ini) accordingly. Otherwise the AWA object advance search will not work.

We recommend using HTTPS.

HTTPS/SSL set up for AE REST API

In order to use HTTPS you need to set the parameter sslEnabled to 1 and continue with the setup of the following parameters in the Automation Engine configuration file (ucsrv.ini):

keystore

This parameter is mandatory and needs to point to the correct target, otherwise the JCP server will terminate.
keystorePassword
keyPassword

The keystorePassword and the keyPassword can be encrypted with the UCYBCRYP Utility.

Adding the certificates

JCP uses keystore as defined in the Automation Engine configuration file. For additional information as well as information on adding certificates, see https://www.eclipse.org/jetty/documentation/current/configuring-ssl.html.

Start the JCP

Use this kind of command to start the JCP via the command line:

java -Xmx512M -jar ucsrvjp.jar -IC:\temp\ucsrv.ini -rest

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

The JCP can also be started via ServiceManager.

java -Xmx512M -jar ucsrvjp.jar -Iucsrv.ini -svc%port% -rest

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 JCP attempts to find the file "ucsrv.ini" in the current working directory (= directory in which the file "ucsrvjp.jar" is located).

Setting Up Multiple REST API Processes

When using multiple JCPs it is imperative that each JCP uses its own Automation Engine configuration file (ucsrv.ini).

If only one INI file is used for more than one JCP, the first one will connect successfully while the others will terminate upon trying to register the same REST port if both run on the same node. An error message is written to the JCP's log file stating the reason for termination.

The AE REST API can be installed multiple times, either with different port numbers on one node or on different nodes (in this case the same port number may be used).

The following scenarios are supported:

Single JCP

In this case a single JCP is used and all REST requests are sent to this single AE REST API instance. This means that no fail-over capabilities are provided and no AE REST API is available if the JCP is down.

Clustered JCPs

In this case two JCPs are used in a cluster but only one of both is available at the time, thus providing fail-over capabilities. All REST requests are sent to only one of the two AE REST APIs, depending on their respective availability.

To use this configuration a JCP needs to be installed on each node but both JCPs share the same Automation Engine configuration file (assuming the cluster shares the same installed resources). If a virtual IP is being used, both JCPs can be reached via the same IP address. This means the endpoints have the same base URI: http(s)://{host}:{port}/ae/api/v1/{client}/...

Please note that a configuration with multiple JCPs is not intended for load balancing purposes.

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.

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.

6. Upgrade all other components

Done

System
available:

Work steps

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.
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 Notes:

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 Compatibility Matrix. 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.
As of v9, the UNIX agent files will be supplied in lowercase letters.

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

Automic recommends: Correct the file name of the Job Messenger in the INI file when you upgrade the agent (variable UC_EX_JOB_MD).
Important: When you install the new agent in the same directory as the old one, you must delete the old Job Messenger after the installation process.
Instead of adjusting the INI file during the upgrading process, you can also create a link (with the old messenger names in uppercase letters) that points to the new messenger.
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.