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 role to download the agent.

    See Grant Access and Secure of Administering Oracle Integration.

  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 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:
    • 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 username. 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 username at agent startup and it is not persisted.
    • 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.

  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:

    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 or otherwise invalid 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.

Use the Agent in High Availability Environments

You can use the connectivity agent in high availability environments. You install the connectivity agent twice on different hosts. There are no differences in agent installation. You specify the same agent group identifier during both installations.

Note the following details:

  • The File Adapter is not supported in high availability environments. When using the File Adapter and some groups have multiple instances, use a dedicated agent group (with one agent only).
  • Any new agent group created is enabled for high availability. Existing agent groups created prior to high availability being supported have no high availability capabilities and cannot be used.

  • You cannot have more than two agent instances per agent group. Attempting to include a third agent instance in the same group during installation results in an error.

  • While you can install up to two agent instances per agent group, be aware of the current restriction with agent high availability when working in tandem with automatically upgraded agents. To ensure that both agent instances do not upgrade at the exact same time, it is recommended that you start each instance with a small time gap. The time gap can be as little as 10 minutes. This ensures that there is no outage due to both agent instances being upgraded at the same time.
  • Ensure that both agent instances can access the same endpoints. For example, agent 1 on host 1 and agent 2 on host 2 must both be able to access the same endpoint (for example, a Siebel system).

  • Both hosts on which the agent is installed must have the same network setup.

  • To enable an older agent integration for high availability, you must create a new group, update the adapter connections in the integration to refer to the new group, and re-activate the integration.

  • You can install multiple agents on the same host. However, to utilize high availability capabilities, install the second agent on a second host.

  • Create a horizontal cluster to achieve high availability. Installing the agent on the same virtual machine (VM) does not guarantee high availability.

  1. Create a new agent group. You cannot use an existing group.

  2. Download and install the first agent on one host. Ensure that you specify the agent group identifier of the new agent group.

    See Download and Install the Agent.

  3. Follow the same steps to download and install the second agent on a second host. That way, if one host goes down, agent processing continues running on the other host.
    • Use the same JAR file that you downloaded for the first installation.

    • Use the same InstallerProfile.cfg file settings. You can also copy the file from one host to the other.

    Note:

    Specify the same agent group identifier and Oracle Integration URL in the InstallerProfile.cfg file as with the first installation.
  4. After installation completes, go to the Agents page and note that two agents are associated with the same agent group.


    Description of agent_groups_ha.png follows
    Description of the illustration agent_groups_ha.png
  5. Go to the Monitor Agents page and note the same information. In this case, both agent instances are running.
    Description of agent_groups_mon_ha.png follows
    Description of the illustration agent_groups_mon_ha.png

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.

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.