Best Practices from Oracle Development's A‑Team
-
Diagnostics and Troubleshooting
November 29, 2018
OIC Connectivity Agent Installation Pointers
The connectivity agent has been a feature of Oracle's integration cloud strategy from the beginning to address the challenge of the cloud/on-premise integration pattern. However, the implementation of the agent differs between Oracle Integration Cloud Service (ICS) and Oracle Integration Cloud (OIC). With both offerings, the pattern for setup remains the same:
- Create Agent Group in ICS/OIC Console
- Download the connectivity agent installer
- "Install" the agent on an on-premise machine using the Agent Group ID from step 1 (this registers the agent with ICS/OIC)
- Verify that the agent is communicating with ICS/OIC via the integration console
However, step 3 differs dramatically between ICS and OIC. With ICS, the installation process resulted in a WebLogic Server (WLS) Single-Server configuration (i.e., all-in-one WLS server). Although the setup for the ICS agent has been optimized for an easy installation experience, the end result is fairly heavyweight. Now looking at how the agent is installed on OIC, it is simply a jar file that is kicked off using java -jar connectivityagent.jar. The end result is "behavior wise" is the same, but the footprint and experience from a setup/configuration perspective is radically different. The rest of this blog will focus on what happens when the OIC agent is "installed" and details that may not be obvious from the on-line documentation that can result in some "why does this not work" head scratching.
OIC Connectivity Agent High-Level Installation Steps
- Create an Agent Group in the OIC Console
- Download the Connectivity Agent zip file from the OIC Console
- Unzip the contents of the zip file on the on-premise agent machine
- Update the InstallerProfile.cfg with the details of the OIC environment and on-premise network
- Run the agent using java -jar connectivityagent.jar
Please refer to the OIC Connectivity Agent on-line documentation for the details associated with the steps mentioned above:
OIC Connectivity Agent Installation Experience
Once the zip file is downloaded from the OIC console and unzipped on the agent machine, you will see something like the following directory structure (as of 18.4.3):
$ tree . ├── InstallerProfile.cfg ├── agenthome │ ├── agent │ │ ├── cert │ │ │ └── keystore.jks │ │ ├── config │ │ │ ├── CpiAgent.properties │ │ │ └── logging.properties │ │ └── data │ ├── bin │ ├── lib │ │ ├── AQCloudAdapter.jar │ │ ├── AqAdapter.jar │ │ ├── CommonDatabaseCloudAdapter.jar │ │ ├── DB2DatabaseCloudAdapter.jar │ │ ├── DBAdapter.jar │ │ ├── DatabaseCloudAdapter.jar │ │ ├── FileCloudAdapter.jar │ │ ├── JDEEOneCloudAdapter.jar │ │ ├── JmsAdapter.jar │ │ ├── JmsCloudAdapter.jar │ │ ├── MySQLDatabaseCloudAdapter.jar │ │ ├── OracleDBaaSCloudAdapter.jar │ │ ├── RestCloudAdapter.jar │ │ ├── SQLServerDatabaseCloudAdapter.jar │ │ ├── SapCloudAdapter.jar │ │ ├── SiebelAdapter.jar │ │ ├── SoapCloudAdapter.jar │ │ ├── adapter_xbeans.jar │ │ ├── adf-share-base.jar │ │ ├── bpm-infra.jar │ │ ├── cloud-adapter-common.jar │ │ ├── cloud-connectivity-persistence.jar │ │ ├── cloud-connectivity-services.jar │ │ ├── cloud-designtime-api.jar │ │ ├── cloud-designtime-impl.jar │ │ ├── cloud-runtime-api.jar │ │ ├── cloud-runtime-impl.jar │ │ ├── com.bea.core.apache.commons.lang.jar │ │ ├── com.bea.core.xml.xmlbeans.jar │ │ ├── com.oracle.http_client.http_client.jar │ │ ├── com.oracle.webservices.fmw.client.jar │ │ ├── com.oracle.webservices.fmw.dbws-impl.jar │ │ ├── com.oracle.webservices.orawsdl-api.jar │ │ ├── com.sun.mail.javax.mail.jar │ │ ├── cpi_agent.jar │ │ ├── cpi_common.jar │ │ ├── cpi_filetransmitter.jar │ │ ├── cpi_install.jar │ │ ├── cpi_invoker.jar │ │ ├── cpi_omcs.jar │ │ ├── dbapi-impl.jar │ │ ├── dbapi.jar │ │ ├── dbplsql.jar │ │ ├── dms.jar │ │ ├── eBusinessCloudAdapter.jar │ │ ├── fileAdapter.jar │ │ ├── fmwgenerictoken.jar │ │ ├── jackson-annotations.jar │ │ ├── jackson-core-asl-1.9.2.jar │ │ ├── jackson-core.jar │ │ ├── jackson-databind.jar │ │ ├── jackson-mapper-asl-1.9.2.jar │ │ ├── javatools-nodeps.jar │ │ ├── javatools.jar │ │ ├── javax.jms.javax.jms-api.jar │ │ ├── javax.management.j2ee.jar │ │ ├── javax.resource.javax.resource-api.jar │ │ ├── javax.transaction.javax.transaction-api.jar │ │ ├── javax.xml.rpc.jar │ │ ├── jca-binding-api.jar │ │ ├── jca-binding-osb.jar │ │ ├── jersey-client-1.18.jar │ │ ├── jersey-core-1.18.jar │ │ ├── jersey-multipart-1.18.jar │ │ ├── jrf-api.jar │ │ ├── ojdbc6dms.jar │ │ ├── ojdl.jar │ │ ├── oracle.ics.abstractionapi.jar │ │ ├── oracle.ics.icscommon.jar │ │ ├── oracle.ide.jar │ │ ├── oracle.jdevimpl.xml.schema.jar │ │ ├── oracle.sca.ui.adapters.jar │ │ ├── oracle.tools.cloud.adapter.ide.jar │ │ ├── oracle.tools.cloud.adapter.sdk.jar │ │ ├── oracle.tools.uiobjects.sdk.jar │ │ ├── oracle.ucp.jar │ │ ├── oracle.xdb.jar │ │ ├── oracleUtilitiesAdapter.jar │ │ ├── orai18n-collation.jar │ │ ├── org.apache.commons.logging_1.2.jar │ │ ├── staxon-1.0.jar │ │ ├── staxon-jackson-1.0.jar │ │ ├── wldb2.jar │ │ ├── wlsqlserver.jar │ │ ├── wlthint3client.jar │ │ ├── wsm-agent-core.jar │ │ ├── wsm-policy-core.jar │ │ ├── xmlparserv2.jar │ │ └── xquery.jar │ ├── logs │ ├── thirdparty │ │ └── lib │ └── version └── connectivityagent.jar 10 directories, 95 files
When getting ready to run the agent for the first time (i.e., do an installation/configuration of the agent), it is very important to include all known details of the on-premise network in the InstallerProfile.cfg before this initial run. The reason this is important is when the agent is run the first time, it will take the details from the InstallerProfile.cfg and update the CpiAgent.properties before starting the agent. When the agent starts up, it will use the CpiAgent.properties and not the InstallerProfile.cfg. As the file name InstallerProfile.cfg implies, it is only used at install time (initial run) and will be ignored for all subsequent startups of the agent.
Why are the details regarding the use of InstallerProfile.cfg so important? There can be a misunderstanding about the single use of the this file which can result in confusions around troubleshooting miscommunications between the agent and on-premise resources. A perfect example of this is the following scenario: The OIC agent is configured, run the first time, and shows as communicating with OIC (all looks good). A configuration of a connection to an on-premise resource (e.g., E-Business Suite) in OIC fails to successfully "test". To troubleshoot the issue, a curl command or a ping is issued from the agent machine to the on-premise system ... which is successful. That makes no sense as the connection test is failing. But wait, the agent is using the on-premise proxy server to communicate with OIC and there was an oversight of adding the on-premise system host name to the proxy_NON_PROXY_HOSTS= of the InstallerProfile.cfg. This oversight was corrected by adding the appropriate configuration to InstallerProfile.cfg for the non-proxy hosts. The agent is restarted, but the connection test still fails since the InstallerProfile.cfg is only used for the initial run of the agent (i.e., the new entry in the InstallerProfile.cfg is not picked up). The fix to this problem is to "reinstall" the agent using the updated InstallerProfile.cfg or manually update the CpiAgent.properties with proxy_nonProxyHosts=.
The following are examples of how the InstallerProfile.cfg impacts the CpiAgent.properties. The contents of CpiAgent.properties prior to the first run of the agent:
$cat CpiAgent.properties #Updated #Thu Aug 17 09:56:48 PDT 2017 icsPlatform= proxyAuth= adminProfile= agentTransport=aq namespace= omcsUri= proxy_host= agent_port= agentWorkerThreads=40 managedserverport= proxy_port= onPremiseAgentVersion= externaljars= agentInstanceId= icsRESTBaseURI=
First scenario where only the oic_URL and agent_GROUP_IDENTIFIER are specified:
$ cat InstallerProfile.cfg # Required Parameters # oic_URL format should be https://hostname:sslPort oic_URL=https://development-xxx.integration.ocp.oraclecloud.com:443 agent_GROUP_IDENTIFIER=A_TEAM_TEST_GROUP # Proxy Parameters proxy_HOST= proxy_PORT= proxy_USER= proxy_PASSWORD= proxy_NON_PROXY_HOSTS= $cat CpiAgent.properties #Updated #Tue Nov 27 09:22:18 MST 2018 icsPlatform=ExternalCompute proxyAuth= adminProfile= authenticatedProxy=false agentTransport=aq proxy_nonProxyHosts= namespace=A_TEAM_TEST_GROUP omcsUri= proxy_host= agent_port= managedserverport= agentWorkerThreads=40 proxy_port= externaljars= onPremiseAgentVersion=18.4.3.0.0 agentInstanceId=CA-VIRTUALBOX-1543335735035 icsRESTBaseURI=https\://development-xxx.integration.ocp.oraclecloud.com\:443
Next scenario includes the proxy details for the on-premise network:
$ cat InstallerProfile.cfg # Required Parameters # oic_URL format should be https://hostname:sslPort oic_URL=https://development-xxx.integration.ocp.oraclecloud.com:443 agent_GROUP_IDENTIFIER=A_TEAM_TEST_GROUP # Proxy Parameters proxy_HOST=someproxy.example.com proxy_PORT=8080 proxy_USER= proxy_PASSWORD= proxy_NON_PROXY_HOSTS=on-premise.example.com $cat CpiAgent.properties #Updated #Tue Nov 27 10:20:35 MST 2018 icsPlatform=ExternalCompute proxyAuth= adminProfile= authenticatedProxy=false agentTransport=aq proxy_nonProxyHosts=on-premise.example.com namespace=A_TEAM_TEST_GROUP omcsUri= proxy_host=someproxy.example.com agent_port= managedserverport= agentWorkerThreads=40 proxy_port=8080 externaljars= onPremiseAgentVersion=18.4.3.0.0 agentInstanceId=CA-VIRTUALBOX-1543339209542 icsRESTBaseURI=https\://development-xxx.integration.ocp.oraclecloud.com\:443
As you can see, depending upon the details specified in the InstallerProfile.cfg it results in the corresponding settings in CpiAgent.properties.
Tip/Trick
It was mentioned earlier that once the agent runs for the first time the InstallerProfile.cfg is ignored. There is one exception to this and that is the OIC user name and password that is used to start the agent. This user is simply used to verify that OIC is available prior to starting the agent. The following can be added to the InstallerProfile.cfg:
oic_USER=[OIC user name]
oic_PASSWORD=[OIC user password]
If there are any concerns about the clear text password in this file, the agent startup process will update the entries with encrypted values upon a successful start. This is very handy as most agent startups will require the agent to continue to run in the background (e.g., nohup) when the user session terminates. Having those entries in the InstallerProfile.cfg causes the agent startup process to bypass the prompts for credentials.
Summary
The key take away from this blog is to remember that the InstallerProfile.cfg is a single use configuration file (with the exception of the OIC user/password) for agent installation. If any changes need to be made to the initial installation configuration there are two options: 1. Reinstall the agent with the updated InstallerProfile.cfg, or 2. manually update the CpiAgent.properties.
Join the discussion
-
As a POC, I Have successfully installed agents to establish a connectivity between OIC and On-Prem WebLogic and was able to invoke the SOA services hosted on it from Integration. However, I am trying to figure out a solution, where the client has an f5 Load balancer, multiple web servers (Virtual) and multiple application servers - (physical/virtual). It would be a nightmare to install the agent on each application servers (hosts). So, Is there a way to install the agent on the Load Balancer? where bi-directional NAT happens. If, we can, will the required adapters function properly as they are expected to. Please let me know your thoughts.
-
Is the connection between the agent and OIC encrypted?
-
Aditya, all of the communication between the agent and OIC is encrypted.