Upgrading the On-Premises Agent

If you previously installed the on-premises agent on your local host, you must upgrade to the latest release to communicate with Oracle Integration Cloud Service.

To upgrade the on–premises agent release:


  • For the on-premises agent upgrade to work, you must set the JAVA_HOME and PATH parameters. Only Oracle JDK version 1.7 and 1.8 are supported. Any other JDK such as Open JDK does not work. If not set, on-premises agent upgrade fails. See Downloading and Running the On-Premises Agent Installer.

  • You can run the following command to obtain online help for upgrading the on-premises agent. This file is available in step 1g below.
    ./cloud-connectivity-agent-patcher.sh -help
  1. Download the latest agent installer ZIP file and perform the following steps. The ZIP file is required to extract the patcher. To upgrade, you can only use the patcher from the ZIP file.

    1. On the Oracle Integration Cloud Service home page, click the Agents diagram.

    2. Click Download to download the ZIP file.

    3. Select Connectivity Agent. This initiates the patch ZIP file download.

    4. Save the ZIP file to the file system.

    5. Unzip the ZIP file and note the following files.

      • cloud-connectivity-agent-installer.bsx

      • cloud-connectivity-agent-patcher.zip

    6. Extract the cloud-connectivity-agent-patcher.zip and notice the following files.

      • cloud-connectivity-agent-ics.properties

      • cloud-connectivity-agent-patcher.jar

      • cloud-connectivity-agent-patcher.sh

      • cloud-connectivity-agent-patching-scripts.zip

    7. Run cloud-connectivity-agent-patcher.sh.


      • Ensure that you specify - (shorter hyphen) in front of each parameter and not (longer hyphen). For example, -au and not —au.

      • If specifying the -patchZipFile, ensure that you supply the file with pattern ics_conn_agent_installer_XXXXXX.YYYY.zip. This is the actual zip file of the connectivity agent installer downloaded from Oracle Integration Cloud Service.

      During upgrade, use the -patchZipFile parameter to specify the complete path of the patch zip file that includes the BSX file.

      ./cloud-connectivity-agent-patcher.sh -agentInstallDir=AGENT_INSTALL_DIR -icsUn=ICS_username -icsPwd=ICS_password -patchZipFile=file_name.zip 
      Parameter Status Description
      -agentInstallDir Mandatory The installation directory of the existing agent (AGENT_INSTALL_DIR under which agenthome should be present).
      –icsUn Mandatory The Oracle Integration Cloud Service username for running the upgrade (for example, weblogic).
      –icsPwd Mandatory The password of the Oracle Integration Cloud Service username for running the upgrade.
      -patchZipFile Optional The complete path of the already downloaded patch ZIP file in which the BSX file is available. If you do not specify this parameter, a smaller-sized version of the ZIP file for exclusively upgrading the on-premises agent is automatically downloaded from Oracle Integration Cloud Service.
  2. For example, in the following command, the /scratch/myuser/agents/agent1 directory includes the agenthome directory and the /scratch/myname/agents/patch/ directory includes the ZIP file that contains the cloud-connectivity-agent-installer.bsx file.
    ./cloud-connectivity-agent-patcher.sh -agentInstallDir=/scratch/myuser/agents/agent1 –icsUn=weblogic -icsPwd=mypassword -patchZipFile=/scratch/myname/agents/patch/cloud-connectivity-agent-installer-1234.5678.zip
    For this example, the patch ZIP file was manually downloaded from Oracle Integration Cloud Service. Therefore, it is good to use that same patch file. If the -patchZipFile parameter is not specified, the application connects to Oracle Integration Cloud Service and downloads a smaller-sized version of the ZIP file for exclusively upgrading the premise agent, and proceeds with patching.

    The patching process begins. The security certificate is downloaded if not already available and added to the keystore. If you go to the Agent Groups page in Oracle Integration Cloud Service during the upgrade process and expand the agent group name, various messages are displayed, including Upgrade in Progress, Restart Pending, and Up to Date. The on-premises agent is automatically restarted after the patch is applied. Once the patch ZIP file is available for extraction (either through the -patchZipFile parameter or through download from Oracle Integration Cloud Service), the remaining process takes around 10 to 15 minutes to complete. This time period includes restarting the on-premise agent.

  3. Verify that upgrade is complete by looking under the agenthome directory. You see that the soa, osb, and lib directories are upgraded and backups of these directories have occurred. The backups are identified by a _BAK_PRE_NEW-VERSION suffix in the agenthome directory.