Oracle CX Commerce Integration

Overview

Oracle CPQ provides an integration between Oracle CPQ and Oracle CX Commerce. Self-service users in Oracle CX Commerce can configure complex products for purchase in Oracle CX Commerce using the Oracle CPQ configurator. In addition, Oracle CX Commerce self-service users can 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 is returned to Oracle CX Commerce for acceptance and ordering by the self-service user. The integration of Oracle CPQ with Oracle CX Commerce uses the Oracle Integration Cloud Service (ICS) to provide pre-built integrations for the two user flows.

The integration provides the following functionality to Oracle CX Commerce self-service users:

ClosedAccess an Oracle CPQ Site as Guest Users

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.


ClosedAdd Items to a Oracle CX Commerce Cart from 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.

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

  1. 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.

 Model Configuration page

  1. 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.

Oracle CX Commerce cart is then updated based on the specified customizations


ClosedEdit a Oracle CX Commerce Cart from CPQ

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.

Oracle CX Commerce cart

  1. Click Edit.

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

Model Configuration page

  1. Update the Oracle CX Commerce shopping cart.
  2. Click Add to Cart.

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

Oracle CX Commerce shopping cart


ClosedRequest a Quote from an Oracle CPQ Sales Specialist

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.

Quote to Order – Manager page

  1. 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.

Transaction page

  1. 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.

ClosedRetrieve Oracle CX Commerce Interaction Data

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:

By default, interaction metrics are retained for 60 days. Open a Service Request on My Oracle Support to increase or decrease this setting.


Note: For instructions on how to implement the above functionality, refer to the Integrating Oracle CX Commerce and Oracle CPQ Implementation Guide.

Administration

ClosedSend Notification via ICS When a Model is Available for Oracle CX Commerce

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.

ClosedModel Administration Settings

ClosedSelf Service Integration Type


ClosedInclude BOM Items in the Add to Cart Payload Template

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.

Notes:

  • The "AddToCartPayload-Cloud.txt" payload template was available in the 2016 R2 Oracle CX Commerce integration.
  • In 2017 R1, the template includes BOM items in the configuration information.

ClosedUse BOM Mapping Rules in Configuration SOAP APIs

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.

Notes:

  • The Oracle CX Commerce integration available with 2016 R2 required administrators to create Recommended Items corresponding to SKUs in Oracle CX Commerce. In 2017 R1, administrators can use Recommended Items, BOM Items, or both.
  • Beginning in 2017 R1, "bomMapping" is a "responseIncludes" property in the Input SOAP XML for both the Configuration configure and getConfigurations SOAP APIs.
  • Beginning in Release 17D, the "getConfigurations" SOAP API returns data related to adding items to a Oracle CX Commerce cart using the "Add to Cart" action. The following new asset fields are available in the "getConfigurations" SOAP API: assetKey, startDate, endDate, and actionCode.

ClosedSample Input SOAP XML with "bomMapping"

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).

ClosedSample Response with "bomMapping" Section

Sample Response with "bomMapping" Section

Note: The Oracle CX Commerce integration available with Oracle CPQ 2016 R2 required administrators to create Recommended Items corresponding to SKUs in Oracle CX Commerce. In Oracle CPQ 2017 R1, administrators can use Recommended Items, BOM Items, or both.

For more information to SOAP Configuration API.


ClosedSpecify BOM Items to Include in the Base Price

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.

Notes:

  • Each line processes its own Included in Base Price status. The value is not inherited from its parent.
  • The Included in Base Price property is not applicable to the root BOM item.

  • If the Included in Base Price column is not present or not populated, the value assumes "n".
  • There are no restrictions on the number of BOM items administrators can mark as Included in Base Price in a BOM Mapping Rule.
  • The Included in Base Price column is optional. Upon upgrade, pre-existing BOM implementations will not fail due to the missing column.
  • New BOM definitions work with or without the Included in Base Price column.
  • With System Configuration, child models in a system always have prices populated upon performing a reconfigure. This is regardless of the child model’s Included in Base Price definition in the BOM structure.

ClosedGenerate a Configuration ID System Attribute

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.

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.

ClosedSample Input SOAP XML with "configurationId"

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.

ClosedSample Response for "configurationId"

Sample Response for "configurationId"


ClosedAdd Configuration Items to a Transaction Using a REST API Call

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.

Note: In the 2017 R1 Oracle CX Commerce integration, Oracle CX Commerce self-service users can add one or more configured items to an Oracle CPQ Transaction using a single Configured Items API call from ICS.

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


ClosedUse REST Services in the Request for Quote Flow

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)
Note: To set custom attributes in a new Transaction, the request must specify a "_modify_action". Attributes are set before the "_modify_action" is run. For example: If an attribute is set to "a" through the request, but the "_modify_action" sets the attribute to "b" through Formulas or an Advanced modify, the final value of the attribute is "b".

ClosedURL Endpoint Sample

ClosedSample Request


ClosedUse a REST API to Retrieve Interaction Data

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.

Oracle CPQ uses a custom URL parameter to determine when a configuration is accessed from Oracle CX Commerce. An interaction is generated every time the parameter is set or an external reconfigure is called using a saved configuration. There may be Configuration scenarios that occur when not integrated with Oracle CX Commerce that count as interaction data, such as interactions performed by non-Oracle CX Commerce partners.

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.

Included in Metric Data

Not Included in Metric Data

  • Accessing the Model Configuration page from Oracle CX Commerce to perform an initial configuration.
  • Accessing the Model Configuration page from Oracle CX Commerce to perform an external reconfigure or using parameters from an external partner.
  • Mobile configurations from an external partner.
  • ABO configurations related to the Modify and Follow-On order flows and performed by external partners.
  • Configurations not completed due to model-related errors.
  • Related web service calls including configure, getConfigurations, and getSpare.
  • Configurations performed when not integrated with Oracle CX Commerce.
  • Navigating multiple nodes or branching nodes within a single Configuration flow.
  • Configuring child models in a system for the first time.
  • Adding a model to a quote from Favorites without performing a configuration in the Model Configuration page.
  • Adding a model to a quote using the “config Id” and the Commerce “_new_transaction” REST API introduced in Oracle CPQ 2017 R1 to enhance the Request for Quote flow.

ClosedView Interaction Data in CPQ

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.

Open a Service Request on My Oracle Support to change the monthly allotment amount.

Closed User Administration eCommerce Interactions

The eCommerce Interaction text on the User Administration List page and the Company Administration List page displays monthly allotments.

User Administration List page

Notes:

  • Prior to Release 18B, “Remaining Monthly Allotment” was “Monthly Allotment” and “Using” was “Used”.
  • Beginning in Release 18C, eCommerce Interactions no longer display on the User Administration List page when the information is not applicable, meaning customers do not pay for or use eCommerce Interactions.

Closed Email Notifications

When the number of eCommerce interactions performed on the Oracle CPQ site in the current month exceeds the maximum limit allowed, an email notification is sent to the email address specified in the Host Company Info page.

To access the Host Company Info page, perform the following steps:

  1. Open the Admin Home page.
  2. Select Host Company under General.
    The Host Company Info page opens.

ClosedView Interaction Data from the Oracle Cloud Portal

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.


ClosedCreate an Authentication Certificate Integration Type

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.

    "Authentication Certificate" integration

Notes:

  • The Save button is disabled upon successfully saving the integration. If changes are made after the save is performed, the button is enabled.
  • Administrators can modify the name of the integration but not the variable name. They can also replace the authentication certificate but cannot remove it.
  • A single Oracle CPQ site can have any number of Authentication Certificate integrations. There is no limit.

ClosedUse Enhanced Add to Cart Payload

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.

Closed2017 R1 Oracle CX Commerce Integration

ClosedRelease 17D Enhancements

Related Topics

Related Topics Link IconSee Also