README for Oracle Cloud Integration Sample

Sample Name

Quote statistics

Author

Kaushal Joshi

Source Code Location

Oracle Cloud Products Involved

Demonstrates

This sample demonstrates the following aspects of Oracle cloud integration:

Primary Goals

Secondary Goals

Functional Overview

This application allows sales users to get certain analytic information to help them make key decisions about the quote they are generating. The application is invoked from the CPQ Cloud opportunity screen, and customer information is passed to it. The application will then consume data via the CPQ Cloud REST APIs to generate information (in this case, provide the average net total across quotes for this customer) which is then displayed on the CPQ opportunity screen. Sales users may use this information to make adjustments to maximize conversion potential. Although a simple statistic is calculated, this application can be extended.

Technical Overview

The application's main UI is a JSP page, which displays the relevant statistic as text. This page is invoked by having the application URL set as the source of an IFrame on the opportunity screen, via a CPQ Cloud commerce HTML attribute. When the application loads, a 3-legged OAuth flow is initiated by the application with CPQ Cloud OAuth Provider, resulting in generating an access token that allows the application to call the Transaction REST API for CPQ Cloud on the same instance.

Initially, when the opportunity page loads, the application receives the business logic parameters necessary as input to calculate the statistics. These paraemters are: customer name, CPQ server URI, commerce resource name, current quote id. However, the application would not have the access token that allows it to call CPQ Cloud REST API to fetch data in order to calculate these statistics. For the purpose of negotiating an access token, the JCS - SaaS Extension sample also has code that performs the 3-legged OAuth flow. The application kicks off the 3-legged flow (specfically, the "authorization code grant" flow) to negotiate an access token with the CPQ Cloud Authorization server. This flow takes place via the front-channel (browser redirects); a cookie is used in the background to remember the original application resource url requested. This flow, if successful, binds the token to the original URL as a query  parameter, and finally redirects to the original application URL. The JCS - SaaS Extension application resource requested can then use the access token as a Bearer token to invoke the CPQ Cloud Transaction API to collect the information it needs and displays it on the JSP page.

For being able to negotiate an access token, an OAuth client is registered with the CPQ Cloud OAuth server via its client endpoint. The client key, id, and secret obtained this way are made available to this JCS - SaaS Extension application code. During the runtime 3-legged flow, the OAuth redirect endpoint on the JCS - SaaS Extension receives the authorization code generated by the CPQ OAuth server and negotiates the access token, redirecting to the original application URI with the the access token in the final step.

Note: This sample demonstrates how to secure authorization to the embedded JCS-SaaS Extension web application using the SSO session. For this to work, the IDP that your CPQ instance uses for SSO should be already federated with Oracle PaaS. Detail on this is not in the scope of the sample and the SSO aspects of your environment are expected to be pre-determined.

Disclaimer

All sample code is provided by Oracle for illustrative purposes only. The objective of this sample is only to demonstrate the goals defined above and may not represent other best practices, functional or technical.These sample code examples have not been thoroughly tested under all conditions. Oracle, therefore, cannot guarantee or imply security, reliability, serviceability, or function of the sample code. All sample code contained herein are provided to you “AS IS” without any warranties of any kind. The implied warranties of non-infringement, merchantability and fitness for a particular purpose are expressly disclaimed.

User and Role Setup

For Setting up the Sample

  1. A user with the Java Administrator Role is required to deploy an application to the JCS - SaaS Extension instance. Refer to Getting a JCS - SaaS Extension Subscription for more details about the Java Administrator Role. Refer to Chapter 7, "Managing Users and Roles" in Getting Started with Oracle Cloud for more details on creating users.
  2. For CPQ Cloud setup, use an existing user of type FullAccess. Refer to Understanding Your CPQ Cloud Customization and Integration Features for more details on one way to administer the CPQ experience for this sample.

For Running the Sample

  1. For CPQ Cloud, create a new user of type Sales Agent, or use an already existing user of that type. Refer tor Understanding Your CPQ Cloud Customization and Integration Features for more details. As an alternative, use a Full Access user like you did to set up the sample.
  2. Use the Transaction Manager to create new quotes and access an existing quote and run the sample as per the CPQ experience you set up via the administration features.

Install Instructions

JCS - SaaS Extension

  1. Clone git repository to your local working directory
  2. Set up the contents of /JCS-SX folder as a web application, to generate a WAR. To see JDeveloper specific instructions for this step refer to the next sub-section "For JDeveloper Users".
  3. Register an OAuth client with the CPQ Cloud OAuth server as explained in the topic "Registering an OAuth client with  CPQ Cloud OAuth Server" (This topic is available under "Additional information" towards the bottom of this README). Note the clientKey, clientId, clientSecret and redirectUri of the registered client.
  4. In the source packet, find CPQTokenConstants.java and edit it to set the following constants:
    • OAUTH_CLIENT_KEY: set this to clientKey value
    • OAUTH_CLIENT_ID: set this to clientId value
    • OAUTH_CLIENT_SECRET: set this to clientSecret value
    • OAUTH_CLIENT_REDIRECT_URI: set this to the redirectUri value
    • CPQ_HOST: set this to the CPQ base uri of the CPQ instance that you registered the client with.
  5. This step may or may not be applicable to you. Does your CPQ instance have the REST collection resource named "commerceDocumentsOraclecpqoTransaction" ? Refer to Identifying CPQ Cloud RESTful Web Services to Invoke from a JCS - SaaS Extension Application for more details on how to find information about REST resources on your CPQ Cloud instance.
    1. If yes: Do you see the fields "_transaction_customer_t_company_name", and "totalOneTimeNetAmount_t" in the response objects when you do a GET on this resource ?
      • If yes: Skip remainder of this sub-section and proceed to the next step.
      • If no: Change the sample code per the topic "Customizing the sample to work with a difference commerce resource" in the Additional Details section towards the end of this README.
    2. If no: Change the sample code per topic "Customizing the sample to work with a difference commerce resource" in the Additional Details section towards the end of this README.
  6. Save and compile the web application, and package it as a WAR. To see JDeveloper specific instructions for this step refer to the next sub-section "For JDeveloper Users".
    • In addition to the Java provided dependencies, use the Dependencies topic below, to understand the dependencies for compile-time and runtime; you will have to download these dependencies; they are not provided along with the sample code.
  7. Deploy the application to your JCS - SaaS Extension instance. Refer to Deploying Applications Individually Using JCS - SaaS Extension Control for more details.

Note: Client credentials should be stored securely, similarly to how user credentials would be stored. The constants in this sample only serve to demonstrate the setup, and are not the recommended way of storing such information.

For JDeveloper Users:
  1. Create a web project in a new generic application or existing application.
  2. Setup the application resources
    • Select the project in Application Navigator and click on File and select Import. In the Import popup select "Web Source" and click OK to bring up Web Source popup. Click "Copy From:" browse button, navigate to cloned git repository in your working directory and select public_html folder. Click OK to close the "Web Source" popup.
  3. Setup the source to compile
    • Open the Import Popup again like in step 2 and select Java Source. Select the src folder from the cloned repository by clicking on browse button of "Copy From:" option. Click OK.
  4. Setup dependencies required to compile and package
    • Right-click on the header of the project, and select "Project Properties" from the popup menu. In the Project Properties dialog box, select "Libraries and Classpath" in the left pane. This will reveal a list of classpath entries. For a Web project JSP Runtime should already be available, if not, click "Add Library..." and add it from the list. Next Click on the "Add JAR/Directory...", to add the dependency libraries (Users are required to download dependency libraries from external sources. They are not packaged with the sample apps. Please refer the table below for list of libraries). Click OK to close the project properties dialog box and then click Save.
  5. Before this step, you will need to follow step 3 through 5 of the above section that explains the general install scenario. Then, build the project and ensure there are no errors.
  6. Go the project properties again. Select "Deployment" section in the left pane. Delete the default war under "Deployment Profiles:" if any. Click on "New...". Select WAR File from "Archiver Type:". Give a meaningful name and click OK to navigate to "Edit WAR Deployment Profile Properties". In the right pane give the suitable location of war file and leave the remaining as they are. In the left pane select "Library Dependencies". Right pane shows all the libraries that were added in point 4. Leave JSP Runtime selected and select the remaining as given in table below. Delesect the others. Click OK to close the dialog boxes and click save to save the changes.
    • If you do not see a WAR option in the Archive Type, you are probably looking at Application Properties, instead of Project Properties as suggested by the step.
  7. Right click the project and select "Deploy" > "warfile". In the popup, select "Deploy to WAR", click Next and Finish to generate a war file.
  8. Note that JDeveloper may inject a weblogic.xml in the WAR, with a <context-root> element that is set to a value you chose in step 6. This will determine part of the URL you will need to use when plugging in the sampleURI value in step 3 of CPQ Cloud setup later on in this README.

Dependencies

The following table lists the libraries that are necessary in order for this sample application to work correctly. These are not provided along with the sample app, but will be necessary for compiling and running the application succesfully.

Dependency Library Purpose Compile-time Runtime Provided in JCS-SaaS Extensions runtime environment as a shared library
Jersey bundle 1.9 For handling RESTful services Yes Yes Yes
Jettison 1.3 For JSON data structures Yes Yes No
Apache Commons Codec v1.4 For url safe base64 encoding utility Yes Yes No
Apache Commons Lang v2.0 For HTML unescape utility Yes Yes No

CPQ Cloud

  1. Log in to the CPQ Cloud instance as a full access user.
  2. Next, set up the CPQ experience for this sample as explained in the following steps.
    • For the next few steps, use the commerce process "Oracle Quote to Order" (variable name oraclecpqo), unless you choose to customize the code to use a different transaction resource than commerceDocumentsOraclecpqoTransaction, in which case locate the commerce process with the help of the variable name of the transaction resource. Refer to Identifying CPQ Cloud RESTful Web Services to Invoke from a JCS - SaaS Extension Application for more details on how to find information of the REST Resource of interest.
  3. Set up a commerce transaction attribute that can be seen in the transaction layout, and configure it to render an Iframe in which to embed the JCS - SaaS Extension application page.
    • To do this, in the admin console, use the Commerce and Documents section link to go to Process Definition. Select one of the process(es) listed, and navigate to its documents. Next, at the top level (also called Main) document, navigate to the attributes list. Click the Add button at the bottom of the list and proceed to add a new attribute of type "Read-only text or html"; enter variable name attr_sampleIframe.
    • Click "Add", to add the attribute. After this you will be presented a page that allows you to edit the attribute details. In this page, choose the "Default" tab, and go for the "Function" option. Click on "Define Function" to write a BML script that will generate the HTML for this iframe. Follow the next few steps to set up this BML appropriately.
    • In the new BML function popup, select input attributes. Select the following items: (you can come back to this screen by clicking on "Reselect" on the script screen)
      • _system_buyside_id ("System variable name" tab)
      • _transaction_customer_t_company_name ("Variable name for transaction" tab) - Note: if you chose to customize your sample (see topic "Customizing the sample to work with a difference commerce resource" in the Additional Details section towards the end of this README ) , select that particular field here.
    • Copy/paste content of the bml_iframeAttribute.txt,
      • Plugin the URI of your JCS - SaaS Extension web application in the string constant sampleURI
      • Plugin the name of the CPQ Cloud instance for the placeholder {CPQ-base-uri}
      • Note: if in the previous steps you chose to use a input parameter other than _transaction_customer_t_company_name, you will need to change its references in the BML. i.e. replace the value of the url parameter 'custId' accordingly.
    • Save and close.
    • We will refer to this as attr_sampleIframe.
  4. Add attr_sampleIframe to the transaction layout.
    • Go to Process Definitions, and in the main document dropdown, navigate to the Desktop Layout. Using the add menu on the top, click Add Attributes. Find the attribute and drag it to an appropriate position in your layout. (Since it is related to statistics associated with a customer, perhaps the customer detail section may make sense, if available).
    • Click preview, and if acceptable, save the layout. At runtime, this attribute will render per the HTML we scripted earlier (i.e. IFrame)
  5. If you have not done so, register an OAuth client with the CPQ Cloud OAuth server as explained in the topic "Registering an OAuth client with  CPQ Cloud OAuth Server" (This topic is available under "Additional information" towards the bottom of this README).
  6. Ultimately, the changes made to commerce need to be deployed to be actually made "live" to the end user. To achieve this, deploy the commerce process and ensure that the deploy is successful

Running the Sample

To run the sample Launch the CPQ Cloud application in your browser.

  1. Login as a user who is of the Sales User type.
  2. Once you are logged in, you will see a navigation bar that will allow you to go to the transaction manager of the commerce process we set up earlier. Click it and you'll see the list of quotes available. A "New Transaction" button should be available too. Either select an existing quote OR create a new transaction (quote), and you'll be redirected to the transaction layout.
  3. Find the attr_sampleIframe IFrame (per where you added it) in this layout. You will see one of the following types of messages:
    • 'This customer has been quoted <##> other similar quotes with an average net price of  $'
    • 'No similar quotes found for this customer' - This means the Customer Company Name attribute of your transaction is not populated, OR this is the only transaction with that particular Customer Company Name value.
      1. For other transactions to be 'selected' in the dataset while calculating the statistic for the open transaction, the Customer Company Name attribute (_transaction_customer_t_company_name) of the open transaction is used as a matcher. To locate where this attribute is available on the transaction UI, you can edit the attribute in the commerce definition (as an admin user) and look at its Desktop Layout path. In your CPQ Cloud instance, this attribute may or may not have been set up to be auto-filled. If this attribute has no value, you will have to manually set its value using the transaction UI.
    • -- could not fetch data --  - This means there was a problem on the JCS - SaaS Extension application while trying to fetch data from CPQ Cloud. Ensure you followed the steps above.
  4. You can create more transactions for a given customer and see how the IFrame content for a given quote changes.

Note:

Additional Information

Customizing the sample code to work with a different commerce resource

If either the REST collection resource "commerceDocumentsOraclecpqoTransaction" or one of its fields "_transaction_customer_t_company_name" or "totalOneTimeNetAmount_t" is not available in your CPQ Cloud instance, you will need to modify some sample code to customize for the resource and/or fields that are available to you.

  1. Resource name: Locate the REST resource you want to use. That should be a Commerce Transactions type resource.
    • Plug the name of the resource into the DEFAULT_RESOURCE literal in CPQConstants.java
    • In the bml_iframeAttribute.txt file included in the package, replace the value of  'resourceName' url parameter with the same string.
  2. Customer company name: Determine one field of this transaction resource that is used to store the "name of the customer"
    • In CPQConstants.java, plug the name of this field into the FLD_CUST literal.
  3. Net amount: Determine one field of this resource that is conceptually similar to "Net price of the quote"
    • In CPQConstants.java, plug the name of this field into the FLD_NET_PRICE literal.

Registering an OAuth Client with the CPQ Cloud OAuth Server

Refer to Configuring CPQ Cloud to Act as an OAuth Server for information on using CPQ Cloud as OAuth Server, and for steps on how to register a client for your PaaS-SX application to use for accessing CPQ Cloud REST API.

An example using curl on LINUX to create a client for the sample application is below. Credentials of a CPQ Cloud full access user should be used for basic authorization for using this api.

cat>/tmp/MyClient.json << __EOF__

{ "clientKey": "PAAS_SX_CPQ",

   "name": "Client",

   "description": "Client for accessing CPQ Cloud Service API from PaaS-SX",

   "redirectUri": "https://{JCS-SX-baseURI}/{Deployed application name}/jersey/clientRedirectEndpoint/PAAS_SX_CPQ",

   "grantType": "AuthorizationCode",

   "expires":3600

}

__EOF__

curl -H "Authorization: Basic <base64encoded username:password>" -H "Content-Type: application/json" -X POST --data @/tmp/MyClient.json {CPQ-base-uri}/rest/v1/clients

If succesful, the above request will respond with a HTTP 200 OK and the client object in JSON format.

Visit the Samples Solution Website

For more details about this sample and other related samples, refer to Oracle Cloud Solutions at https://cloud.oracle.com/developer/solutions.

Uninstall Instructions

JCS - SaaS Extension

Undeploy the application from JCS - SaaS Extension. Refer to the Undeploy section in Deploying Applications Individually to JCS - SaaS Extension for more details.

CPQ Cloud

Delete the attribute attr_sampleIframe and redeploy the commerce process.

Documentation

To learn how to further extend this sample, explore other implementation options, or develop your own application following a similar implementation pattern, visit the Quote Statistics Solution page in the Oracle Cloud Developer Portal.

Known Issues

Copyright © 2016, Oracle and/or its affiliates. All rights reserved.