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 when creating an agent group in Oracle Integration Cloud Service.

To upgrade the on-premises agent to the latest release, see Upgrading the On-Premises Agent. To learn more about on-premises agent concepts, see About Connectivity Agents and Integrations Between On-Premises Applications and Oracle Integration Cloud Service.

System Requirements and Restrictions


Any request processed through the connectivity agent is slightly impacted by agent processing time. This add-on time is higher in an idle environment (low load, infrequent message processing) and is minimal when the system is at peak load and processing continuous messages. When low load or infrequent message processing is the case, any interaction modeled as a synchronous request/response (using the agent) can be impacted by this processing add-on time.

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

  • Do not make any custom configuration changes to the agent installed in your environment using the Oracle WebLogic Server Administration Console. These changes may cause issues during agent upgrade and are not supported. Oracle is not responsible for any custom changes that you may make.

  • Do not have two on-premises agents running on the same host.

  • If you have other Oracle WebLogic Server domains running on the host, they must not interfere with the Derby database used by the on-premises agent.

  • You cannot copy the agent directory hierarchy that is installed on one host to another host. You must directly install the connectivity agent on your host using the connectivity agent installer described in this section.

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

  • Install only Oracle JDK version 1.7 or 1.8. Other JDKs such as Open JDK are not supported.

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

  • Set the PATH property. For example:

  • Install the on-premises agent on one of the following supported operating systems:

    • Linux OEL version 6 or 7

    • Red Hat Enterprise Linux Server release 6.x (where x is release 6.6 and higher) (Santiago)

    • SUSE Linux Enterprise Server 12 SP1

  • 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 that a Derby database is not running. See the Troubleshooting section below for details.

  • Provide the fully-qualified domain name (FQDN) for the agent host in the local /etc/hosts file.

Installing the On-Premises Agent

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. On the Oracle Integration Cloud Service home page, click Agents.

    The Agent Groups page is displayed. This page shows any current agent groups and on-premises agents associated with the agent groups.

  2. Click Download.

  3. Select Connectivity Agent.

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

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

  5. Unzip the downloaded file.

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

  7. Change the file permissions to be executable.
    chmod +x cloud-connectivity-agent-installer.bsx
  8. Execute the file with the following properties.


    Ensure that you understand the following issues:
    • Do not forget the agent username (-au) and agent password (-ap) if you specify them during installation. The same values are required when upgrading the on-premises agent to newer versions. If you forget the supplied parameters, a re-installation of the on-premises agent may be required because upgrading the on-premises agent is not possible. However, if these parameters are not supplied during installation, the default username is weblogic. Contact Oracle Support Services to obtain the default password for weblogic.

    • 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, the installation logs are generated and available at the same location as the BSX file. You can also redirect the output to an output file.

    ./cloud-connectivity-agent-installer.bsx —h= —u=username —p=my_password —ad=agent_group_identifier -au=agent_username -ap=agent_password
    Parameter Status Description Additional Notes
    -h Required Specify 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 Specify the Oracle Integration Cloud Service user name.  
    -p Required Specify 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 Specify 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.  
    -au Optional Specify a new agent username. This is a new username used to initialize the local installation of the on-premises agent. If not specified, the default username of weblogic is used.  
    -ap Optional Specify a password for the new agent username. If not specified, the default password is used. You may need to contact Oracle Support Services to obtain the default password for the default user weblogic.  
    —aport Optional Specify the agent port (for example, 9002). This enables you to specify any available port outside of the default value of 7001. If not specified, it defaults to 7001. Any free port can be used.  
    -ph Optional Specify the hostname, or address, of the proxy server.

    A proxy server allows indirect connection to network services and is used mainly for security (to get through firewalls) and performance reasons (proxies often provide caching mechanisms). The -ph and -pp properties are only required if your on-premises environment is set up with a proxy server mandating that all connections be routed through it.

    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

    Specify the port number of the proxy server.

    If your on-premises host includes a proxy server, you must specify this parameter.
    -pu Optional

    Specify the proxy server user.

    -ppw Optional

    Specify the proxy server user password.

    —nphosts Optional

    Specify the nonproxy hosts:-nphosts=NONPROXYHOSTS. You can specify a single host or multiple hosts separated by a |.|
    -profile Optional Set the number of worker threads to a value appropriate to your environment.
    • PROD: When -profile PROD is specified, the agentWorkerThreads property value is set to 40 in the file. This setting is optimal for high-load environments. When -profile —PROD is not specified, the agentWorkerThreads property value also defaults to 40.

    • DEMO: When -profile DEMO is specified, the agentWorkerThreads property is set to 3.

    A value of 3 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 host by specifying the -profile PROD property during installation. This automatically sets the number of worker threads to 40 (the recommended value for high-load environments).

    You can also specify this value in the file after installation. This change requires an agent restart.


    See Updating Property Values.

    During installation, the following tasks are performed:
    • All on-premises adapters are registered.

    • A Java database is installed.

    • The 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. See Viewing and Editing Agent Groups.

You are now ready to create an adapter connection in Oracle Integration Cloud Service that uses the on-premises agent. See Creating a Connection with an Agent Group.


Do not use and to start and stop the on-premises agent. Instead, use and

Importing the Oracle Integration Cloud Service Certificate to the Agent KSS Store

The on-premises agent uses the KSS key store for runtime invocations. To import an Oracle Integration Cloud Service certificate into the on-premises agent KSS store, execute the following script after installing the agent. This script is provided with the connectivity agent ZIP file that you download:
 -u agent_user_name -p password -c fully_qualified_certPath 
-h agent_host_name -t port_number -a alias

Troubleshooting Issues

  • The following error can occur if you specify undocumented parameters during agent installation.
    Agent Registration REST call Failed
    Response from rest service -- Agent Instance creation REST Srevice expects
    the following arguments { String restURI, String username, String password,
    String id, String name, String agentDefinition, String version }

    Ensure that you run the installer with the documented parameters. If you specify the -inst parameter as part of agent install, this error can occur. This parameter is optional and can be safely ignored. Re-run the installer without this parameter.

  • If you receive the following error during agent runtime message processing:

    Caused By: javax.persistence.PersistenceException: Exception
    [EclipseLink-7060] (Eclipse Persistence Services - 2.6.4.v20160829-44060b6):
    Exception Description: Cannot acquire data source
    Internal Exception: javax.naming.NameNotFoundException: Unable to resolve
    'jdbc.SOALocalTxDataSource'. Resolved 'jdbc'; remaining name

    As a workaround, ensure that you click Test on the Connections page for any of the on-premises adapter connections serviced by that agent. After performing this step, the runtime message processing error stops and message processing resumes.

  • If you attempt to restart the agent after previously having no problems and receive the following error, check to see if the certificate matches the one that was used to install the agent.
    Agent Group Existence Check Failed, Recheck ICS Username, ICS Password and Proxy Username, Proxy Password or Contact Customer Support
    If the JKS store certificate has changed, validation fails and the agent cannot be restarted. Re-import the certificate to resolve this issue:
    1. In the file, check line 63 for the key store path. For example:

    2. Back up the keystore.

    3. Download the Oracle Integration Cloud Service certificates to the host where the agent is running.

      1. Log in to Oracle Integration Cloud Service.

      2. In a Firefox browser, click the secure link to the left of the HTTPS URL.

      3. Click Secure Connection > More Information > Security > View Certificate > Details.

      4. Click Export and save the file with a .crt extension and as type X.509 Certificate with chain (PEM) (*.crt,*.pem).

    4. Import the entire certificate chain from Oracle Integration Cloud Service as follows:

      keytool -import -trustcacerts -keystore  Agent_Home/cert/keystore.jks -file certificate.crt -alias
      You can also individually download and import the certificates in the chain. For example:
      keytool -import -trustcacerts -keystore
      Agent_Home/cert/keystore.jks -file
      /tmp/certificate_file_name -alias alias_name
      keytool -import -trustcacerts -keystore
      Agent_Home/cert/keystore.jks -file
      /tmp/certificate_file_name -alias
      keytool -import -trustcacerts -keystore
      Agent_Home/cert/keystore.jks -file
      /tmp/certificate_file_name -alias

      You must download the certificates from the browser after logging in to Oracle Integration Cloud Service.

  • If you do not provide the fully-qualified domain name (FQDN) for the agent host in the local /etc/hosts file, installation is unsuccessful and you receive the following error: Fail to find default JPS Context in
  • If the time zone is not set on the on-premises agent host, you can receive the following database connection error:

    ORA-01882: timezone region not found
    If this occurs, set the Java VM time zone property on the host on which the on-premises agent is installed. For example:
  • 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
  • If you install the agent with a proxy server and frequently receive the following stuck thread stack trace errors, you require patch 20440467. Contact Oracle Support Services for details.

    Agent stuck thread stack trace:
     java.lang.Thread.State: RUNNABLE
    at Method)
    - locked <0x00000006cb9a01a8> (a$2)
    - locked <0x00000006cb9a0198> (a java.util.Collections$UnmodifiableSet)
    - locked <0x00000006cb9a0020> (a
    . . .
    . . .

Deinstalling the On-Premises Agent

If you need to reinstall the on-premises agent, you must first deinstall it. Follow these instructions in the order specified.

  1. Stop the on-premises agent:

  2. Delete the directory in which the on-premises agent is installed.

  3. Go to the Oracle Integration Cloud Service home page.

  4. Click Agents.

  5. Find the agent group.

  6. Click the number representing the agent count. The Agents in this Agent Group dialog is displayed.

  7. Find the agent to delete, and click X to delete the agent registration.

  8. Reinstall the on-premises agent with the agent group specified in the installation parameters, as described in Installing the On-Premises Agent.