Best Practices from Oracle Development's A‑Team

Extending Oracle Sales Cloud using Oracle Java Cloud Service

Arvind Srinivasamoorthy
Sr. Director, Oracle A-Team

Oracle Sales Cloud comes with tools such as Application Composer and Page Composer that allow you to customize and extend the application to suit your business needs. These tools can be used to add new UI elements, add validations, enrich the Sales Cloud data model, and to create interfaces with external applications. Additionally, Application composer provides a Groovy interface for advanced control over the application behavior.

In spite of powerful capabilities of these tools, sometimes it is desirable to build these extensions outside of Sales Cloud and deploy them to Oracle Platform Cloud offerings such as Oracle Java Cloud Service.

Some reasons for this approach include:

  • Displaying in Sales Cloud, data that is not directly Sales related: For example, in a Bank that uses Sales Cloud, there may be a requirement to view customer profile information such as average quarterly balance from within Sales Cloud. One option would be to use web services, but in many cases the data is not available as web services, but instead available as files, due to security or other constraints. Another option to work around this is to model the data in Sales Cloud (using Application composer). However this option may not be logical. In our example, bank transaction data logically does not belong to the Sales Cloud data model. Additionally, from an actual data volume perspective, loading large volumes of bank transaction information into Sales Cloud is unwarranted. In such scenarios, you could load this data into Oracle Database Cloud Service, display this data on an application built on Oracle Java Cloud Service, and embed/link out this application from Sales Cloud.
  • The need for an alternative UI behavior that is not satisfied by Sales Cloud tools: For example, there may be a requirement to display accounts and related contacts in a graphical view using UI widgets different from what Sales Cloud provides. Sometimes, the need for an alternative UI is also dictated by the UI standards of another application. For instance, a corporate portal may need to display sales information for the current quarter. In this case, the corporate UI dictates the look and feel of the UI to be built on Java Cloud Service, which will in turn be embedded within the portal.
  • The need for a common UI or web service that will be re-used across different applications: For example, a 360 view of a customer in an enterprise that captures information related to a customer from multiple applications. A UI such as this can be built on Java Cloud Service and linked out of each application in the enterprise. Another example would be a UI for person search-match which runs against an MDM application, but is linked off Sales Cloud and Marketing Cloud. Similarly, a web service that performs a common task can be deployed to Java Cloud Service and can be invoked from different enterprise applications.

There could be additional scenarios where it is desirable to build extensions using Java Cloud Service, or even a combination of Java Cloud Service and other Oracle Platform Cloud offerings. In this blog space you can continue to explore more examples, patterns and implementation techniques. Oracle official documentation is also linked out where appropriate.

Using https://cloud.oracle.com you can sign up for a free 30-day trial account or purchase your account of Java Cloud Service. Note that on https://cloud.oracle.com there are multiple offerings of Java Cloud Service to suit different requirements. Oracle Java Cloud – SaaS Extension is an offering specifically tailored for building SaaS Extensions. All references to Java Cloud Service in this post refer to this offering. It will be abbreviated as JCS-SX going forward.

Whenever JCS-SX trial instance is provisioned, an associated Database Cloud Service-Schema instance is also provisioned automatically. This is the only database instance JCS-SX can work with.  If you purchase your JCS-SX instance (instead of a trial) you will be required to purchase a Database Cloud Service-Schema instance and then associate it with your JCS-SX instance. Every JCS-SX instance can work with only one DbCS instance.

Note: Similar to providing multiple Java Cloud Service offerings, Oracle also provides multiple Oracle Database Cloud offerings to suit different requirements. To work with JCS-SX you will be using the Database Cloud Service-Schema offering, which will simply be referred as DbCS going forward.

A Worked Example

To illustrate one usage of JCS-SX with Sales Cloud, consider the banks example discussed earlier. One requirement could be that a bank branch manager should be able look at a ‘transaction profile’ UI linked off Sales Cloud Accounts screen to understand what additional products he/she can sell to a given customer. Assume that the monthly average balances of all customers are available as a flat file and is imported into the Database Cloud Service. Using JCS-SX a Java application can be built to display the account balances of a customer over different periods. As the bank manager navigates to this Java application from the context of a customer in Sales Cloud, the account balances of that customer will appear. In addition to viewing the balances, the application could also display contextual information of the customer, from Sales Cloud, such as address of the customer. The Transaction profile UI can be embedded within or linked off from the Sales Cloud UI. This scenario can be represented below.


From an implementation perspective, the scenario can be broken down as follows.

  1. Creating Database model and loading data to DbCS
  2. Building the Transaction Profile application on JCS-SX to displays data from DbCS
  3. Enhancing the application to invoke SOAP web services in Sales Cloud to display contextual data
  4. Configuring Sales Cloud to launch the application from the accounts screen
  5. Configuring a Security mechanism

Creating Database Model and Loading data to DbCS

In this example, it is assumed that the monthly average balances of customers are available as CSV files on a periodic basis. This data has to be loaded to your DbCS instance prior to displaying it on your JCS-SX instance. Prior to uploading data you need to build a data model in your DbCS instance to host the transaction data to be uploaded. You can build your data model directly on DbCS or you can use the database cart feature to transfer a data model from your development environment using Oracle SQL Developer or Oracle JDeveloper. Steps to use database cart are available here within Oracle documentation.

Since the monthly balances data is available only once a month, it can be assumed that this data upload task is performed manually using the DbCS console or through the Database Cart feature available with SQL Developer. Since in this example the data is available as CSV, assuming that the data is of reasonable volume, we will use the visual interface provided by DbCS to upload data as CSV files. A summary of steps required to manually upload data along with other data upload options is discussed in this blog post

Building an application on JCS-SX to display data from DbCS

You will perform Java Application development in your local environment using an IDE such as JDeveloper, Eclipse, or Netbeans. DbCS (the specific offering you use with JCS-SX as noted earlier) does not provide JDBC access. Therefore, the data model has to be replicated locally in a database that is accessible through your IDE for Java development. If you were using the Database cart to create a data model, you already have this data model in a database. Otherwise, create the data model manually in a database.

Now, you will follow the standard Java application development process to create an application based on the data model in your local database. If you are using Oracle ADF for development, you will be creating EOs and VOs based on your local database objects. Complete building your application. Test the application in your local environment. If you are using JDeveloper, you can use the Integrated Weblogic Server that comes with your JDeveloper for testing.

Note: You can assume that the Customer ID (party ID in Sales Cloud) of the customer for which the data is to be displayed is available as an URL parameter when this application is launched from Sales Cloud.

To prepare the application for deployment to JCS-SX you need to adjust a few things.

  • Ensure that Oracle Cloud technology is added to your project technologies.
  • In your application’s deployment profile, ensure that the default platform is set up as Oracle Cloud.
  • Do not secure your application for Authentication and Authorization at this point (just for this example). Simply add an empty <login-config/> to your web.xml to leave your application unauthorized.
  • From your JCS-SX console, obtain the DataSource JNDI location value and use that in your application.

Your application is ready to be deployed to JCS-SX. Create a Cloud connection from your IDE and deploy your application. As an alternative, create an EAR and deploy the application using the JCS-SX console. Once deployed, you should be able to launch and test the application using the JCS-SX console.

Enhancing the application to invoke SOAP web services in Sales Cloud to display contextual data

You can now enhance the application to display the name and address of a particular customer in addition to displaying the transaction data from DbCS. As discussed earlier, assume that the Customer ID (Party ID) is available for you as a URL parameter.

To retrieve the customer information you can build a Web Service proxy to access the Sales Party Sales Cloud SOAP service. Alternatively, you can also use a Web Service Data control (WSDC) to access a web service. Step by step implementation details for both options are provided in this blog.

The above blog reference does not discuss the scenario where the Party ID is available as a URL parameter. When using ADF, this can be achieved by extracting the URL parameter as a PageScopeFlow parameter and using it subsequently in the proxy (or the WSDC). The blog reference also uses user name token to authenticate against the web service. Towards the end of this blog we will discuss other security options.

Once the proxy or WSDC creation is complete and the appropriate UI widgets are created, test the application on your local environment and deploy it to JCS-SX.

Configuring Sales Cloud to launch the application from the accounts screen

Next, this application should be invoked from Sales Cloud within the context of a particular Account. This application can either by launched through a link or can be embedded into the Sales Cloud Screens. For the purpose of this example, let us assume that we will simply use a link to launch the JCS-SX application.

To implement this in Sales Cloud, the Application composer tool will be used. Create a new Link item under the Standard Account object. In the URL definition section, use groovy script such as below.

def partyid= PartyId
def url = <jcs-sx_app_url> + “?” + “partyId=”+ partyid
return (url)

Click on Pages and select the Simplified Tab. Choose the appropriate page layout and add the Link item that was created. You should now be able to launch the JCS-SX URL along with the current PartyId (customer ID) available as a URL parameter.

Configuring a Security mechanism

In this scenario, there are two main areas of security. First is to secure the JCS-SX application itself and second is the application being able to authenticate against the Sales Cloud web service.

If you secure your JCS-SX application for authentication, then when you launch the UI from Sales Cloud, you need identity federation between the Sales Cloud and JCS-SX to launch your JCS-SX application without prompting for username and password. In this example, we will not secure the application. Instead we will use a JSON Web Token (JWT) based authentication to achieve a similar behavior.

We will use JWT as illustrated below:

A JWT is generated in Sales Cloud using groovy APIs and other mechanisms (step 1 in the figure above) and is passed to the JCS-SX application as an URL parameter along with the PartyId (step 2). Since all Sales Cloud SOAP web services are protected with an OWSM policy that honors a JWT token, the JCS-SX application uses the JWT token to authenticate against the Sales Party web service on Sales Cloud (step 3). As discussed earlier, in this pattern the JCS-SX application itself is not secured for authentication/authorization. However, this does necessarily make the application unsecured. If someone attempts to launch the application URL without providing a JWT token or using an incorrect JWT token, it will not launch successfully since the application will fail to authenticate against the Sales Cloud web service on page load (assuming it is designed to invoke the web service on page load). The JWT –based authentication is described here in more detail.

Note that this is not the only security pattern that Oracle supports. Additionally, Oracle is actively enhancing its cloud applications. So watch out this space to learn about security-related enhancements as they are delivered.

Update Jan 2018: Starting 2016 Oracle supports SAML between Sales Cloud and JCS-SX provided these services are in the same ID domain. JWT based authentication is not supported. If you are using JWT tokens Oracle Highly recommends that you migrate IMMEDIATELY to SAML based pattern.

Please refer to documentation and sample code at https://docs.oracle.com/en/solutions/index.html



As discussed earlier there are many reasons to use JCS-SX to extend Sales Cloud. There are several patterns for Sales Cloud – JCS-SX integration and the example above provided a quick summary of one pattern. As you explore this blog space and further Oracle documentation you will find several other patterns that may suit your requirements.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha