Installing the Agent for Database Jobs and Events

This page guides you through the installation of the agent used to execute database jobs and events in Windows and UNIX.

Tip! This page refers only to the manual installation process. If you want instructions on how to install a containerized Java agent, see Installing Containerized Java Agents.

Notes:

It is recommended to install the Agent in a separate directory.
The database agent for jobs and events is only available for a particular database type (such as MS SQL) and can be set in the INI file of the SQL Agent. A separate agent must be installed for each database type that can be accessed by jobs or events. Database and server names must be defined in the particular Job or Event object. For more information, see Agent SQL
This section describes the installation of the Agent in a system in which authentication is not used. If you want to use an authentication method, you have to carry out additional steps. For more information, see Agent Authentication.

This page includes the following:

Supplied Files

The files relevant for the Database Agent are stored in the directory IMAGE:AGENTS\SQL. Additionally, the Temp and JDBC (empty) folders are supplied. The Temp folder stores log files while the JDBC folder is meant to store the JDBC driver installation .

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Important! Make sure you are familiar with the TLS/SSL and certificate implementation before installing and/or upgrading the respective component. For more information, see:

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

Installing the Agent for Database Jobs and Events

On the admin and/or user computer where the Agent is installed, install the Java Runtime Environment (JRE).

If you have JRE installed, you can ignore this step. For a list of compatible java versions, see compatibility matrix.

Use the following command to check the version of the current Java virtual machine (VM):

java -version

If several JRE or Java SDK Versions are installed on the computer, make sure that the order of the directories is correct in the %PATH% or $PATH settings since the first JRE that is found in the list of directories is used.
On the host, install the Agent.
1. Create a separate directory for the Agent (for example, C:\AUTOMIC\AGENTS\SQL\BIN or C:\AUTOMIC\AGENTS\SQL_SERVICE\BIN).
2. Copy the content of IMAGE:AGENTS\SQL to the directory you just created. Under Windows, you can also use the program SETUP.EXE for the installation. It is available in the directory IMAGE:AGENTS\SQL\WINDOWS.
On the host, install the JDBC driver.

A suitable JDBC driver must be installed for all databases that the Agent uses. Refer to the particular vendor's installation guide.
1. Create the JDBC folder in the BIN folder of the Database Agent.
2. Copy the JDBC driver files to the JDBC folder after successfully installing it.
3. You must restart the DB Service Agent after installing a new JDBC driver in its JDBC folder.
Microsoft SQL Server
1. Install the relevant JDBC driver (Microsoft JDBC Driver for SQL Server or Microsoft JDBC Driver 4.0 for SQL Server) from the Microsoft site. The driver supports MS SQL Server 2005 and 2008 (2008 R2).
2. Copy the sqljdbc4.jar file to the JDBC directory of the agent after you have installed the driver.
  
  Notes:
  - If several JRE or Java SDK Versions are installed on the computer, make sure that the order of the directories is correct in the %PATH% or $PATH settings since the first JRE that is found in the list of directories is used.
  - When you start the agent under Windows, you can use the corresponding OS user for logging on to the MS SQL database (Windows authentication). When you install the JDBC driver, you must also copy the sqljdbc_auth.dll file to the BIN directory of the database agent. Make sure that the architecture of the file complies with the architecture of the JVM that is used (such as x64).
Oracle
1. Install the JDBC driver from the Oracle site.
2. Copy the relevant .jar (ojdbc5.jar or ojdbc6.jar) file to the JDBC directory of the agent after you have installed the driver.
  
  The JDBC driver version 9.0.1 or prior cannot be used with this Agent.
  
  The agent searches the relevant .jar file classes in the JDBC folder. The file name is irrelevant. It is important to use the most current .jar file. You might want to store only one jar file in the JDBC folder.
  
  Oracle RAC: The agent can also be configured so that it can connect to an Oracle database in RAC. For more information, see Connection to Oracle Databases.
  
  Note: The agent's connection information itself has to be defined by using Connection objects (for example: in SQL variables). In the Connection object you would use Oracle or Oracle OCI as connection type.
MySQL
1. Install the JDBC driver from the MySQL site.
2. Copy the mysql-connector-java-5.0.3-bin.jar file to the JDBC directory of the agent after you have installed the driver.
DB2

The JDBC driver is part of the DB2 installation. It is available in the SQLLIB/java directory (in Windows: C:\Program Files\IBM\SQLLIB\java). You can also download it from the IBM site.

Copy the db2jcc.jar (JDBC Type 4 Driver) and db2jcc_license_cu.jar (Server license) files to the JDBC directory of the agent.

Sybase
1. Install the JDBC driver (jConnect 5.5/6.05) from the Sybase site.
2. Copy the relevant .jar (jconn2.jar or jconn3.jar) file to the JDBC directory of the agent after you have installed the driver.
Informix
1. Install the JDBC driver (V3.5) from the IBM site.
2. Copy the ifxjdbc.jar and ifxlang.jar files to the JDBC directory of the agent after you have installed the driver.
  
  Notes:
  - The agent requires Informix databases with transaction support.
  - Due to an Informix error, it is necessary to specify the value for the environment variable DB_LOCALE in particular versions. The error "Database locale information mismatch." occurs if the DB_LOCALE has not been correctly set.
    
    In this case, define the value in the db_locale= parameter in the [INFORMIX] section of the INI file of the agent(use lower case). For example:
    
    [INFORMIX] db_locale=EN_US.CP1252
Ingres
1. Install the JDBC driver from the Ingres (ActianX) site.
2. Copy the iijdbc.jar file tto the JDBC directory of the agent after you have installed the driver.
SAP HANA

The JDBC driver is located in the HANA client installation directory.

Copy the ngdbc.jar file from the installation directory to the JDBC directory of the agent.
On the server computer, set up the system environment.

The DB Service Agent uses its own SQL Agent (UCXJSQLX.INI) INI file.
1. Adjust the SQL Agent (UCXJSQLX.INI) INI file to your system environment, see Agent SQL.
2. When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default. In this case, you only have to check that the root certificates already are in the respective store.
  
  If you do not want to use the default location for this component, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.
  
  For more information, see Securing Connections to the AE (TLS/SSL).
3. If the Agent starts in Windows, you can use the Windows user to log on to the database. The following steps are required:
  - Make sure the JDBC driver is installed as described above.
  - In the INI file of the SQL Agent, set the WindowsAuthentication= parameter to 1.
  - In the UC_HOSTCHAR_DEFAULT variable, set the ANONYMOUS_JOB parameter to Y. For more information, see UC_HOSTCHAR_DEFAULT - Host Characteristics.
4. In the admin or server computer, adjust the HEADER.WINDOWS, TRAILER.WINDOWS and RESTART.WINDOWS if necessary. For more information, see Executing Jobs.
Start the agent.
1. Make sure that the AE system is running on the server computer. For more information, see Multi-Server Operations.
2. On the host, start the Agent with the following command: java [Windows:]-Xrs -Xmx1G -jar ucxjsqlx.jar.
  
  An Agent object is automatically created in the system client 0 and stored in the HOST folder.
3. In AWI, client 0, verify that the Agent is logged on to the Automation Engine.
  
  Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.
  
  Assign the new Agent to clients with the required rights using the Agent object definition. For more information, see Authorizations Page.