Installing the Agent for Database Variables

This page guides you through the installation of the Database Agent for Variable objects with SQL source in Windows and UNIX. This Agent is also referred to as the DB Service Agent.

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. This is especially important since the DB Service Agent and the SQL Agent use the same binaries.
  • The DB Service Agent must be installed on the same computer as the Automation Engine. However, you can only log on to MS SQL Server databases via Windows authentication when the Automation Engine does not run on UNIX since the library sqljdbc_auth.dll cannot be loaded under UNIX.
  • You can use a DB Service Agent throughout the whole system, regardless of the authorization settings (Agent object > Authorizations tab).
  • The Agent for SQL variables (DB Service Agent) can access all supported database types. The database type must be determined in a DB-type Connection object that can be assigned to Variable objects with SQL source. This means that you only require one DB Service Agent for all SQL variables. You can also determine the database name and the connection parameters (such as Server name and port number) in the Connection object. For more information, see Connection (CONN).
  • The DB Service Agent uses its own SQL INI file. Since Variable objects with SQLI source access the AE database directly through the Automation Engine, they do not require an Agent. 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.

  • Usually one DB Service Agent per system is sufficient. If you want to use more than one agent, make sure you use the same JDBC driver for any additional instances.

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 Variables

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

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

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

  4. On the server computer, set up the system environment.

    The DB Service Agent uses its own SQL Agent (UCXJSQLX.INI) INI file.

    1. Adjust it 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. In the AE, create a DB Connection object for each database that is being used. You can also create connections for different database types. For more information, see Connection (CONN).

    4. If the Agent starts in Windows, you can use the Windows user to log on to the database. However, you have to set the IntegratedSecurity parameter to true in the corresponding DB Connection object.

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

      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.

    Use the ServiceManager to start or end the Agent as a service. For more information, see ServiceManager.

See also:

Installing the Agents