Downloading and Running the On-Premises Agent Installer

You must download the agent installer from Oracle Integration Cloud Service and run the installer to install the on-premises agent in your local environment. During installation, you associate the agent with the agent group identifier you generated in Oracle Integration Cloud Service. After completing on-premises agent installation, you must apply a patch.

System Requirements

You must satisfy the following prerequisites on your on-premises host before running the agent installer in a production environment:

  • Ensure that you have created the agent group. You must specify the agent group identifier when installing the on-premises agent. For information, see Creating an Agent Group.

  • Install JRE version 1.7 or higher.

  • Set the JAVA_HOME property to the location of the JDK installation. For example:

  • Install the on-premises agent on Linux OEL version 5 or 6 only.

  • 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 greater than 8 GB.

  • Set the number of worker threads to a value appropriate to your environment. By default, the on-premises agent is set to 3. This may be sufficient for some low-load environments and most demo environments. However, for high-load environments, the agent instance may need additional tuning. Increase concurrency on the on-premises agent installation host by setting agentWorkerThreads to a recommended value of 40 in the file. This change requires an agent restart.


    For information about editing this file, see Updating Property Values.

  • Do not install the on-premises agent in an environment that includes an existing Oracle WebLogic Server installation.


To download and run the on-premises agent installer:


It is recommended that you retain a copy of the cloud-connectivity-agent-installer.bsx agent installer file after completing installation.
  1. Log in to Oracle Integration Cloud Service.

  2. In the Integration Cloud Service toolbar, click Designer.

  3. On the Designer Portal, click Agents.

    The Agent Groups page is displayed. This page shows any current agent groups and on-premises agents associated with the agent groups.
    Description of GUID-CA56DDEA-B243-4A84-A0D1-89ACEB01483D-default.png follows
    Description of the illustration GUID-CA56DDEA-B243-4A84-A0D1-89ACEB01483D-default.png

  4. Click Download Agent Installer.

  5. Select Connectivity Agent.

    This selection enables you to integrate Oracle Integration Cloud Service with on-premises environments.

  6. Select Save File when prompted to save the file to a directory location on your on-premises host.

  7. Unzip the downloaded file.

  8. Locate the cloud-connectivity-agent-installer.bsx agent installer file.

  9. Change the file permissions to be executable.
    chmod +x cloud-connectivity-agent-installer.bsx
  10. Execute the file with the following properties specified. Do not install the on-premises agent in a directory path that includes /tmp. Note the use of the dash (-) when specifying the property value. The output of this command is displayed on-screen. For troubleshooting purposes, you can also redirect the output to an output file.

    ./cloud-connectivity-agent-installer.bsx —h= —u=weblogic —p=my_password —ad=agent_group_identifier
    Parameter Status Description Additional Notes
    -h Required Specifies the Oracle Integration Cloud Service hostname and port. As an example, when installing from your Oracle Integration Cloud Service POD, the host and port you specify are typically the Oracle Integration Cloud Service URL (for example,

    Note the following issues:

    • Do not specify /ics after the port number.

    • If you forget to specify a port, you receive the following error:

      Numberformat Exception
    • If you specify port 80 with the https protocol, you can receive the following error:

      Outbound ProxyHost and ProxyPort as not provided  certPath --- 
      /home/oracle/host/downloads/ics_conn_agent_installer_151110.1158/keystore.jks Read timed out                 
         at Method)                 
         . . . 
         . . .
    -u Required Specifies the Oracle Integration Cloud Service user name.  
    -p Required Specifies the Oracle Integration Cloud Service password. Note:
    • Some special characters must be properly escaped with a backslash (\) character. For example, if your password includes an exclamation character, you must enter the backslash character before the exclamation character (\!).

    • If the password contains a dollar sign ($) character (for example, W$lcome11), the complete password value must be contained in single quotes (for example, -p='W$lcome11'). Otherwise, you receive an Undefined variable error when you run the agent installer command.

    -ad Required Specifies the agent group identifier that was generated in the Identifier field when you created the agent group in the New Agent Group - Information dialog in Creating an Agent Group. You must create the agent group before you can install the on-premises agent.  
    -ph Optional Specifies the outbound proxy hostname. If your on-premises host includes a proxy server, you must specify this property. The agent can work with any proxy in the DMZ.
    -pp Optional Specifies the outbound proxy hostname port. If your on-premises host includes a proxy server, you must specify this property.
    During installation, the following tasks are performed:
    • All on-premises adapters are registered.

    • Oracle WebLogic Server and a Java database are installed.

    • The Oracle WebLogic Server and JRF domain is created.

    • The on-premises agent is deployed.

    Once installation is complete, an agent instance is created for interacting with Oracle Integration Cloud Service. You can verify that the agent instance was created by going to the Agent Groups page and noting that the agent count was increased by one. If you click the number, details about the agent are displayed. For more information, see Viewing and Editing Agent Groups.

Troubleshooting Issues

  • If there is a Derby database (DB) already in use on the host on which the agent is being installed, you receive the following error:

    2016-01-27 20:48:51,714 FINE  [47] - 
    prop str: user=dummy;portNumber=1527;databaseName=dummy;create=true;serverName=localhost 
    url: jdbc:derby://localhost:1527/dummy;ServerName=localhost;databaseName=dummy 
    2016-01-27 20:48:51,714 FINE  [47] - 
    Selected DB ID/CAT: DerbyDerby's Driver (Type 4) Versions:Any 2016-01-27 20:48:51,714 FINE  
    [47] - Selected DB vendor: Derby 
    2016-01-27 20:48:51,714 FINE  [47] - 
    adding normal datasource: opss-data-source 2016-01-27 20:48:51,714 FINE  [47] - datasource: opss-data-source component 
    name: OPSS Schema
    . . .
    . . .
    Perform the following steps:
    1. Check if the Derby database is running.

      ps -ef | grep "derby"
    2. If any processes are displayed, run the following command to terminate them:

      ps -ef | grep "derby" | awk '{print $2}' | xargs kill -9
  • At the end of on-premises agent installation, the following message is displayed:

    Agent installation completed Successfully. 
    Agent Instance creation successful

    After this message is displayed, you may receive the following error message that can be safely ignored. On-premises agent installation was successful. This issue occurs during KSS store creation. If KSS store creation is required, you can manually perform this task at a later time.

    javax.naming.AuthenticationException: User: [...], failed 
    to be authenticated. [Root exception is java.lang.SecurityException: User:
    ..., failed to be authenticated.]
    Problem invoking WLST - Traceback (innermost last):
    ts/", line 45, in ?
    File "<iostream>" line 19, in connect
    File "<iostream>" line 552, in raiseWLSTException
    WLSTException WLSTException: Error occurred while performing connect : User:
    ..., failed to be authenticated. : User:
    ..., failed to be authenticated.
    Use dumpStack() to view the full stacktrace : 
You are now ready to create an adapter connection in Oracle Integration Cloud Service that uses the on-premises agent. See ..