Wednesday Jul 01, 2015

Calling Fusion SOAP Services from Ruby

Just completed some integration work with a partner of ours using the Ruby language. Given that a lot of startups like Ruby I thought it would be useful to cut-n-paste the sample code here.
This example creates a simple (minimal) opportunity using the SOAP API in Sales Cloud. That said the code would be almost identical if you were querying HCM Data,
The approach we took here was to prototype the SOAP call using SOAPUI and then cut-n-paste the SOAP payload into the data variable. In a real industrialized solution I'd create the payloads in template form.

  def create_opportunity

  # Change to your Fusion SOAP Endpoint Hostname

    http =, uri.port)
    http.use_ssl = true
    path = uri.request_uri
    http.read_timeout = 5
    http.open_timeout = 5

  # Change authorization header to contain Base64encoded string of username/password
    headers = {
    'Content-Type' => 'text/xml',
    'authorization' => 'Basic bBase64EncodedCredentialHere='

   # Data Contains the payload
    <opp:Name>Joel Test New1</opp:Name>

    resp, data =, data, headers)

A quick test in a SOAP testing tool like JDevelopers Http Analyzer or SOAPUI is a MUST before executing this!

Monday May 04, 2015

Getting started with Sales Cloud (Updated)

Hey all, Ive just reviesed the Getting Started with Oracle Sales Cloud Integrations blog entry with a few more links

Thursday Dec 04, 2014

Getting Started with Oracle Fusion Cloud Integrations

Updated: 4-May-2015

Hey all,

If your getting started with integrating your application with Oracle Fusion Cloud then I wholeheartedly recommend you read the following resources before starting.. Most of the below is specific to Oracle Sales Cloud because it has App Composer, however much of the below is also applicable to HCM, ERP and other Fusion products.. 

Some of these are a MUST have read before you start integrating/coding/customizing :-) I've put them here in the order I think would work for most people... Kinda like a getting started check-list

I consider this blog entry an living blog entry, in that  I'll be updating it on a regular basis, so make sure you periodically check this location 

Top 5 Fusion Integrations Must Reads 

1. Familiarise yourself with the Sales Cloud Documentation. Specifically :

    • Go through the "User" section, documents like "Using Sales Cloud", "book. If your a techie like me you'll sit there and think, "Hey this is functional why do I need to read this?", well you do.. Even as a technical person, reading through the various user documents like the Using Sales Cloud" bits as an end user helps you understand what the different concepts/topics are.. You'll also understand things like the difference between a Prospect and a Sales Account, territories, assessments and much more.. Its worth a quick read, but do make sure you have a functional consultant to hand to make sure your not building something which can be done by configuration....
    • Read through all the books in the "Extensibility" section. The only anomaly here is the "Business Card Scanner mobile App" document. Its a walk-through of how to integrate Sales Cloud with a 3rd party Service to do business card scanning with MAF... Id leave that till last...
    • Peruse the Development section, this section contains a number of example use-cases, ie how to create a customer in R8, how to call an outbound service, its a good read....
2. Get an overview of the tasks you might do...
    • Once you've this then look at the "Tasks" section of the docs....Here the curriculum development folk have categorised some of the most common tasks and put short cuts to the documentation detailing how to do this.. e.g. like adding a field to Sales Cloud, calling a soap webservice etc
3. Are you going to be customizing the SalesCloud User Interface?
    • Many Sales Cloud integrations involve customizing the Sales Cloud User Interface. The customization could be as simple as adding a few fields to a standard object (like Opportunity), creating new objects (like MyOrder), validation or adding external content to one or many pages.
    • If your adding fields make sure you read the "Introduction to SalesCloud Customizations" section.
    • If you will be adding validation, triggers or calling webservices from Sales Cloud then make sure you read up on groovy scripting, and specifically the chapter on calling outbound SOAP webservices from groovy.
    • Make sure you understand the difference between calling a SOAP Service from groovy and creating an outbound webservice call using object workflows
      • In a nutshell , calling SOAP Services from groovy is a synchronous call, and calling a SOAP Service from a object workflow is a fire-and-forget asynchronous call
      • If you need to make sure an outbound webservice call is executed successfully then call the outbound webservice from a groovy script and surround it with an exception handler to catch any errors
    • On the subject of groovy be aware that in Sales Cloud you do not have access to the entire groovy language, thus make sure you understand that we only support a number of groovy functions (white-listing) and these are documented at the end of the book , Appendix A Supported Groovy Classes and Methods
4. Are you going to be accessing data from SalesCloud from the external app??
    • If you think you will be calling SOAP WebServices in Sales Cloud then the "Getting started with WebServices" is a MUST read...  This doc goes into details into how to look up the SOAP webservice in Fusion OER, how to create static proxies, querying data and how to perform CRUD operations...
    • Get to know Oracle Fusion OER,, its a gold mine of information.......
    • Read Arvinds ( A-Team Chronicles Blog ) excellent "Invoking Sales Cloud SOAP Services from external Applications (part 1)" blog entry. This blog entry describes the steps aronud looking up a SOAP service (ie Opportunities) and then how to create a SOAP JAX-WS static proxy using JDeveloper11g. I personally would the JAX-WS Proxy approach (vs the Data Control) and then building Java code around this to support your application.
5. Do you need your app to know who is calling it? 
    • Many integrations involve embedding a 3rd party web app into Oracle Sales Cloud as an iFrame or pressing a button in SalesCloud and calling the 3rd party app (either a UI or WebService call) . If your doing this then you'll almost certainly need to pass a "token" to the 3rd party application so it can use that it can call back to Sales Cloud with a key rather than a plain text username/password combo.. We call this key JWT TOKEN and its based on industry standards ( .  For a starters read my JWT Getting started blog  entry and then use the links to read the core documentation

That covers the top 5 areas of integration.. Now for a list of locations where you can get even MORE useful information :

More Information

  1. Oracle Learning Centres Quick Webinars on SalesCloud Integration
    • I worked with Development to get this mini tutorial series done, its excellent but Im obviously not biased eh  ;-) 
  2. R9 Simplified WebServices doc
    • This is a new document we recently completed based on how to use the new R9 Simplified SOAP TCA Services..  Although the document is targetted at R9 developers, it covers many of the standard topics like how to create a proxy, how to create a create operation etc.. It even has some sample CRUD payloads which are really really useful 
  3. Oracle Fusion Developer Relations
    1. Good friends of mine, they host a fantastic blog, youtube channel and whitepapers for Fusion Developers, another gold mine of information covering customization , extensions and integration code.
  4. Oracle Fusion Developer Relations
    1. Youtube channel : Not content with an awesome blog the Developer Relations folk even have a you tube channel where they host a collection of short "tutorials", showing all sorts such as "How to add a field to a page" , " How to call a webservice" etc..
    2. Oracle Fusion Developer Relations Whitepapers
  5. And finally there is my humble blog (which you are reading now) where I try and blog on things which aren't documented anywhere else.. If they are documented and are interesting I often link to it.. mainly because I want to find it myself :-)

Thats it folks!

If there are blog entries you'd like to see, or specific how to's, then feel free to contact me at


Thursday Oct 09, 2014

Generating Sales Cloud Proxies using Axis? Getting errors?

If your generating SOAP proxies using Apache Axis/2 you may find yourself hitting strange errors.. Whats even stranger is that you can generate proxies using JDeveloper and it works fine in tooling like SOAPUI.. Well help is at hand..

The most common error is

IWAB0399E Error in generating Java from WSDL:  java.lang.RuntimeException: Unknown element _value

I'm not sure if this is a bug in Fusion Sales Clouds base tech (ADFBC SDOs) or a bug in Apache Axis but there is a workaround and engineering are looking into this.

For a workaround you have two options

  1. Use adb binding and set the flag –Eosv to turn off strict validation.
  2. Use JDK xjc command to generate the JAXB classes:
  3. e.g. xjs -wsdl http://<salescloudsoapendpoint/opptyMgmtOpportunities/OpportunityService?WSDL

Enjoy and let me know if this works for you :-) 



Tuesday Jun 10, 2014

Common usecases and techniques when integrating a 3rd party application with Oracle Sales Cloud

Over the last year or so I've see a lot of partners migrating and integrate their applications with Oracle Sales Cloud. Interestingly I'd say 60% of the partners use the same set of design patterns over and over again. Most of the time I see that they want to embed their application into Oracle Sales Cloud, within a tab usually, perhaps click on a link to their application (passing some piece of data + credentials) and then within their application update sales cloud again using webservices.

Here are some examples of the different use-cases I've seen , and how partners are embedding their applications into Sales Cloud,
NB : The following examples use the "Desktop" User Interface rather than the Newer "Simplified User Interface", I'll update the sample application soon but the integration patterns are precisely the same

Use Case 1 :  Navigator "Link out" to third party application

This is an example of where the developer has added a link to the global navigator and this links out to the 3rd Party Application. Typically one doesn't pass any contextual data with the exception of perhaps user credentials, or better still JWT Token.

Techniques Used  

Use Case 2 : Application Embedded within the Sales Cloud Dashboard

Within the Oracle Sales Cloud application there is a tab called "Sales", within this tab its possible to embed a SubTab and embed a iFrame pointing to your application. To do this the developer simply needs to edit the page in customization mode, add the tab and then add the iFrame, simples! The developer can pass credentials/JWT Token and some other pieces of data but not object data (ie the current OpportunityID etc)

 Techniques Used

 Use Case 3 : Embedding a Tab and Context Linking out from a Sales Cloud object to the 3rd party application

In this usecase the developer embeds two components into Oracle Sales Cloud. The first is a SubTab showing summary data to the user (a quote in our case) and then secondly a hyperlink, (although it could be a button) which when clicked navigates the user to the 3rd party application. In this case the developer almost always passes context specific data (i.e. the opportunityId) and a security token (username password combo or JWT Token). The third party application usually takes the data, perhaps queries more data using the Sales Cloud SOAP/WebService interface and then displays the resulting mashup to the user for further processing. When the user has finished their work in the 3rd party application they normally navigate back to Oracle Sales Cloud using what's called a "DeepLink", ie taking them back to the object [opportunity in our case] they came from.

This image visually shows a "Happy Path" a user may follow, and combines linking out to an application , webservice calls and deep linking back to Sales Cloud.

Techniques Used

Use-Case 4 :  Server Side processing/synchronization

This usecase focuses on the Server Side processing of data, in this case synchronizing data. Here the 3rd party application is running on a "timer", e.g. cron or similar, and when triggered it queries data from Oracle Sales Cloud, then it queries data from the 3rd party application, determines the deltas and then inserts the data where required. Specifically here we are calling Oracle Sales Cloud using SOAP/WebServices and the 3rd party application is being communicated to using the REST API, for Oracle Sales Cloud one would use standard JAX-WS WebService calls and for REST one would use the JAX-RS api and perhap the Jackson api for managing JSON objects.. This is a very common use case and one which specifically lends itself to using the Oracle Java Cloud Service as the ideal application server where to host the mediator between the two applications.

 Techniques Used

General Resources

The above is just a small set of techniques and use-cases which are used today. There are plenty of other sources of documentation and resources available on the internet but to get you started here are a few of my favourite places 

Monday Jan 13, 2014

More complete RESTful Services for Oracle Sales Cloud Sample/Demo Application

This sample code builds on the previous code examples in my blog showing how you can create a RESTful Facade for Oracle Sales Cloud. Specifically this example concentrates on the six main objects people tend to work with :

  • Opportunities
  • Leads
  • Locations
  • SalesParty
  • Person
  • Interactions

This application is an extension of a previous blog article, it is recommended that this article, and tutorial, are followed first. 

Please note this code is SAMPLEWARE and delivered with no guarantees, warranties or  support

Functionality / Features

  • Supports Oracle Sales Cloud Release 7 and JDeveloper
  • Ability to query data in a RESTFul way (using GET/PUT verbs)
  • Data can be queried using JSON or XML data formats
  • URIs can contain parameters which reduce the amount of data which is returned , e.g. only bring back Opportunity IDs and Names
  • URI can contain SIMPLE queries, e.g. where OptyID=12323232
  • Complex queries can be passed in as a POST query when the URI ends in /xmlquery
  • User Credentials, CRM Server, FetchSize and FetchStart can be provided in httpHeaders, thus can be encrypted by SSL
  • Default Server can be setup so that credentials are not needed
  • Project can be extended to cover other objects


  • Read only is implemented, if you want to issue writes (PUTS) or updates then I recommend custom methods for each operation you require.
  • In the future Oracle Sales Cloud will likely have support REST support natively; This software will work fine against future versions of Oracle Sales Cloud but you are probably better off using the native Oracle Sales Cloud REST support when it 



Architect & Technology Evangelist - If its middleware,PaaS/SaaS integration then I'm interested

The views expressed on this blog are my own and do not necessarily reflect the views of Oracle.


« December 2015