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 aConfiguration_Details
response (returned from Oracle Configure, Price, Quote) to a Commerce commerce item (cart item). With the embedded configurator, approach theConfiguration_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. AconfigId
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 whenajaxEnabled
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/_ad
d endpoint. It accepts acacheInstanceId
and adds a row to thearraySet
. - Delete Row - This action corresponds to the Oracle Configure, Price, Quote
_set<arraySetVarName>/actions/_delete
endpoint. It accepts acacheInstanceId
andremoveIndex
and removes the row from the supplied index in thearraySet
.
- Add Row - This action corresponds to the Oracle Configure, Price, Quote
- 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
- 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
- Publish your changes.
Commerce is now configured to use the direct API configuration process for customizable products.