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:
Access 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.
Add 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:
- 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.
- 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.
- 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.
Edit 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:
- Open the Oracle CX Commerce cart.
- Click Edit.
The Oracle CPQ Model Configuration page opens within an iFrame in Oracle CX Commerce.
- Update the Oracle CX Commerce shopping cart.
- Click Add to Cart.
The Oracle CX Commerce shopping cart opens and displays the updates.
Request 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:
- The Oracle CX Commerce self-service user selects Request Quote from the Oracle CX Commerce Create Order page. The Request Quote page opens.
- 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.
- 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.
- 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.
- 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.
Retrieve 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:
- Use a REST API to Retrieve Interaction Data
- View Interaction Data in CPQ
- View Interaction Data in the Oracle Cloud Portal
By default, interaction metrics are retained for 60 days. Open a Service Request on My Oracle Support to increase or decrease this setting.
Administration
Send 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.
A Ready for Self Service option and a Self Service Part Number field are available on the Model Administration page to support this enhancement.
Complete the following steps:
- Open CPQ.
- Navigate to the Admin Home page.
-
Under Products, click Catalog Definition.
The Supported Products page opens.
- From the Navigation menu, select Product Families.
-
Click List.
The Supported Product Families page opens with Product Lines displayed by default in the Navigation menu.
-
Click List.
The Product Line Administration List page opens with Models displayed by default in the Navigation menu.
-
Click List.
The Model Administration List page opens.
-
Click the model that is ready to sell in the Oracle CX Commerce storefront.
The Model Administration page opens.
-
Set the Ready for Self Service option to True.
By default, the option is set to False for new models.
- Enter a part number in the Self Service Part Number field to enable the part number in the Oracle CX Commerce storefront.
- Click Update.
- If the Ready for Self Service option is set to True and a part number is not entered in the Self Service Part Number field, an error will display.
Notes:
- If the Ready for Self Service option is not selected, the Self Service Part Number field is not required.
- If a duplicate part number is entered in the Self Service Part Number field, an error message displays upon clicking Update.
- System attributes are available to represent the Ready for Self Service option and the Self Service Part Number field. If the Ready for Self Service option is not enabled, the part number attribute is still present for the model.
- New system model attributes are added with the variable names "_bm_model_part_number" and "_bm_model_ready_for_self_service". If they already exist for a model, administrators should rename or delete them before upgrade. Otherwise, the Self-Service publish fails and existing model attribute data may be lost.
- The value of the Self Service Part Number is not restricted to parts that exist in the Oracle CPQ parts database.
- The Ready for Self Service and Self Service Part Number values are preserved in migration, migration packages, and bulk services.
- If there are duplicate part numbers on the target site, migration fails.
The Self Service integration type is a child of the ICS integration. In order to set up a Self Service integration, administrators must have ICS set up.
The Self Service integration page contains the following options:
- Service: The Service drop-down contains integration flows from ICS. Select the integration flow with which to integrate.
-
Publish: Click Publish to perform the integration. Oracle CPQ collects the enabled Ready for Self Service models and sends them to ICS using the selected Service.
Data for all models under any supported Product Family whose Self Service option is enabled can be sent to ICS, assuming the Product Family is deployed. All eligible model data is sent to the single ICS integration flow selected from the Service drop-down menu.
-
Last Published: The date and time when the Self Service integration was last published.
Notes:
- If a middleware integration does not exist, the option to create a Self Service integration is disabled.
- The Publish button only works after the integration is saved.
- Less than (<), greater than (>), and ampersand (&) characters are encoded in ICS. Administrators should not use these characters in part numbers or work is required by partners to decode them.
- If deleting a Middleware integration when a Self Service integration exists, a confirmation dialog is returned. If the administrator accepts the confirmation, both the Middleware integration and the Self Service integration are deleted.
Include 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.
Use 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.
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.
Specify 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.
Generate 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.
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"
Add 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:
- Integration Cloud Service (ICS) topic
- The Oracle Cloud Integration web site
- Integrating Oracle CX Commerce and Oracle CPQ Implementation Guide
Use 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)
https://sitename.oracle.com/rest/v17/commerceDocumentsOraclecpqTransaction/actions/_new_transaction
{ "_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 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 |
---|---|
|
|
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:
- Open the Admin Home page.
-
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.
User Administration eCommerce Interactions
The eCommerce Interaction text on the User Administration List page and the Company Administration List page displays monthly allotments.
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.
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:
- Open the Admin Home page.
- Select Host Company under General.
The Host Company Info page opens.
View 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.
Create 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:
- Open the Admin Home page.
- Select Integration Center under Integration Platform.
The Integration Center opens. - Click Create Integration.
- From the Type drop-down, select Authentication Certificate.
- In the Name field, enter a name that describes the authentication certificate. For example: Oracle CX Commerce
- The Variable Name field auto-populates upon clicking in or tabbing to the field.
- (Optional) In the Description field, enter a description of the authentication certificate.
- Click Browse next to the Authentication Certificate label.
- Select the Oracle CX Commerce authentication certificate and click Open.
-
Click Save.
The "Authentication Certificate" integration appears in the left pane of the Integration Center.
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.
Use 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.
2017 R1 Oracle CX Commerce Integration
- While the 2017 R1 Oracle CX Commerce integration supports either BOM Items or Recommended Items, customers who choose to implement asset-based services must use BOM Items.
-
Among the BOM Mapping enhancements included in 2017 R1 is the ability to use BOM Mapping Rules to define child items in the BOM hierarchy as configurable models. The Oracle CX Commerce integration does not support this enhancement.
There are scenarios where a Transaction successfully creates via REST services, but the "_modify_action" fails. By default, the response includes only the response of the "_modify_action". This is regardless of whether the action is successful or not. To see the responses for create and modify, define an optional property in the request. The optional property format is "criteria" with value "state": true. To view a sample of this optional property, refer to the Transaction and Asset REST APIs section of this document.
- If trying to use the "_configuration_Id" system attribute as dynamic data in Rich Text templates or Document Engine, customers who are upgrading must perform the Refresh Data Source action.
- When creating a Transaction with a model, the model’s Price Book does not traditionally set the Transaction Price Book. However, a model with a "Client-Side" integration sets the Transaction Price Book to match the model Price Book when a quote is created. When adding parts with that model in the same Transaction, the parts must also use the same Price Book. A model without a custom Price Book defined uses the default Price Book.
- When creating a Transaction through REST services, support for Transaction currency preferences is available.
- Administrators can define the Transaction currency even when line items (both parts and models) are part of the create request.
- Model and Transaction currencies must always match. If they do not match, the Transaction is not created.
- If there are multiple config IDs with different currencies and Transaction currency is undefined, an error returns.
Consider the following tips when using the Oracle CPQ 17D Oracle CX Commerce integration enhancements.
- The asset fields are always included in the "getConfigurations" SOAP API. If there is no asset associated to the Configuration, blank values display.
- The asset fields are only included in "getConfigBom" when there is an asset associated to the Configuration.
- The asset and Configuration are related by matching the asset's "assetKey" with the "bomInstanceId" of the configBomInstance. The "bomInstanceId" is also known as "itemInstanceId_l" when running the "getConfigBom" action.