Installing the JWP

This page guides you trough installing and starting the Java work process (JWP).

Notes:

  • If no JWP is available at login, the login fails and an error message is displayed. The system also notifies you if, for any reason, the minimum number of processes is not fulfilled during a session. The notification disappears once the process is running again.

    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.

  • The JDBC connection string uses the username and password defined in the [ODBC] section of the INI file of the Automation Engine (UCSRV.INI, see Automation Engine) to connect to the database.

This page includes the following:

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

TLS/SSL Certificate Authority for Agents (Optional)

To secure the communication between agents, the Automation Engine automatically generates a public/private key pair and a self-signed certificate authority upon first startup.

However, you can use your own CA to manage your certificate and its respective key pair. To do so, you have to create the UC_AGENT_TLS_SETTINGS variable in Client 0 and define the relevant settings. For more information, see UC_AGENT_TLS_SETTINGS - Agent Certificate Management.

TLS/SSL Certificates for LDAP (Optional)

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

There are a number of 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:

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

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

      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 a TLS/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>

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

You can start a JWP as a dedicated process with a specific role. For example, you can use the following command to start the JWP as a dedicated process with for the authentication (AUT) role:

java -Xmx2G -jar ucsrvjp.jar -Iucsrv.ini -role=AUT

You can also start the JWP with a dedicated IDX or UTL role by setting the -role command line parameter accordingly.

Note: When you assign a role to and start a JWP using the command line, this server processes is used exclusively for the role you defined in the command line. In this case, the JWP cannot take over tasks of other JWPs if they should stop.

For more information, see JWP Roles.

Next step:

Installing the REST Process