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:

In the left navigation pane, click Home > Integrations > Agents.
Click Create Agent Group.

The Create New Agent Group is displayed.

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.

Understand the JDK Version, Operating System, and Heap Size Requirements

Install and use JDK version 17.
Note:
To comply with Oracle security standards, JDK 8 and JDK 11 are being deprecated for use with the on-premises connectivity agent. You must upgrade to JDK 17 as soon as possible and convert the JKS keystore to the PKCS12 keystore at the same time. See Complete Upgrade Prerequisites in Provisioning and Administering Oracle Integration 3.
Note the following key deadlines:
- Support for the connectivity agent on JDK 8 and JDK 11 ends on December 31, 2023. If you continue to use either version, you no longer receive quarterly updates for the connectivity agent and support for any submitted service requests that involve the connectivity agent.
- Some services that depend on the connectivity agent may not function properly after January 15, 2024. This means that connectivity agent traffic on JDK 8 and JDK 11 may be blocked by Oracle.
The new announcements banner on the Home page also provides information about the JDK 8 and 11 deprecation.
Note:
The announcement banner does not disappear after upgrading to JDK 17 and the PKCS12 keystore. To dismiss the banner:

In the navigation pane, click Settings, then Upgrade.

Run the upgrade eligibility program regardless of whether you are preparing to upgrade.
The banner goes away shortly.
Note the following details:
- There are JDK 11 and JDK 17 restrictions when using the Oracle WebLogic JMS Adapter. See Connectivity Agent Restrictions.
- If you are using JDK 8 with the connectivity agent, ensure that JDK 8 includes the latest updates. After applying these updates, restart the agent. Certificates in older versions of JDK 8 can expire, which causes connectivity issues for the agent.
  Move to JDK 17. JDK 17 is the minimum version required for upgrading the agent from Oracle Integration Generation 2 to Oracle Integration 3. Customers should plan to uptake the latest JDK patches periodically after they move to JDK 17.
- You do not need to purchase a JDK license. See JDK license and support for OIC Connectivity Agent (Doc ID 2611142.1).
- 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.
Install the connectivity agent on one of the following certified operating systems:
- Oracle Linux 6.x
- Oracle Linux 7.x
- Oracle Linux 8.x
- 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.

Ensure the Connectivity Agent Version is Compatible with JDK 17

Run the following command from the agenthome directory to determine if the connectivity agent is compatible with JDK 17. The following minimum version on Oracle Integration Generation 2 is required for JDK 17 compatibility.

$ cat version
230505.0528.4033

If you receive the following error when starting the connectivity agent after upgrading to JDK 17, you are not running a compatible version of the connectivity agent:

Agent is only supported on Java version 8 or 11. Please set JAVA_HOME and PATH to the location
for Java (JDK 8 or 11). This error occurs because you are using an older version of the connectivity agent.

You may be running an older version of the connectivity agent for the following reasons:

Previous attempts to upgrade the connectivity agent failed
You started the agent with the following option:
```
-DenableAutoUpgrade=false
```

To resolve this issue:

Start the connectivity agent once with your previous JDK version (JDK 8 or JDK 11).
Wait for the connectivity agent upgrade to finish. You can monitor upgrade in the agenthome/logs/agent-upgrade.log file.
Stop the connectivity agent.
Restart the connectivity agent with JDK 17.

Upgrade the Existing JDK 8 or JDK 11 Agent to the JDK 17 Agent

Install JDK 17.
Stop the existing connectivity agent.
Set JAVA_HOME and PATH to JDK17.
Restart the connectivity agent.

Revert Back to the JDK 8 or JDK 11 Agent in Case of Issues

Stop the connectivity agent.
Set JAVA_HOME and PATH to JDK8 or JDK11.
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 and JDK 17 are 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 role to download the agent.
See What Users Can Do in the Integrations Design Section by Role of Provisioning and Administering Oracle Integration Generation 2.

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.
In the left navigation pane, click Home > Integrations, then click Agents.
Click Download > Connectivity Agent.
Download the connectivity agent installer to the directory on your on-premises host.
Unzip oic_connectivity_agent.zip.
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.

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 Generation 2. The connectivity agent 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.

Set the JAVA_HOME property to the location of the JDK installation.
Set the PATH property. For example, if csh is your shell:
```
setenv PATH = $JAVA_HOME/bin:$PATH
```
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
```

Provide the Oracle Integration credentials when prompted.

Proceeding to install a new agent ...
Enter your OIC username : 
Enter password for username :

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.

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.

Go to the agenthome/agent/cert/ directory. (keystore.jks is available here).
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

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 &
```

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.

Create a new service account on Windows.
Use that account to log in to the Windows host and remain logged in with that account.
Install the connectivity agent on the Windows host.
Use that agent to communicate with the MS SQL Server or other endpoints accessed on Windows.

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.