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 Release 17.2.5. To learn more about on-premises agent concepts, see About Agents and Integrations Between On-Premises Applications and Oracle Integration Cloud Service.

System Requirements and Restrictions

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:

    JAVA_HOME=/usr/java/jdk1.7.0_79
  • Set the PATH property. For example:

    PATH=/usr/java/jdk1.7.0_79/bin:$PATH
  • 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.6 (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.

Installing the On-Premises Agent

To download and run the on-premises agent installer:

Note:

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.

    Note:

    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=https://ICS_host.us.oracle.com:port —u=username —p=my_password —ad=agent_group_identifier -au=agent_username -ap=agent_password
    where:
    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, https://icsapps.integ.dc4.c1234.oraclecorp.com:443).

    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  
      java.net.SocketTimeoutException: Read timed out                 
         at java.net.SocketInputStream.socketRead0(Native Method)                 
         at java.net.SocketInputStream.socketRead(SocketInputStream.java:116)                 
         at java.net.SocketInputStream.read(SocketInputStream.java:170)                 
         . . .
    -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 |.

    -nphosts=abc.com|xyz.com
     
    -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 CpiAgent.properties 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 CpiAgent.properties file after installation. This change requires an agent restart.

    agentWorkerThreads=40

    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.

Note:

Do not use startWeblogic.sh and stopWeblogic.sh to start and stop the on-premises agent. Instead, use startAgent.sh and stopAgent.sh.

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] com.oracle.cie.domain.jdbc.DatasourceXBeanAspectHelper - 
    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] com.oracle.cie.domain.jdbc.DatasourceXBeanAspectHelper - 
    Selected DB ID/CAT: DerbyDerby's Driver (Type 4) Versions:Any 2016-01-27 20:48:51,714 FINE  
    [47] com.oracle.cie.domain.jdbc.DatasourceXBeanAspectHelper - Selected DB vendor: Derby 
    2016-01-27 20:48:51,714 FINE  [47] com.oracle.cie.domain.jdbc.DatasourceXBeanAspectHelper - 
    adding normal datasource: opss-data-source 2016-01-27 20:48:51,714 FINE  [47] 
    com.oracle.cie.domain.jdbc.DatasourceXBeanAspectHelper - 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

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:
    ./stopAgent.sh
  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.