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. Creating the agent group automatically creates an OAuth client application in Oracle Identity Cloud Service. This enables the connectivity agent to use OAuth 2.0 token-based authentication when invoking Oracle Integration endpoints. Basic authentication is not supported in Oracle Integration 3. 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.
What to Know About OAuth 2.0 Token-Based Authentication Support
OAuth 2.0 token-based authentication is more secure and Oracle Integration 3 connectivity agent configuration is simpler than in Oracle Integration Generation 2.
- You must allow egress from the agent network to Oracle Integration design-time and runtime and the Oracle Identity Cloud Service or identity domain.
- The Service Gateway on the Oracle VCN provides access to Oracle Integration, Oracle Identity Cloud Service, and identity domains in the same region as the connectivity agent. See Access to Oracle Services: Service Gateway.
- The Service Gateway on the Oracle VCN does not provide access to Oracle Integration, Oracle Identity Cloud Service, and identity domains in a different region than the connectivity agent; this type of access requires the NAT Gateway. See NAT Gateway.
Create an Agent Group
Creating the agent group also creates the necessary artifacts required for message exchange. You can edit the connection name after creation.
-
In the navigation pane, click Design, then Agents.
-
Click Create.
The Create agent group panel opens.
-
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, the identifier value is automatically included in the
InstallerProfile.cfg
file.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.
Description
Provide a meaningful description so that others can understand the responsibilities of the agent group.
This action automatically creates an OAuth client application in Oracle Identity Cloud Service. The application name takes the following form:agent_group_name-instance_IDCS_name
This enables the connectivity agent to use OAuth 2.0 token-based authentication when invoking endpoints. In Oracle Integration 3, each agent group has its own OAuth client application.
-
System Requirements
Satisfy the following system requirements before installing the on-premises connectivity agent.
Connectivity Agent Prerequisites
- Allowlist the Oracle Integration runtime and design-time IP addresses and the Oracle Identity Cloud Service IP address to install the connectivity agent.
-
Install and use JDK version 17.
You do not need to purchase a JDK license for the sole purpose of installing and/or running the connectivity agent. See JDK license and support for OIC Connectivity Agent (Doc ID 2611142.1).
The JDK installation can be the same one as used with other products installed on the same host. However, separate JDK licensing may be required for any use of Java beyond the use of the connectivity agent. 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:
- The connectivity agent is not certified on Kubernetes (K8s).
- IBM or Open JDK are not supported.
-
-
Provide a minimum of 8 GB memory with 4 GB of heap size dedicated for the connectivity 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
agenthome
directory
to determine if the connectivity agent is compatible with JDK 17. The following
minimum version on Oracle Integration 3 is required
for JDK 17
compatibility.$ cat version
20230613.0926.318
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.
- Previous attempts to upgrade the connectivity agent failed
- You started the agent with the following
option:
-DenableAutoUpgrade=false
- 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 11 Agent to the JDK 17 Agent
If you need to upgrade from JDK 11, perform the following steps.
- Install JDK 17.
- Stop the existing connectivity agent.
- Set
JAVA_HOME
andPATH
toJDK17
. - 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:
- Enter the Oracle WebLogic Server
URL. For
example:
http://abcweblogic.oracle.com:7001/console
- At the bottom left, find the
version. For
example:
WebLogic Server Version: 12.2.1.4.0
- Enter the Oracle WebLogic Server
URL. For
example:
- 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
Download 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. Ensure that you restrict access to the folder in which you install the connectivity agent to only those users who need to stop and start the agent.
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 3.
-
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
. 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.
- Do not install the agent in a directory path that includes
-
In the navigation pane, click Design, then Agents.
-
Click Download, then Connectivity Agent.
-
Download the connectivity agent installer to a directory on your on-premises host.
-
Extract
oic_conn_agent_installer.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 Connectivity Agent. - Hover over the agent group.
- Click Actions
, then select Download config.
This step downloads a preconfigured
InstallerProfile.cfg
file to use during installation. The following message is displayed.BootStrap configuration downloaded for Agent Group agent_group_name. Replace the file in agent install location before proceeding with agent setup.
- Replace the existing
InstallerProfile.cfg
template file in theoic_conn_agent_installer
directory that was created when you extracted the agent installation file in Step 5 with the preconfiguredInstallerProfile.cfg
file you downloaded in Step 7.The preconfigured
InstallerProfile.cfg
file automatically includes values for all required parameters such asoic_URL
andagent_GROUP_IDENTIFIER
and OAuth 2.0 token-based authentication parameters such as client ID, client secret, and scope. This eliminates the need to manually specify values for these parameters.- Optionally set proxy parameter values. 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 theproxy_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 a407 Proxy Authentication Required
error.
-
Set the
JAVA_HOME
property to the location of the JDK installation. -
Set the
PATH
property. For example, ifcsh
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
-
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...
The agent group associated with this connectivity agent now has its own
InstallerProfile.cfg
file and OAuth client application in Oracle Identity Cloud Service. If you delete the agent group, the OAuth client application is also deleted in Oracle Identity Cloud Service.If errors occur, review the agent diagnostic logs.
See Monitor Agents.
-
Depending on your agent environment, you may also need to install a certificate.
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.p12
.
Installing the certificate enables you to access hosts with self-signed certificates. A
certificate is not typically needed.
Note:
If you install a certificate after installing the connectivity agent, you must restart the agent.-
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.p12
is available here). -
Run the following command:
keytool -importcert -keystore keystore.p12 -storepass password -alias alias_name -noprompt -file certificate_file -trustcacerts
Where:
-storepass password
: The default, initial password for the agent keystore. Refer to yourkeytool
documentation for the defaultstorepass
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
-
Run the agent process. For example:
nohup java -jar connectivityagent.jar &
Or
-
If you do not want to expose the password in
InstallerProfile.cfg
, perform the following steps:-
Enter
java -jar connectivityagent.jar
at the command prompt. -
Enter the user name and password when prompted.
-
Enter
Ctrl+Z
to suspend the process. -
Enter
bg
(to run the process in the background). -
Enter
jobs
to get thejobid
. -
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
- 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.