Rafael Andrade, Nedzad Saranovic
As part of Oracle Fusion Middleware 11.1.1.7, Oracle introduced the Cloud Adapter for Salesforce.com integration. In this TechNote we will first provide some general information about Cloud Adapter and shortly describe the support, behaviour and restrictions. Then we will proceed with comparing Cloud Adapter and Custom Web Service call, state strengths and limitations of each approach, and end with some final recommendations.
Cloud Adapter integration
Cloud Adapter offers a single integration platform to unify cloud and on-premises applications, reducing the effort to manage authentication, session management and transformation mappings that is usually needed when you build a direct integration with Salesforce using the WSDL API. Depending on the business needs, integration can be done from different systems and in different areas and data sets: Account, Contact, Product, Invoice, Billing, Order, Fulfilment, integrating hundreds of objects existing in Salesforce.
Following the usual Adapter Wizard approach, the integration can be easily created by browsing, searching and selecting one or more Salesforce business objects and operations. It also allows modelling of SOSL/SOQL queries, providing design time validation capabilities.
The Cloud adapter is available in the 11g (11.1.1.7) and 12c versions of Oracle Fusion Middleware. Although we expect to have out of the box functionalities with this new feature in the Middleware platform, the initial set up needs some attention and manual configuration on the server side. We will soon post another blog in which you will find the installation steps needed to have the Cloud Adapter for Salesforce.com integration working in both SOA Suite and OSB. We’ll be using Oracle 12c as reference for all technical details.
Adapter support, behaviour and restrictions
The Cloud Adapter for Salesforce.com supports the following operations:
| Category | Operation |
| CORE | convertLead, getDeleted, getUpdated, merge, undelete, upsert |
| CRUD | create, retrieve, update, delete |
| MISC | getUserInfo, process |
| SOSL / SOQL | query, queryAll, search, queryMore |
During design-time, each time you instantiate a Salesforce Adapter in your SCA or OSB, an operation needs to be selected and for each operation, you can choose a set of Salesforce objects that will be affected. Each invocation of the adapter instance should be seen as a transaction within Salesforce. There is a header property “All or None” that allows you to say what to do in case of an intermediate failure: rollback all changes or keep what was already changed.
During run-time, the Adapter will handle the user session in a transparent way, storing the session in the cache for future calls and avoiding multiple calls to login the user.
There are restrictions on the number of objects that can be selected for one Salesforce instance. The number of objects vary depending on the operation being selected. In addition to that, when you instantiate the adapter (and thus select the operation and objects), if you need separate transactions or need information from one object (e.g. account ID) to be added to another object (e.g. contact), you will need to create two separate adapter instances, make two separate calls and handle the distributed transaction and compensations.
Recommendation
After the environment is correctly set up, the use of the Cloud Adapter is really straightforward. If you have a custom integration that involves a simple scenario, with only a few interactions with Salesforce and operations on top of a reduced number of objects, the use of Cloud Adapter is suggested to easily process the Salesforce requests. For complex scenarios with multiple interactions with Salesforce or for a generic approach that allows any call to be made to Salesforce, the use of Cloud Adapter may be too time consuming, due to the particularities related to the way Salesforce Adapter is created in your project. In these cases you will need to create one instance of the adapter for each different object and/or operation.
Alternate approach
For complex scenarios it might be better to interact directly with Salesforce API using the Enterprise WSDL. You will need to manage the sessions (login/logout) in your custom code, but it allows you more flexibility to create a generic approach and reuse it.
The custom Proxy or Business Service can be built based on the same WSDL used for Oracle Cloud Adapter. You need to import the WSDL as a web service reference and call the expected operation, sending the Salesforce Business Object as a payload.
Before you call the service to query or change objects, however, you need to call the Login operation and handle the Session ID received back, that needs to be included in any subsequent requests. As a recommendation, it would be better to handle the session separately from the integration code and keep the session alive on the server side using a more robust approach, reusing the same session for multiple calls. In this case, you should be able to handle the exceptions in case of Salesforce invalidating the session, doing the login again and retrying the failed transaction.
Salesforce has a limit on the number of logins that you can do per day and expects you to store the Session ID and Server URL for multiple calls. It means that you should not login/logout for each operation, otherwise your logins will start to be rejected. In addition to that, the way Salesforce handles session, once you do a login, the session will be opened on the Salesforce side and any next logins done by the API will join the same session, instead of creating a new one. It means that if you do a logout, you will be invalidating the session not only for your flow instance, but for all flows that did a login while your session was active. The recommendation in this case is to NOT logout. Just do a login if you do not have the Session ID and keep the session alive, handling only the exceptions in case the session is terminated by Salesforce to do the login again.
Below is a comparison between the two approaches, with advantages and disadvantages of each one.
Strengths
| Oracle Salesforce cloud adapter | Direct call to Salesforce API |
| Straightforward wizard based approach during design | All operations exposed in one API |
| Built-in management of session and authentication | All objects exposed in one API without restrictions |
| Easier mapping of data during design | Can be a part of a generic framework |
| Performance restricted only by hardware and Salesforce restrictions | Performance restricted only by hardware and Salesforce restrictions |
| Adapter supports up to 6 previous versions of Salesforce.com | No extra license costs |
Limitations
| Oracle Salesforce cloud adapter | Direct call to Salesforce API |
| It does not work out of the box. Requires additional configuration setup. | Extra effort needed in development for session and authentication management |
| Limitations imposed by Salesforce on number of objects per operation transferred to adapter | Extra effort needed for data transformation within BPEL or OSB because of polymorphism |
| Adapter is limited to only one operation per created instance | Requires more knowledge and experienced developer to make it work |
| Not generic enough to be used as a part of a framework | Limitations imposed by Salesforce on number of objects per operation exist although the API itself has no limitations |
| Extra cost per processor to use on top of every SOA licence |
The use of the web service interface from Salesforce is free of charge, so if you follow the direct approach, the cost is limited to the effort to build the custom integration. If you plan, however, to use the Salesforce Adapter to speed up the initial integrations, you need to consider the cost associated to the Adapter, that is around $17.500 per core.
Final recommendations
- When dealing with only a limited number of operations and objects (one or two different operations on up to 5 objects) on the Salesforce side Oracle Cloud Adapter is preferred as it has authentication and session management out of the box.
- For complex situations with a large number of tasks that require different operations on multiple different objects, we recommend using direct calls of Salesforce API to achieve flexibility and generic approach.
- Only the direct invocation of Salesforce API is generic enough to be a part of a framework, so if you plan to include Salesforce in a framework for higher reusability, direct invocation of Salesforce API is the recommended approach.
Choice of integration approach is not made solely on technical information and data, but also on existing environment setup and business requirements, so final choice will depend on the project and use cases it needs to cover.
