Oracle’s vision for quick, easy, and efficient ways to integrate on-premise business applications with Software as a Service (SaaS) cloud applications is to provide adapters as integrations points between the on-premise applications and applications in the cloud. The Oracle Cloud Adapter for Salesforce.com (SFDC) is once such adapter that is out there today.
If you have worked with the Salesforce API’s (SOAP and REST), you may have discovered that the operations are quite generic and that you need to know the existing Salesforce objects and the Salesforce system quite well in order to understand how to perform simple operations such create and update. Oracle has provided their Oracle Cloud Adapter for Salesforce.com to help alleviate some of the more cumbersome Salesforce API use cases such as session creation, session management, understanding which Salesforce objects are available, and knowing which fields exist on the objects.
Before you can begin to make life a little easier with the use of the Oracle Cloud adapters, you must first install the adapter in JDeveloper and in your Oracle SOA Suite 11g Middleware home directories. There are a number of blogs and sites out there on the internet that cover the basic installation but I found that few, if any, cover the nuances of the installation.
This topic is dedicated to filling in some of the blanks for the installation of the Oracle Cloud Adapter for Salesforce.com adapter.
Lessons Learned
- Official Documentation Lesson Learned: You can find the official installation doc here and, when used with the following lesson learned, should cover a SOA 11g installation of the adapter quite well: http://www.oracle.com/technetwork/middleware/adapters/documentation/ug-sfdcadapter-ps6-2104970.pdf
- JDeveloper Lesson Learned 1: In 11g, you can install the Salesforce adapter by simply updating your SOA extension via the Help->Check for Updates… feature. After installing the extention, check your Oracle SOA Composite Editor extension and verify that it is version 11.1.1.7.0.99.99 or higher. Also, know this way of updating JDeveloper has replaced the earlier approach for manually patching JDeveloper (opatch from a downloaded patch) to install the Salesforce adapter. You can ignore any older patches or information stating to manually patch JDeveloper 11g.
- JDeveloper Lesson Learned 2: I’ve just updated JDeveloper, but I don’t see the adapter!? At the time of writing this article, it is important to know that in JDeveloper 11g the Salesforce adapter is only available in the Component Palette of SOA Composites. It is not available for BPM Composites in JDeveloper 11g.
In reality, this is not a big issue at all because proper service and composite management and development often does not include combining very many BPM Processes and SOA services within the same composite. However when trying to learn or trying to create demo code this situation becomes much more likely to occur and can be extremely confusing. Oracle product management is aware of this JDeveloper 11g issue and should be tracking its resolution. Finally, I do believe the Salesforce adapter is present for both SOA and BPM composites in JDeveloper 12c but I don’t have a screen capture to prove it right now so I will leave you to verify the situation for yourself.
- Patching SOA Servers Lesson Learned 1: The patch I applied was the SOA 11g BP6 patch 19953598 and is a super set of previous patches as of the time of writing this article, 4/23/2015. Meaning you can ignore the older/lower patch versions that do the same patching. You can download the patch from the Oracle Support Site fhere https://support.oracle.com/epmos/faces/PatchDetail?patchId=19953598&requestId=18297013
- Patching SOA Servers Lesson Learned 2: Be sure to have a version of Opatch installed and configured that is version 11.1.0.8.2 or higher when using patch 19953598.
- Patching SOA Servers Lesson Learned 3: If you have ever applied a Bundle Patch (BP) before then you know that you will likely run into conflicts with smaller patches that were applied before they were rolled into the BP. With BP6 I knew I could ignore all of my conflicts but to do so I had to apply the patch using napply -force via opatch for the BP6 patch which contains the Salesforce Adapter.
- Patching SOA Servers Lesson Learned 4: Patch 19953598 must be applied to both ORACLE_SOA1 and oracle_common home directories. I believe this information is covered either in the installation guide or in the patch readme file but I think it is a good point to highlight no matter what.
- Patching SOA Servers Lesson Learned 5: This lesson was taken directly from a page on the Oracle Support site and may not be covered at all in the installation guide or the patch readme file. “Due an issue within BP6 11.1.1.7.6 Patch 19953598, you will need to manually copy the oracle.soa.adapter.jar file from the Patch location: 19953598customscripts to the SOA Server in $SOA_HOME/soa/modules/oracle.soa.adapter_11.1.1” See the Oracle Support documentation here https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=ubrvb4km7_9&_afrLoop=298910270209054
- SSL Lesson Learned 1: If you’ve ever played around with anything SSL related in SOA Suite 11g then you may know that the domain trust store is hard coded out of the box to use the default trust store JKS file. If you are trying to setup a custom trust store you need to open the $DOMAIN_HOME/bin/setSOADomainEnv.sh (or setSOADomainEnv.bat) and remove the hard coded arg –Djavax.net.ssl.trustStore=${WL_HOME}/server/lib/DemoTrust.jks (for Windows –Djavax.net.ssl.trustStore=%WL_HOME%serverlibDemoTrust.jks) and configure your new trust store location properly. If starting your SOA server via the NodeManager, then set the trust store argument(s) in the Server Start Arguments for each SOA server you have. Below shows the trust store and trust store password args being set. There are better ways to provide the password that can be found in Oracle documentation, but this approach will verify that the trust store is setup properly to begin with.
If starting the SOA server(s) by means other than the NodeManager, you can simply change the setSOADomainEnv arg –Djavax.net.ssl.trustStore=${PATH_TO_YOUR_TRUSTSTORE} for each of your SOA server’s startup params, where ${PATH_TO_YOUR_TRUSTSTORE} is the path to the custom trust store you are planning to use.
If you attempt to use a custom trust store and do not make one of the two changes listed above your custom trust store WILL NOT BE SEEN and you will likely encounter the unpleasant exception:
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to
requested target
If you are playing around in your own environment, it simply easier to just use the trust store DemoTrust.jks (which is already hardcoded) to be used by the server so you can move on to importing your Salesforce cert.
- SSL Lesson Learned 2: The official documentation does a good job of pointing out where to get the Salesforce cert but does not point out exactly which level of the cert to export in order to increase the likelihood that the SSL communication is going to work. Export and use the *.salesforce.com cert from the root level of the SSL Certificate Hierarchy to avoid encountering the unpleasant exception:
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to
requested target
SSL guru’s can tell you all about cert management and hierarchy’s and cert practices and such. Just know that this article is simply trying to get you up and running until the SSL guru’s come in to help you fine tune your security.
- SSL Lesson Learned 3: In the Weblogic console, find and turn off “Hostname Verification” by applying the value of “None” for each SOA server. Don’t forget to click “Activate Changes”. I believe this configuration should have already been put in place if following the practices in the Enterprise Deployment Guide before getting to the point of SSL cert setup.
- General Lesson Learned 1: I could not find any documentation on configuring the adapter itself so I had to learn this lesson through pure investigation on my own. There is no Salesforce adapter application deployed to Weblogic server meaning you will not need to make any adapter application configurations like you must do when using the DB Adapter. There are still configurations when using the Salesforce adapter such as a CSF Map, CSF Key, etc. but the configurations are not similar to the DB Adapter and some of the other adapters that exist in SOA Suite.
Conclusion
I don’t claim that this article will solve every issue encountered when installing the Oracle Could Adapter for Salesforce.com, but I know it should save some time with some commonly encountered sticking points that are not covered in detail by the installation guide or by other internet articles currently out there today. Once up and running, you should compare using the Salesforce API via SoapUI (or another tool) against using the Salesforce adapter and you will quickly see how much help the adapter provides.
If there is enough interest in this article, I may follow up with some lessons learned on actually using the Salesforce adapter. I was sure to note a few lessons learned in the usage department as well, but that is a different topic in itself. For now I wish you the best of luck on getting your adapter installed and moving on to the next step of integrating with a Salesforce system 🙂