Download and Run the Connectivity Agent Installer

You must create an agent group and download and run the connectivity agent installer to install the agent in your local environment.

Create an Agent Group

You must create an agent group in Oracle Integration before you can run the connectivity agent installer. When you install the connectivity agent in your environment, you associate the connectivity agent with the agent group identifier. Up to two connectivity agents can be associated with an agent group. For a single Oracle Integration instance, you can create up to five agent groups. Creating the agent group also creates the necessary artifacts required for message exchange.

To create an agent group:
  1. In the left navigation pane, click Home > Integrations > Agents.

  2. Click Create Agent Group.

    The Create New Agent Group is displayed.

  3. Enter the following information, then click Create.

    Field Description

    Name

    Provide a meaningful name so that others can understand the agent name. The name must be unique among all agent names in the system. The name can consist of the following:

    • Letters (A-Z, a-z)

    • Numbers (0-9)

    • Spaces ( )

    • Special characters ( _ - )

    The name must not begin or end with a space and cannot be longer than 50 characters.

    Identifier

    Accept the default identifier value or change it, if necessary. The identifier is initially the same as the agent group name you provided, but in upper case. When you install the agent, you must specify the identifier value.

    Note: After creating the agent group, you cannot edit the agent group identifier. Instead, you must delete and recreate another agent group to associate with a different agent group identifier.

    Type

    Connectivity Agents Group is displayed and cannot be edited. The connectivity agent supports integrating with on-premises systems. The agent group references only connectivity agents.

    Description

    Provide a meaningful description so that others can understand the responsibilities of the agent group.

System Requirements

Satisfy the following system requirements before installing the on-premises connectivity agent.

  • Oracle recommends installing and using JDK 11. JDK 8 has been deprecated for use with the connectivity agent. See Upgrade the Existing JDK 8 Agent to the JDK 11 Agent and Revert Back to the JDK 8 Agent in Case of Issues. You do not need to purchase a JDK license. See JDK license and support for OIC Connectivity Agent (Doc ID 2611142.1).

    Note:

    There are JDK 11 restrictions when using the Oracle WebLogic JMS Adapter. See Connectivity Agent Restrictions.

    The JDK installation can be shared with other products installed on the same host. However, ensure that the JDK installation is not modified for use with these other products.

  • The agent is certified on the following operating systems:
    • Oracle Linux 6.x

    • Oracle Linux 7.x

    • Oracle Linux 8.0

    • RedHat Enterprise Linux 6.6

    • RedHat Enterprise Linux 7.x

    • RedHat Enterprise Linux 8.x

    • Suse Linux Enterprise Edition 12 SP2

    • Windows Standard Edition 2016

    • Windows 2019

    Note:

    IBM or Open JDK are not supported.
  • Provide a minimum of 8 GB memory with 4 GB of heap size dedicated for the agent JVM. If you want to include any other processes on that host besides the on-premises agent, it is strongly recommended that you increase physical memory to a value greater than 8 GB.

Upgrade the Existing JDK 8 Agent to the JDK 11 Agent

  1. Stop the existing connectivity agent.
  2. Set JAVA_HOME and PATH to JDK11.
  3. Restart the connectivity agent.

Revert Back to the JDK 8 Agent in Case of Issues

  1. Stop the connectivity agent.
  2. Set JAVA_HOME and PATH to JDK8.
  3. Restart the connectivity agent.

Connectivity Agent Restrictions

Note the following connectivity agent restrictions.

  • When the Oracle WebLogic JMS Adapter is used with a version of Oracle WebLogic Server prior to 12.2.1.4, JDK 11 is not supported. To know your version of Oracle WebLogic Server, perform the following steps:
    1. Enter the Oracle WebLogic Server URL. For example:
      http://abcweblogic.oracle.com:7001/console
    2. At the bottom left, find the version. For example:
      WebLogic Server Version: 12.2.1.4.0
  • When installed on a Windows host, the connectivity agent does not work with a proxy using NT LAN Manager (NTLM) authentication.

Agent Download and Installation

The agent must be downloaded and installed on your local host. If needed, you can also install a security certificate on your local host. If necessary, you can also run the agent installer as a background process.

Download and Install the Agent

Install the connectivity agent installer to install the agent in your local environment. During installation, you associate the connectivity agent with the agent group identifier you generated when creating an agent group in Oracle Integration.

Note:

  • You must have the Java execute permission to install and restart the agent.
  • You must have the ServiceAdministrator or ServiceDeveloper role to download the agent.

    See What Users Can Do in the Integrations Design Section by Role of Provisioning and Administering Oracle Integration and Oracle Integration for SaaS, Generation 2.

  1. Create a directory for connectivity agent installation on your on-premises host.

    Note:

    • Do not install the agent in a directory path that includes /tmp.

      The agent must never be installed in /tmp. As per the Filesystem Hierarchy Standard version 3.0, /tmp is meant for temporary files. Even though the install and agent work, it is not a recommended location for agent installation because the directory in /tmp may be deleted after the reboot of the system or agent virtual machine.

    • Agent installation is not supported with use of an SSL proxy.
  2. In the left navigation pane, click Home > Integrations, then click Agents.

  3. Click Download > Connectivity Agent.

  4. Download the connectivity agent installer to the directory on your on-premises host.

  5. Unzip oic_connectivity_agent.zip.

  6. If you need to add any third party JARs (for example, for the Siebel Adapter or MySQL Adapter), copy them under the agenthome/thirdparty/lib directory.

    Note:

    If you perform this step after installing the connectivity agent, you must restart the agent.

    See Restart the Agent.

  7. Modify InstallerProfile.cfg to include the following information:
    # Required Parameters
    # oic_URL format should be https://hostname:sslPort
    oic_URL=https://oic_host:ssl_port
    agent_GROUP_IDENTIFIER=
    
    #Optional Parameters
    oic_USER=
    oic_PASSWORD=
    
    #Proxy Parameters
    proxy_HOST=
    proxy_PORT=
    proxy_USER=
    proxy_PASSWORD=
    proxy_NON_PROXY_HOSTS=
    

    Where:

    Parameter Description
    oic_URL This parameter is required. This is the HTTPS URL for the Oracle Integration host. The port is 443.
    agent_GROUP_IDENTIFIER This parameter is required. This is the identifier for the connectivity agent group created in Oracle Integration. The identifier name is case sensitive.

    See Create an Agent Group.

    oic_USER This optional parameter provides the Oracle Integration user name. When the agent runs for the first time, this field, if provided, is encrypted in the properties file. If this field is not provided, you are prompted to enter the user name at agent startup and it is not persisted. See What Users Can Do in the Integrations Design Section by Role of Provisioning and Administering Oracle Integration and Oracle Integration for SaaS, Generation 2. The connectivity agent only supports basic authentication. You cannot use Oracle Cloud Infrastructure API key or OAuth parameters.
    oic_PASSWORD This optional parameter provides the Oracle Integration password. When the agent runs for the first time, this field, if provided, is encrypted in the properties file. If this field is not provided, you are prompted to enter the password at agent startup and it is not persisted.
    Proxy Parameters These parameters are only required if the connectivity agent is used with a proxy in the on-premises environment.
    • If you have multiple hosts that must be configured in a nonproxy host environment, you must separate each IP address or host with a pipe symbol (|) in the proxy_NON_PROXY_HOSTS parameter. For example:
      proxy_NON_PROXY_HOSTS=localhost|127.0.0.1|*.myorg.com
    • If you use a proxy user for Windows, the user name must include the MS domain name in front of the user name, along with double backslashes before the user name (for example, MS_domain\\username). If you do not specify the double backslashes, you receive a 407 Proxy Authentication Required error.
  8. Set the JAVA_HOME property to the location of the JDK installation.

  9. Set the PATH property. For example, if csh is your shell:
    setenv PATH = $JAVA_HOME/bin:$PATH
  10. Run the connectivity agent installer from the command prompt. If you want to copy and paste this command, ensure that it does not have any special characters.

    java –jar connectivityagent.jar
  11. Provide the Oracle Integration credentials when prompted.
    Proceeding to install a new agent ...
    Enter your OIC username : 
    Enter password for username : 
  12. Wait for a successful installation message to appear.
    Done with Agent installation & configuration... Starting agent for message processing.
    Agent started successfully... listening for new messages... 

    If errors occur, review the agent diagnostic logs.

    See Monitor Agents.

  13. Depending on your agent environment, you may also need to install a certificate.

    See Install a Certificate on the Agent Host.

Install a Certificate on the Agent Host

If you need to add a certificate on the agent host, use the keytool to import the certificate in keystore.jks. Installing the certificate enables you to access hosts with self-signed certificates. It is not normally needed.

Note:

If you install a certificate after installing the connectivity agent, you must restart the agent.

See Restart the Agent.

Scenarios under which you need to import the certificate in the agent keystore are as follows:
  • The connectivity agent is used with an SSL proxy.

  • The connectivity agent is used to invoke secure (SSL) on-premises endpoints.

  1. Go to the agenthome/agent/cert/ directory. (keystore.jks is available here).

  2. Run the following command:
    keytool -importcert -keystore keystore.jks -storepass password -alias alias_name -noprompt -file certificate_file

    Where:

    • -storepass password: The default, initial password for the agent keystore. Refer to your keytool documentation for the default storepass password. See keytool.
    • -alias alias_name: Any name to uniquely identify the imported certificate in the keystore.
    • -file certificate_file: Absolute path of the certificate file.

Run the Connectivity Agent Installer as a Background Process on Linux Systems

When you run the connectivity agent installer (using java -jar connectivityagent.jar), the process is tied to the terminal window in which you are working and ends when the window is closed. If you want to run the process in the background, use one of the following options:

Run the Connectivity Agent Installer as a Background Process

  1. Update InstallerProfile.cfg with oic_USER and oic_PASSWORD values and then use nohup to run the agent process. For example:
    nohup java -jar connectivityagent.jar &

Or

  1. If you do not want to expose the password in InstallerProfile.cfg, perform the following steps:

    1. Enter java -jar connectivityagent.jar at the command prompt.

    2. Enter the username and password when prompted.

    3. Enter Ctrl+Z to suspend the process.

    4. Enter bg (to run the process in the background).

    5. Enter jobs to get the jobid.

    6. Enter disown -a %jobid (from Step e) to disassociate the process from the owning shell.

Connectivity Agent Cannot Be Run as a Service on Windows

Running the connectivity agent as a service on Windows is not supported. You must be logged in to the Windows host. Otherwise, the agent stops working when you log off. Consider the following recommended options.
  1. Create a new service account on Windows.
  2. Use that account to log in to the Windows host and remain logged in with that account.
  3. Install the connectivity agent on the Windows host.
  4. Use that agent to communicate with the MS SQL Server or other endpoints accessed on Windows.
or
  1. Instead of installing the connectivity agent on a Windows host, install it on a Linux virtual machine that has access to the Windows systems with which that agent must interact.