1. Integrating with Oracle Commerce
  2. Use Oracle CPQ Cloud Features
  3. Use the Integration Functionality
  4. Implement configuration customization via the CPQ Configuration API.

Implement configuration customization via the CPQ Configuration API.

You need to complete some initial tasks to implement the functionality that directly customizes configurations using the Oracle Configure, Price, Quote Configuration API for the first time on a customer storefront.

The Direct API Configuration feature lets you directly customize configurations using the Oracle Configure, Price, Quote Configuration API. This topic describes the tasks which a developer and designer would work together to implement this functionality for the first time for a customer storefront.

This feature lets you directly customize configurations using the Oracle Configure, Price, Quote Configuration API. This topic describes the tasks which a developer and designer would work together to implement this functionality for the first time for a customer storefront. This would be the set of tasks that would be carried out first to allow you to use the feature.

In this case, the customer does not want to use the hosted iFrame model for executing product customization on their site but would prefer customization via the Direct API Configuration feature. The specific reasons the customer is requesting the implementation of this feature are the following:

  • The customer wants the customization user experience to be as seamless as possible.
  • The customer wants their merchandising team to have as much control over the customization user interface "look and feel" as possible.
  • The customer would prefer that the merchandising team manage the user interface experience in their design tools as much as possible.

The details for implementing and using the Oracle Configure, Price, Quote Configuration API feature are described in the sections that follow. In these descriptions, it is assumed that the Commerce and Oracle Configure, Price, Quote Integration is already configured and enabled.

Understand the role of the Commerce Configurator SSE in the Direct API Configuration feature

The Direct API Configuration feature uses a Commerce server-side extension (SSE) to provide a collection of endpoints which lets the storefront UI (regardless of the UI framework used) to configure products and services. The SSE accepts a configurator request, invokes the corresponding requests in Oracle Configure, Price, Quote, and processes the Oracle Configure, Price, Quote response before returning an optimized payload.

The SSE performs the following configurator actions:

  • Configure - This action corresponds to the Oracle Configure, Price, Quote _configure endpoint and is the starting point for configuring a model. It returns all the necessary layout data, attribute, and configuration state data for a user interface to display a configurator model. Also, where a layout contains Pick Lists and/or Array Sets, it returns all data required for those components to be rendered.
  • Update - This action corresponds to the Oracle Configure, Price, Quote _update endpoint. It will accept an updated configuration state from the client and return an new configuration state based on the changes made.
  • Next - This action corresponds to the Oracle Configure, Price, Quote _next endpoint. This action is available when the model configuration is spanned across multiple nodes/configuration flow layouts. It works similarly to the initial configure action as it also returns all the necessary layout data, attributes, configuration state, and pick list/array set data to display the particular layout for a stage in the flow.
  • Previous - This action corresponds to the Oracle Configure, Price, Quote _next endpoint. This action is available when the model configuration is spanned across multiple nodes/configuration flow layouts. It works similarly to the initial configure action as it also returns all the necessary layout data, attributes, configuration state, and pick list/array set data to display the particular layout for a stage in the flow.
  • Add to Cart - This action corresponds to the Oracle Configure, Price, Quote_integration_addToCart endpoint. This action returns a Commerce commerce item (cart item). It transforms a Configuration_Details response (returned from Oracle Configure, Price, Quote) to a Commerce commerce item (cart item). With the embedded configurator, approach the Configuration_Details response is returned to Commerce and it is the responsibility of the Commerce client to transform the response to a Commerce commerce item.
  • Reconfigure - This action corresponds to the Oracle Configure, Price, Quote _reconfigureClient endpoint. It is similar to the Configure action but rather than starting a brand new configuration, it returns all the necessary layout data, attributes, configuration state, and pick list/array set data for a user interface to display a configurator model for an existing configuration. A configId parameter is used to identify the existing configuration.
  • Interact - This action corresponds to the Oracle Configure, Price, Quote _interact endpoint. It is typically triggered by the user interface in response to a change to an attribute value when ajaxEnabled has been set to true for the user interface component. It takes the value for the attribute that has changed and returns a new configuration state based on the change made.
  • Array Set - The action supports the following:
    • Add Row - This action corresponds to the Oracle Configure, Price, Quote _set<arraySetVarName>/actions/_add endpoint. It accepts a cacheInstanceId and adds a row to the arraySet.
    • Delete Row - This action corresponds to the Oracle Configure, Price, Quote _set<arraySetVarName>/actions/_delete endpoint. It accepts a cacheInstanceId and removeIndex and removes the row from the supplied index in the arraySet.
  • Layout - This action retrieves the full layoutCache for a particular product and flow.
  • Pick Lists - This action retrieves all options available for a particular pick list.
  • UI Settings - This action retrieves all general/base user interface configuration settings from Oracle Configure, Price, Quote.
  • Templates - The action retrieves configuration templates that are to be used for rendering a BOM table and a recommended parts table.

Implement the Direct API Configuration feature

To implement the Direct API Configuration feature in Commerce you must:

  • Download and install the Oracle Configure, Price, Quote Configurator (Storefront/Agent) Server-Side Extension in Commerce.
  • Create a "Customize Button for Direct API" user interface element for direct API configuration.
  • Create a "Reconfigure Button for Direct API" user interface element for direct API reconfiguration."
  • Create a JavaScript Library of user interface components that will be used to render the Layout response from Oracle Configure, Price, Quote (this could be Knockout Components, React, Commerce elements etc.).
  • Include the "Customize Button for Direct API" element (button) in the Product Details widget in order to trigger a customization session.
  • Include the "Reconfigure Button for Direct API" element (button) in the Shopping Cart widget in order to trigger a reconfigure session.
  • Bundle the user interface elements and JavaScript library into a single extension that can be uploaded in a single step.
  • Log in to Commerce Admin and navigate to Settings → Extensions.
  • Upload the Oracle Configure, Price, Quote Configurator server-side extension.
  • Upload the new extension containing the user interface elements and JavaScript library.

Implement the Direct API Configuration feature for Configure

If you decide to implement the Direct API Configuration feature for Configure do the following:

  • Log in to Commerce Admin and navigate to Design → Layout → Product Layout → Layout Settings.
  • Select Product Layout → Grid View and then select the Product Details widget.
  • Select the Element Library. You should see three "Customize Button" user elements available. These include the following:
    • Customize Button - Supports the iFrame customization flow by using the iFrame URL stored in Commerce Admin and appending values for Product Line, Product Family and Model to load the iFrame and kick off the configuration process.
    • Customize Button with Configuration Metadata - Supports the iFrame customization flow by using the iFrame URL stored in Commerce Admin and appending values for Product Line, Product Family, Model and a collection of one or more static or dynamic key value pairs of configuration metadata to load the iFrame in the correct state and kick off the configuration process.
    • Customize Button for Direct API - Supports the API driven customization flow.

      Note: You created this as directed in the previous section as the "Customize Button for Direct API" element.

  • Add the Customize Button for Direct API to the Product Details widget.
  • Save your changes.
  • Navigate back to Layout → Product Layout → Layout Settings.
  • Set the Layout Preview Product ID for 4ForU Deal offer. This is a configurable product that lets you buy services for Landline, Mobile, Internet and TV in a single bundle at a steep discount.
  • Save your changes. Select Product Layout → Preview. You are presented with a preview of the product layout for the 4ForU Deal offer.
  • Select to customize the offer. You are presented with the customizable options for the offer in a combination of user interface components including the following:
    • Panels
    • Tabs
    • Input fields
    • Radio buttons
    • Checkboxes
    • Multi-select lists
    • Single select lists
    • Date pickers
    • Pick Lists
    These components are presented as the default mapping for the corresponding Oracle Configure, Price, Quote model attributes and layout.
  • Publish your changes.

Implement the Direct API Configuration feature for Reconfigure

If you decide to implement the Direct API Configuration feature for Reconfigure do the following:

  • Select Layout → Cart Layout → Grid View and select the Shopping Cart widget.
  • Select Go to widget code.
  • Add the Reconfigure Button for Direct API to the Shopping Cart widget.

    Note: You created this as directed in the earlier section as the "Reconfigure Button for Direct API" element.

  • Save your changes.
  • Navigate back to Layout → Cart Layout → Layout Settings.
  • Set the Layout Preview Product ID for the 4ForU Deal offer with a quantity of 1. This is a configurable product which lets you buy services for Landline, Mobile, Internet and TV in a single bundle at a steep discount.
  • Save your changes.
  • Select Product Layout → Preview. You are presented with a preview of the product layout for the 4ForU Deal offer.
  • Select to customize the offer and add it to the cart.
  • Select the cart and choose to edit the configurable item.
  • You are presented with customizable options for the offer in a combination of user interface components including the following:
    • Panels
    • Tabs
    • Input fields
    • Radio buttons
    • Checkboxes
    • Multi-select lists
    • Single select lists
    • Date pickers
    • Pick Lists
    These components are presented as per the default mapping for the corresponding Oracle Configure, Price, Quote model attributes and layout.
  • Publish your changes.

Commerce is now configured to use the direct API configuration process for customizable products.