Best Practices from Oracle Development's A‑Team

Integration Cloud Service (ICS) On-Premise Agent Installation

Greg Mally
Consulting Solutions Architect

The Oracle On-Premises Agent (aka, Connectivity Agent) is necessary for Oracle ICS to communicate to on-premise resources without the need for firewall configurations or VPN. Additional details about the Agent can be found under New Agent Simplifies Cloud to On-premises Integration. The purpose of this A-Team blog is to give a consolidated and simplified flow of what is needed to install the agent and provide a foundation for other blogs (e.g., E-Business Suite Integration with Integration Cloud Service and DB Adapter). For the detailed online documentation for the On-Premises Agent, see Managing Agent Groups and the On-Premises Agent.

On-Premises Agent Installation

The high-level steps for getting the On-Premises Agent installed on your production POD consist of two activities: 1. Create an Agent Group in the ICS console, and 2. Run the On-Premises Agent installer. Step 2 will be done on an on-premise Linux machine and the end result will be a lightweight WebLogic server instance that will be running on port 7001 (or a port of your choosing using the -aport option).

Create an Agent Group

1. Login to the production ICS console and view landing page.
2. Verify that the ICS version is 17.3.3 or greater.
3. Scroll down on ICS Home page and select Create Agents OR use the menu in the upper left-hand corner of the window and navigate to Agents. Notice this brings you to the Agents page of the Designer section.
- OR -
4. On the Agents page click on Create New Agent Group.
5. Provide a name for your agent group (e.g., AGENT_GROUP).
6. Review the Agent page containing new group.

Run the On-Premises Agent Installer

1. Click on the Download drop down on the Agents page, select Connectivity Agent, and save file to an on-premise Linux machine where the agent will be installed/running. This Linux machine needs to be able to establish a non-proxied TCP/IP connection to the on-premises resource(s) it will be communicating with.
2. Extract the contents of the zip file for the cloud-connectivity-agent-installer.bsx. This .bsx is the installation script that will be executed in the on-premise machine where the agent will reside. A .bsx is a self extracting Linux bash script:
NOTE: ICS 17.2.5 includes one additional file within the zip file: cloud-connectivity-agent-patcher.zip. If you are doing a new/clean install, you can ignore this file. However, if you have an existing agent installation then the files in this .zip are of interest to you. See Upgrading the On-Premises Agent to Release 17.2.5 for more details.
3. Make sure the cloud-connectivity-agent-installer.bsx file is executable (e.g., chmod +x cloud-connectivity-agent-installer.bsx) and execute the shell script. NOTE: It is important to specify the SSL port (443) as part of the host URL. Also, there are optional properties for the proxy details if a proxy is required for your network. For example:
./cloud-connectivity-agent-installer.bsx -h=https://<ICS_HOST>:443 -u=[username] -p=[password] -au=weblogic -ap=welcome1 -ad=AGENT_GROUP -ph=<PROXY_HOST> -pp=<PROXY_PORT> -pu=<PROXY_USERNAME> -ppw=<PROXY_PASSWORD>

Special Characters: At times you may have special characters in user names and/or passwords.  If you use any of the following, it's best to escape the character with a backslash (\) on the command-line: ;'"`#$&*?[]<>{}\ including white space and sometimes !^%

Proxy Authentication: When proxy authentication is required, it is important to understand that the WebLogic http client only supports BASIC authentication for the proxy.  If there is an "Auth scheme NEGOTIATE is not supported!" error in the agent logs during startup, then the proxy is not setup for BASIC authentication.  When this happens there are three options available:

1. Allow the agent server to be pre-authorized/trusted for the proxy.
2. Add the two URLs located in the $AGENT_HOME/user_projects/domains/agent-domain/agent/config/CpiAgent.properties on the do not authenticate list.
3. Configure the proxy to allow BASIC authentication.

16.1.5+: A new property was added (-aport) that allows an option to change the default 7001 port at the time of running .bsx file. If not specified, it will default to the out-of-the-box value of 7001. The format for using this optional property is: -aport=[port number], for example -aport=7101

16.2.1+: Two new REQUIRED properties were introduced (-au & -ap) that allow control over the administrator user name and password.  Prior to these new properties the default was weblogic/welcome1. Now it is up to the installer what the administrator name and password will be.

16.3.3+: A new property was introduced (-profile) that allows you to change the number of worker threads for the agent process.  The values for this property are DEMO (3 threads) or PROD (40 threads). This will change the default value of agentWorkerThreads= in the $AGENT_HOME/user_projects/domains/agent-domain/agent/config/CpiAgent.properties file.

For details about what command-line options are available, simply specify the --help option:
This is what the agent installer looks like when started from the command-line:


4. Return to the ICS console and the Agents configuration page. Notice that the number of Agent(s) has changed from 0 to 1:
5. Review the Agent Group.
6. Navigate to the Monitoring page via the menu in the upper left-hand corner and select the Agents.
7. Review the Agent monitoring landing page. Notice there is now a green icon indicating the agent is up and running:
8. Review the directory structure for the agent installation.
As you can see this is a standard WLS installation. The agent server is a single-server configuration where everything is targeted to the Admin server and is listening on port 7001 (if the default has not been overridden). Notice that the installer included scripts for starting and stopping the agent located in the same directory as the agenthome. It is very important to always use the startAgent.sh script for starting the server, because includes environment settings specific to the agent:


We are now ready to leverage the agent for things like the Database or EBS Cloud Adapter.





Join the discussion

Comments ( 1 )
  • Alberto Hideki Konno Tuesday, August 13, 2019
    Hi A-Team. Nice post.
    I'm curious about logs and monitoring of the ICS Agent.
    How would be an ideal approach for this task?
    A log view of the console messages would be great also.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha