Oracle CX Commerce Integration

Oracle CX Commerce self-service users can access an Oracle CPQ site as guest users via an iFrame that displays within Oracle CX Commerce. When an Oracle CPQ site is accessed by a Oracle CX Commerce self-service user, session parameters are passed from Oracle CX Commerce to CPQ. This provides a seamless user experience and eliminates the need for Oracle CX Commerce self-service users to enter login credentials when entering an Oracle CPQ site from Oracle CX Commerce.

Session parameters include currency, language, and locale preferences such as number format, units, and date format. For example: If a Oracle CX Commerce self-service user’s language preference is set to German, the text in the Oracle CPQ interface displays in German when the user accesses CPQ. The user’s currency and locale preferences are also passed from Oracle CX Commerce and display in CPQ.

The “Add to Cart” action sends items to a Oracle CX Commerce cart via an Add to Cart button, which displays on the Oracle CPQ interface following configuration. A “Client Side” integration type is available in Oracle CPQ and enables the sharing of data between Oracle CPQ and Oracle CX Commerce. Oracle CPQ administrators must configure a “Client Side” integration to add the Add to Cart button on an Oracle CPQ site.

Oracle CPQ administrators must also add payload template files to File Manager. The template files support the “Add to Cart” action and include simple configuration information such as config id, quantity, part, and model name. BML reads these template files and replaces the values in brackets, such as {{quantity}}, with dynamic values.

To add items to a Oracle CX Commerce cart:

1. The Oracle CX Commerce administrator adds a Customize button to a Oracle CX Commerce site.

The Customize button is shown below and is part of the Oracle CPQ – Oracle CX Commerce integration.

2. A Oracle CX Commerce self-service user clicks Customize.

The Oracle CPQ Model Configuration page opens within an iFrame in Oracle CX Commerce and contains the Add to Cart button.

3. From the Oracle CPQ Model Configuration page, the Oracle CX Commerce self-service user customizes the laptop order and clicks Add to Cart. As shown in the following figure, the Oracle CX Commerce cart is then updated based on the specified customizations.

After a Oracle CX Commerce self-service user adds an item to a Oracle CX Commerce cart, the user can return to the shopping cart and edit the details of the items in the shopping cart. All of the Oracle CPQ configured parts that display in the “Details” area of the shopping cart are recommended items.

To edit a Oracle CX Commerce cart from CPQ:

1. Open the Oracle CX Commerce cart.

2. Click Edit.

The Oracle CPQ Model Configuration page opens within an iFrame in Oracle CX Commerce.

3. Update the Oracle CX Commerce shopping cart.
4. Click Add to Cart.

The Oracle CX Commerce shopping cart opens and displays the updates.

A Oracle CX Commerce self-service user can select a Request Quote option in Oracle CX Commerce to obtain a quote from an Oracle CPQ sales specialist. The high-level steps related to requesting a quote are provided below. For additional information, refer to the Integrating Oracle CX Commerce and Oracle CPQ Implementation Guide.

To request a quote:

1. The Oracle CX Commerce self-service user selects Request Quote from the Oracle CX Commerce Create Order page. The Request Quote page opens.
2. From the Request Quote page, the Oracle CX Commerce self-service user has the option of entering a message for the Oracle CPQ sales specialist. For example: The user could enter a message requesting a 15% discount.
3. When the Oracle CX Commerce self-service user clicks Request Quote, an order ID is assigned to the order and the quote request is sent to an Oracle CPQ sales specialist. The Oracle CPQ sales specialist can view the order ID in the last column of the Oracle Quote to Order – Manager page.

4. The Oracle CPQ sales specialist can then use the Transaction page to modify the pricing on the quote. Using the Sync Quote action, the Oracle CPQ sales specialist can update the associated Oracle CX Commerce order.

5. The order is updated in Oracle CX Commerce, and the Oracle CX Commerce self-service user has the ability to accept or reject the proposal or request another quote.

Beginning in Release 18B, Oracle CPQ supports the retrieval and display of eCommerce usage metrics related to the number of times the Oracle CPQ Model Configuration page is accessed from Oracle CX Commerce (i.e. the number of interactions).

Oracle CPQ customers have the option to pay for our service based on the number of licenses available for the site or the number of user interactions. For customers who integrate with Oracle CX Commerce, the majority of configurations are performed by unregistered users. As a result, tracking usage by license count does not properly reflect usage. This feature addresses this scenario and supports Oracle CPQ customers who pay for our service based on the number of interactions that occur by any user.

For more information refer to the following:

• Use a REST API to Retrieve Interaction Data
• View Interaction Data in CPQ
• View Interaction Data in the Oracle Cloud Portal

When Oracle CPQ is integrated with Oracle CX Commerce, there are setup steps that administrators must complete in both applications before exposing a product in the Oracle CX Commerce interface. In prior releases, Oracle CX Commerce was not notified when models in Oracle CPQ were ready for Configuration. As a result, Oracle CX Commerce had no automated way of knowing when to expose the Configure action on the Oracle CX Commerce storefront.

Oracle CPQ makes a REST call to Oracle Integration Cloud Service (ICS) when products are available for Configuration and ready to sell in the Oracle CX Commerce storefront. Oracle CX Commerce administrators can subscribe to ICS to receive these notifications automatically.

Model Administration Settings

Self Service Integration Type

The "Add to Cart" action sends items to a Oracle CX Commerce cart via an Add to Cart button, which displays on the Oracle CX Commerce integrated Oracle CPQ site following configuration. When implementing the Oracle CX Commerce integration, administrators must add the following payload template files to File Manager: AddToCartPayload-Cloud.txt, Attributes_Payload.txt, and Recommended Items Payload.txt.

The template files support the "Add to Cart" action and form the payload structure for sending a configured item to a Oracle CX Commerce shopping cart. BML reads the payload template files and replaces the values in brackets, such as {{bomitems}}, with dynamic values.

Oracle CX Commerce integration provides support for BOM Mapping Rules in SOAP API responses. The Configuration configure SOAP API returns data related to creating or reconfiguring a model in a Transaction. The Configuration getConfigurations SOAP API returns data related to adding items to a Oracle CX Commerce cart using the "Add to Cart" action.

Sample Input SOAP XML with "bomMapping"

When the XML input "bomMapping" property is set to "true" the SOAP API response includes a "bomMapping" section, which includes the same kind of data that is visible to administrators when in the Pipeline Viewer (e.g. partNumber, quantity, and price).

Sample Response with "bomMapping" Section

For more information to SOAP Configuration API.

Many customers price configured items with market based pricing, meaning the price of the configured items are based on a final price as opposed to the composite price of the components. In a configured item, Configuration choices may alter the original "base" price. Administrators can use an Included in Base Price column in the BOM Item Definition table to specify the BOM items to include in the base price, distinguishing them from optional items that alter the price.

For example: A model may have certain BOM items that are intended to be free of charge for a specific Configuration. Administrators can mark these items as Included in Base Price, allowing the inclusion of the item with the model without adjusting the model's base price to accommodate for it. The Included in Base Price indicator can also be used to more easily calculate delta prices.

The variable name (i.e. includeInBasePrice) for the column is a string that acts as a Boolean.

• If the Included in Base Price column is set to "y", the price for the item displays as blank when listed individually in any BOM item section that includes prices, including:
  • getConfigurations SOAP API
  • configure SOAP API
  • getConfigBom BML

  • Model Configuration page

    Note: When the Included in Base Price column is set to "y", the prices in Commerce display as 0. The prices in Configuration display as blank.
• Everywhere in Commerce (i.e. REST, BML getbom, and UI)
• If the Included in Base Price column is set to "n", the price displays as in prior releases.
• The price for the item displays as the price from the Parts database or the calculated price from the Pricing function.

The "Configuration ID" system attribute is strictly for "Client Side" integrations. Users generate the "_configuration_id" when invoking Commerce or performing the "Add to Cart" action.

As shown below, the Configuration ID displays in the interface when Oracle CX Commerce self-service users create a new Transaction.

Administrators can view the configuration information associated with a Transaction by entering the "configurationId" associated with a previously generated Transaction into the getConfigurations SOAP API request.

Sample Input SOAP XML with "configurationId"

When a "configurationId" is provided in the input XML for the getConfiguration SOAP API, the response provides all of the configuration information associated with a Transaction, including attributes and BOM data.

Sample Response for "configurationId"

The ICS Oracle CX Commerce-Oracle CPQ Create Quote integration flow uses the Configured Items API call to simplify the process. The Configured Items API call uses a single API call to create a Transaction with one or more configured items.

For more information on the ICS Oracle CX Commerce-Oracle CPQ Create Quote integration refer to:

• Integration Cloud Service (ICS) topic
• The Oracle Cloud Integration web site
• Integrating Oracle CX Commerce and Oracle CPQ Implementation Guide

The Request for Quote flow allows Oracle CX Commerce self-service users to request an Oracle CPQ quote, thereby initiating an Oracle CPQ Transaction that a sales specialist can modify, reconfigure, or discount. Once finalized in CPQ, the quote returns to Oracle CX Commerce for acceptance and ordering by the self-service user. Oracle CPQ provides a REST API Adapter for ICS, allowing the Oracle ICS integration with Oracle CX Commerce to use REST services for the Request for Quote flow.

The following functionality is available when creating a new Transaction via REST services:

• Perform a Modify action
  • An optional "_modify_action" property for the Create Transaction API allows a Transaction to be saved once created.
  • If the "_modify_action" property is not included in the request, the REST service still creates the Transaction. No additional action runs.
• Add models to a Transaction
  • Define an optional property for "_configuration_id" to add one or more models to a Transaction.
  • If a "_configuration_id" is included in a request for a new Transaction, the response is the Transaction data. Included in the Transaction data is line level data for the model.
  • A model in a generated Transaction only has a "_configuration_id" when the Product Family's integration type is "Client Side".
• Define "_price_list_price_each" and "_price_net_price" as line item system attributes
  • Line item attributes support all fields from the Price Attribute set.
  • Price Books cannot be defined for models but can be defined for parts.
• Set the following main doc and sub doc attribute types for new Transactions
  • Date
  • Text Field
  • Menu
  • Integer
  • Float
  • Boolean
  • Currency
  • Text Area
  • Phone (in an Address Set)
  • Country (in an Address Set)
  • State (in an Address Set)
  • Zip (in an Address Set)

URL Endpoint Sample

https://sitename.oracle.com/rest/v16/commerceDocumentsOraclecpqTransaction/actions/_new_transaction

Sample Request

{
   "_modify_action": "cleanSave_t",
   "documents": {
      "_currency_pref": "USD",
      "customTextMainDoc": "sample text",
      "_customer_t_company_name": "Oracle",
      "_customer_t_first_name": "Kim",
      "_customer_t_last_name": "Anderson",  
      "transactionLine": {
         "items": [ {
            "_configuration_id": 36467201,
            "customTextSubDoc": "Laptop"
         } ]
      }
   }
}

Use the eCommerce Interaction Metrics REST API to retrieve usage data related to the number of times the Oracle CPQ Model Configuration page is accessed from Oracle CX Commerce. Each instance is an interaction representing usage data. Interactions are generated by all users, regardless of company or access type. Oracle CX Commerce self-service users do not need to invoke the Add to Cart action for an interaction to count as usage metric data.

Refer to the REST API for eCommerce Interaction Metrics for API details.

The below table identifies interaction scenarios both included and not included in metric data.

Host Company Full Access users with permission to create and modify users can view eCommerce interaction data on the User Administration List page. The eCommerce interaction data represents the number of interactions performed on the Oracle CPQ site in the current month.

To view interaction data in CPQ, perform the following steps:

1. Open the Admin Home page.

2. Under Users, select Internal Users.

   The User Administration List page opens and displays eCommerce interaction data. The customer is billed for the monthly allotment amount, which is a specific number of interactions per month. The number of interactions used by the customer from the beginning of the month to the current date also displays. The value is updated each time the page is opened.

Customers can use the eCommerce Interaction Metrics REST API to view daily interaction metrics from the Oracle Cloud portal, which bypasses the need to access Oracle CPQ directly to view metric data. The daily interaction metrics display in the Oracle Cloud portal automatically. There is no administrator setup required.

Beginning in Release 18C, Oracle CPQ provides an "Authentication Certificate" integration type in the Integration Center to support access token-based authentication. This integration type allows Oracle CX Commerce self-service users to securely access Oracle CPQ to modify or reconfigure a ABO asset-based Configuration without an Oracle CPQ user session.

When administrators create a new integration of type "Authentication Certificate", they provide a name and variable name for the authentication certificate and upload the Oracle CX Commerce authentication certificate. A temporary session is created for the Oracle CX Commerce self-service user, allowing the user to access the Model Configuration page via an iFrame within Oracle CX Commerce to modify or reconfigure a specific asset.

To create an Authentication Certificate integration type, perform the following steps:

1. Open the Admin Home page.
2. Select Integration Center under Integration Platform.
   The Integration Center opens.
3. Click Create Integration.
4. From the Type drop-down, select Authentication Certificate.
5. In the Name field, enter a name that describes the authentication certificate. For example: Oracle CX Commerce
6. The Variable Name field auto-populates upon clicking in or tabbing to the field.
7. (Optional) In the Description field, enter a description of the authentication certificate.
8. Click Browse next to the Authentication Certificate label.
9. Select the Oracle CX Commerce authentication certificate and click Open.

10. Click Save.
    The "Authentication Certificate" integration appears in the left pane of the Integration Center.

    

Beginning in Release 18C, ABO line level action codes and system configuration systems are available in the Add to Cart payload. The line level action codes allow Oracle CX Commerce self-service users to perform a Modify action to update an asset and send the associated Add, Update, or Delete action to Oracle CX Commerce. Oracle CX Commerce self-service users can also add tiered systems with models and child models to the Oracle CX Commerce shopping cart.

Every model in Oracle CPQ corresponds to a product in Oracle CX Commerce. To configure a model or child model, Oracle CX Commerce self-service users can securely access the Oracle CPQ Model Configuration page via an iFrame that displays within Oracle CX Commerce. Using the system navigation panel available in Oracle CPQ Release 18C (a System Configuration enhancement), Oracle CX Commerce self-service users can view the hierarchy and state of each model in a system. They can then choose a system model or child model to configure and use the Add to Cart action to update the Oracle CX Commerce shopping cart with the system model or child model. The ability to reconfigure tiered systems is also supported.