Upgrading an AE System from Version 11.2 to Version 12

Guidelines for upgrading to a new Automation Engine version.

Below you find the necessary steps for upgrading your system to the latest version.
To help you follow the individual steps of an upgrade process of your AE system meticulously, this topic is divided into several steps.

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

As of v11.2 the Zero Downtime Upgrade (ZDU) is available.
Automic strongly recommends using that procedure over the manual procedure described below since the ZDU can ensure continuous operations.

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

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

Preliminary Information

ClosedNotes

To ensure that your upgrading process is successful Automic recommends that you strictly follow the steps that are described in this guide.

Never upgrade a productive AE system without having it tested extensively in a separate environment.

For details about installing hotfixes, see the related topic hotfix installation.

ClosedGeneral Information

It is very important that you follow a structured procedure when you upgrade an AE system, because it guarantees that processing can be continued as soon as possible.
The following guidelines explain the required steps in detail and especially address areas that need special attention. Follow the recommended steps for a smooth conversion process and you will soon be able to use all the new functions of your new Automation Engine version.

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:

  1. Installation and comprehensive testing in a test environment.
  2. Planning the conversion time and creating a plan for a possible re-conversion.

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

  3. Make a backup of the AE database and all the components' directories.
  4. Upgrade your system step by step WITHOUT using the new functions.
  5. 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:

  1. 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.
  2. 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 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 is not included in this documentation. Changes to the XML file structure may happen anytime.

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

ClosedRequirements

Done

Condition

Carefully read the Release Notes of the relevant Automation Engine version. They include information that must be taken into account during the upgrading process.

The most important requirement is a test system. Comprehensive tests in a separate system are necessary before the new Automation Engine version is used in your production system. The test system helps you to get used to the necessary steps for upgrading your production system and even to optimize them.

Has your database been maintained on a regular basis? Automic recommends starting a reorganization run with AE utilities and database means before you upgrade the database. The smaller the database, the quicker the upgrading process. Note that it will still take some time to upgrade the AE database and that you will need sufficient disk space for having tables duplicated.

Authorizations for the affected computers, databases, ERP systems etc. are required during the various upgrade phases. Ensure that the responsible administrators are available during the particular work steps.

You can request assistance from consultants, developers 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 TeamTechnical Support Team as soon as you know when you are going to start the upgrading process.

Ensure that you have the phone number and e-mail address of Technical Support and your login data for the Download Center.

The Installation Steps

Closed1. Check Incompatibilities between Version 11.2 and 12

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

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.

 

Automic recommends installing a dedicated host for the AWI. For sizing recommendations, refer to Sizing of Automic Workload Automation Systems.

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 Automic: https://www.ca.com/us/services-support/ca-support/contact-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 transer 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.

Closed2. Prepare for Upgrade

Done

System
available:

Work steps

ClosedRead Release Notes

  • Start off by reading the Release Notes of the Automation Engine version to which you intend to upgrade. They are available in the "Release Notes" chapter of the Automation Engine documentation.

    • The section "Check Incompatibilities between Version X and Y" is very important. It contains information about incompatibilities and points out additional work steps that can be required during or even before the installation. Automic recommends preparing your AE system and your system environment accordingly.

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

ClosedPrepare 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 e-mail address of Automic Support and your login data for the Automic Automation Support zone ready. 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.

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

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

Closed3. Upgrade the core components

Done

System
available:

Work steps

ClosedUpgrade 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. An example is shown in the chapter about new installations.

    • Do not remove or overwrite the installation directories of your utilities. Back up the corresponding folders in order to make sure that you can quickly return to your old version if any problems occur.

  • 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

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

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

ClosedUpgrade Framework Integration (optional)

  • Alternately, you can carry out this step after the core components have been upgraded. The function Framework Integration is not available until it has been installed.

    • Do not remove or overwrite the installation directories of your utilities. Back up the corresponding folders in order to make sure that you can quickly return to your old version if any problems occur.

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

ClosedUpgrade the Automic Web Interface

Upgrading ECC to AWI 12

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

Stop the Apache Tomcat Service

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

Back Up Current Files

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

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

Upgrade Apache Tomcat

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

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

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

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

Restart the Apache Tomcat Service

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

Deploy the New AWI WAR File

Deploy the new version of the AWI on Tomcat.

  1. (Optional) Rename the WAR file to ECC.WAR, keeping the "war" extension. The name of the WAR file will also be the context path of your AWI installation.
  2. On the server where you have Tomcat installed, copy the WAR  file to the webapps folder of the Tomcat installation. If Tomcat is running, the WAR file will be deployed automatically, creating a folder with the same name.

    3. Warning: Do not delete the WAR file! If you do, Tomcat will also remove the corresponding subfolder, which also undeploys the AWI!

Configure the New AWI Version

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

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

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

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

    configuration.properties

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

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

    logback.xml

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

    The "theme" folder

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

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

Start the New AWI

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

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

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

    8080= the default port for Apache Tomcat

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

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

ClosedStop all clients

Starting with this step, your AE system is no longer available until the database has successfully been upgraded.

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

ClosedStop the Automation Engine

  • Stop all server processes. 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.

ClosedBack up the AE database

  • Back up your 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.

ClosedUpgrade the AE database

  • Automic strongly recommends reading the notes concerning database modifications below before starting the upgrading process.
  • Upgrade your AE database using the utility AE DB Load. The individual steps you find below.
  • 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.
ClosedNotes on Upgrading the AE Database

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.

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;
ClosedDatabase Upgrade with AE DB Load Utility


Notes:

The DB directory of the installation CD 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.

Procedure:

  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.
    • 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.
  2. 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 mask is only displayed if the database is upgraded to a new Automation Engine version.

  3. Install partitioning with ILM (optional)
    • 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.

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

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.

The subsequent installation steps depend on the database type used.

Java Cryptography Extension (JCE)

  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 UserInterface and/or the AWI 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.

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

  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.

    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. Modify the Automation Engine configuration file.

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

    The database connection must be modified in the configuration file for the JWP. There are 2 different options for this:

    • DSN-less ODBC Connection

      Please note that with this option, the same database connection string that is also used by all the other WPs in the Automation Engine system must be changed in the configuration file. When installing a JWP for an existing system, all WPs must be subsequently 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).

    • Separate connection string for the JWP

      With this option, a separate database connection string for the JWP is defined in the [JDBC] section.

      Example:

      [JDBC]
      SQLDRIVERCONNECT=jdbc:sqlserver://dbsrv01;databaseName=AEV10

      The name and password of the database user are used by the [ODBC] item, therefore you should not define any user and password in JDBC string because it can only be stored as cleartext.

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

ClosedOracle

  1. Install JDBC driver.

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

  2. Configure the database connection.

    There are 2 options:

    1) Connection via OCI

    Modification of the INI file "ucsrv.ini" is not necessary in this option. However, the JWP requires access to the Oracle database libraries in the same way as a WP. In UNIX, the environment variables LD_LIBRARY_PATH or SHLIB_PATH must therefore be selected accordingly, depending on the platform.

    More information on installing the JDBC driver can be found in the JDBC installation instructions from Oracle.

    2) Direct connection to the database

    You can connect directly to the database using the Oracle JDBC Thin driver.

    The [JDBC] section in the ucsrv.ini file must be configured accordingly. Example:

    [JDBC]
    SQLDRIVERCONNECT=jdbc:oracle:thin:@dbserver:1521/service_name

    The name and password of the database user can be found in the [ODBC] item, therefore you should not define any user and password in JDBC string because it can only be stored as cleartext.

ClosedDB2

  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.

    Modification of the ucsrv.ini file is not necessary.

    However, if required, the database connect string can be defined in the [JDBC] section of the INI file.

    Example:

    [JDBC]
    SQLDRIVERCONNECT=jdbc:db2://server:<port>/database

    The user name and password for database access can be found in the [ODBC] item, therefore you should not define any user and password in JDBC string because it can only be stored as cleartext.

Add certificates for SSL

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

  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:

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

    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:

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

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

  2. Add certificates via download.

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

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

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

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

ClosedStart 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.
  • All clients can be started from the System Overview of client 0000.

ClosedMonitor the AE system

  • Do not replace the agents yet. 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.

Closed4. Upgrade all other components

Done

System
available:

Work steps

ClosedInstall the Agents

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 also be installed in a separate directory. An adequate monitoring period is essential. Automic recommends not replacing 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 version 9, the UNIX agent files will be supplied in lowercase letters.

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

  1. Automic recommends: Correct the file name of the Job Messenger in the INI file when you upgrade the agent (variable UC_EX_JOB_MD).
  2. 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.
  3. 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

ClosedInstall the remaining components

  • Replace components such as the CallAPIs. Keep in mind to monitor the newly installed version for some time.

Do not remove or overwrite the installation directories of the remaining components. Back up the corresponding folder in order to make sure that you can quickly return to your old version.

ClosedUse the new functions

  • Now you can upgrade your production system. Repeat the steps made when upgrading your test system. Upgrading a test system optimally prepared you for upgrading your production system.
  • Again read the Release Notes of the new Automation Engine version after having upgraded your productive system. They list all new functions. Use them and extend your processing. Automic Support will be pleased to help you with any problem that may occur.
  • Enjoy using your new Automation Engine version.
  • Monitor your upgraded AE system for a time. The upgrading process is complete if no problems occur.