CPQ Integrations
CPQ Integrations
F59936-01
October 2022
Integrating with Oracle Commerce,
F59936-01
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software, software documentation, data (as defined in the Federal Acquisition Regulation), or related
documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S.
Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,
any programs embedded, installed, or activated on delivered hardware, and modifications of such programs)
and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end
users are "commercial computer software," "commercial computer software documentation," or "limited rights
data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation
of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated
software, any programs embedded, installed, or activated on delivered hardware, and modifications of such
programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and
limitations specified in the license contained in the applicable contract. The terms governing the U.S.
Government's use of Oracle cloud services are defined by the applicable contract for such services. No other
rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications.
It is not developed or intended for use in any inherently dangerous applications, including applications that
may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you
shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its
safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.
Oracle®, Java, and MySQL are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.
Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are
used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,
and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered
trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise
set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be
responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,
products, or services, except as set forth in an applicable agreement between you and Oracle.
Contents
iii
Appendix C: Understand the OIC Integration Mappings 1-39
Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and Earlier) 1-43
Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-Site Set
Up (19D and Later) 1-48
Appendix F: Understand the SyncQuote BML 1-53
Appendix G: AddToCartPayload-Cloud 1-54
iv
Appendix B: Request for Quote Flow 2-79
v
Access rights 8-2
Assumptions 8-2
Configure Oracle Commerce for Oracle Management Cloud 8-3
Submit Order webhook 8-3
Return Order webhook 8-4
Configure the Oracle Integration Cloud Adapter 8-4
Connections 8-4
Lookup configuration 8-5
Integrations 8-5
XSL location 8-5
Configure Order Management Cloud 8-6
Create the source system 8-6
Create defaulting rules 8-8
Create the orchestration process 8-10
Create the connector 8-13
Order creation 8-14
SKUs 8-14
Payment 8-15
Order types 8-15
Pricing and tax 8-15
Shipping methods 8-15
Mapping of attributes 8-16
Order Status 8-16
Map attributes for order status 8-17
Returns 8-17
Map attributes for returns 8-17
Exchanges 8-18
vi
Publish Your Changes in Both Commerce and Maxymiser 10-11
Work with Maxymiser Campaign Results 10-12
vii
Commerce Configuration 13-5
Accessing the Oracle Integrations Console 13-5
Configuring the Integration 13-5
Index
viii
1
Integrate with Oracle CPQ
Integrate Oracle CPQ with Oracle Commerce.
When you integrate Oracle CPQ with Commerce enable a number of features that your
shoppers can use, including allowing a shopper to configure products, request quotes, or
purchase configurable services.
Purpose
The purpose of this implementation guide is to provide the steps that administrators must
complete in Oracle Configure, Price, Quote, OIC, and Oracle Commerce to prepare for a
Commerce and Oracle Configure, Price, Quote integration.
Audience
This implementation guide is for administrators who are setting up and configuring the
integration. The guide assumes administrators have prior Commerce, Oracle Configure,
Price, Quote, and OIC administration experience.
Prerequisites
The following is a list of integration prerequisites:
• A Commerce 19D or later site setup as described in this implementation guide.
• An Oracle Configure, Price, Quote 19C or later Base Ref App site set up as described in
this implementation guide. The integration between Commerce and Oracle Configure,
Price, Quote adds attributes to the Base Ref App site that correspond to required
Commerce order data.
• A synchronized product catalog to ensure that products in the Commerce catalog map to
corresponding items in the Oracle Configure, Price, Quote catalog.
• Oracle Integration Cloud Service (OIC) 18.3.5 or later.
1-1
Chapter 1
Set Up OIC Integrations
Note: For information about how to obtain any of the above prerequisites, contact an
Oracle sales representative.
1-2
Chapter 1
Set Up OIC Integrations
1-3
Chapter 1
Set Up OIC Integrations
1-4
Chapter 1
Set Up OIC Integrations
1. Log in to Commerce.
2. Click the Menu icon.
3. Select Settings from the menu.
4. Click Web APIs from the sidebar menu.
5. Click Registered Applications from the Web APIs panel.
6. Click Register Application.
7. Enter a name for the integration. Since you are registering OIC, choose a meaningful
name that reflects the integration.
8. Click Save. The Application ID and Application Key are automatically generated. The
application displays on the Registered Applications page.
9. Click the name of the application you created.
10. Select Click to reveal to display the application key.
Note: You need the application key when configuring the Commerce connection in OIC. Copy
the registration key, so that it is available when you complete the Configure the Commerce
Connection procedure.
6. Click Configure Security. The Commerce connection uses the OAuth security policy, so
you must enter the security token for the connection. The security token was generated in
the Generate Security Token section.
7. Click OK.
8. Click Test.
9. Click Save.
Your Commerce connection is now configured for the integration.
1-5
Chapter 1
Set Up OIC Integrations
Once the Oracle Configure, Price, Quote, Commerce, Oracle Configure, Price, Quote
Quote, Oracle Configure, Price, Quote Configure, and Oracle Configure, Price, Quote
getConfigurations connections are configured, you must activate these integrations.
To activate the OIC (Oracle Integration Cloud) integrations:
1. Log in to OIC as an admin user.
2. Click the Integrations icon to display the Integrations List.
3. Use the Activate slide switch to activate the integrations.
4. Decide whether you want to switch on detailed tracing, which collects information
about messages processed by the integration flow. Administrators may find
detailed tracing helpful when troubleshooting issues with the integration flow, but it
may impact performance.
To switch on detailed tracing, select the Enable detailed tracing check box.
Note: Once an integration flow is active, administrators must deactivate and then
reactivate the flow to switch detailed tracing on or off.
5. Click Activate.
1-6
Chapter 1
Set Up OIC Integrations
1-7
Chapter 1
Set Up OIC Integrations
10. Insert the sample BML provided in Appendix F: Understand the SyncQuote BML.
12. Navigate to the Integration tab and move Sync quote above Modify Functions.
1-8
Chapter 1
Set Up OIC Integrations
• If configuring the Request Quote webhook, display information for the OCCS-CPQ
Create Quote integration flow.
• If configuring the Update Quote webhook, display information for the OCCS-CPQ
Update Quote integration flow.
• If configuring the External Price Validation webhook, display information for the
OCCS-CPQ GetConfigurations integration flow.
• If configuring the Services Retrieval webhook, display information for the OCCS-
CPQ Get Assets integration flow.
Note: This webhook has been deprecated.
• If configuring the Services webhook, display information for the OCCS-CPQ Asset
Actions integration flow.
Note: This webhook has been deprecated.
4. Copy the Endpoint URL for the integration.
5. Log in to Commerce.
6. Click on the Menu icon.
7. Select Settings from the menu.
8. Select Web APIs from the sidebar menu.
9. Click the webhook you want to configure.
10. Paste the Endpoint URL that was copied into the URL field for the webhook.
11. Remove the “metadata” text from the end of the URL.
The webhook is now configured and is triggered each time the relevant event occurs, which
in turn triggers the relevant integration flow.
Note: It is not possible to edit webhooks differently for different sites. Updating webhooks
applies changes regardless of the site selected.
See the section Configure the Commerce Server Side Extensions in this document for more
information on these actions.
For more information about Commerce webhooks, refer to the Use Webhooks chapter of the
Extending Oracle Commerce book.
1-9
Chapter 1
Set Up OIC Integrations
For more information on understanding and using the asset Upgrade feature, refer to
the Use Asset Based Ordering section of the Using Oracle Configure, Price, Quote
Features with Oracle Commerce book.
Note: You can also customize configurations of complex assets in Commerce without
being redirected to an Oracle Configure, Price, Quote hosted iFrame which may have
a separate and distinct user interface look and feel that creates a disjointed user
experience. This capability is known as the Direct API Configuration feature and can
be used as another option for the Modify and Upgrade actions. For more information
on the Direct API configuration feature, refer to the Customize configurations in
Commerce using the Oracle Configure, Price, Quote Configuration API section of Use
Oracle CPQ Cloud Features.
1-10
Chapter 1
Set Up OIC Integrations
must modify the SSE code to provide the specific calls needed to connect to the correct credit
checking system.
You can configure the available SSEs, CheckCredit-store.zip and CheckCredit-agent.zip, by
first downloading the SSE packages.
To complete installing and configuring the SSE, refer to Understanding the general procedure
for installing and configuring the integration SSEs.
1-11
Chapter 1
Set Up OIC Integrations
1-12
Chapter 1
Set Up OIC Integrations
It also validates that for any item in the order which is based on a SKU where the
configurable property is TRUE and the assetable property is TRUE the quantity must be 1
and, if not, return an error indicating that this item can only be purchased one at a time. This
check is done by looking to see if the root item has an assetKey value. For more information,
refer to Use Asset Based Ordering.
You can configure the available SSEs, OrderQualification-store.zip and OrderQualification-
agent.zip, by first downloading the SSE package.
To complete installing and configuring the SSE, refer to Understanding the general procedure
for installing and configuring the integration SSEs.
The subsection(s) that follows describe the relevant endpoint(s) for this SSE.
Understand the Order Qualification endpoint
This endpoint is triggered by the Order Validation webhook when any order containing a
configured item is submitted.
The input for this endpoint is the order containing the configured item.
The return for this endpoint is either a TRUE or FALSE value depending on whether the order
passed the validation check or not. If the value is FALSE the return also includes information
about which item(s) in the order failed validation.
Configure the Order Qualification Pipeline SSE
This SSE is used to ensure that an order is valid. It enables an order qualification step in the
purchasing process that can be invoked via the Order Qualification webhook. The extension
can be configured to execute custom order qualification processes such as checking whether
the shopper is eligible to purchase the items in the cart. It contains a pre-built algorithm to
validate that the Customer, Billing, and Service accounts as well as the Billing Profile
assigned to the items in the cart are valid for the logged in shopper.
You can configure the available SSEs, OrderQualificationPipeline-store.zip and
OrderQualificationPipeline-agent.zip, by first downloading the SSE package.
To complete installing and configuring the SSE, refer to Understanding the general procedure
for installing and configuring the integration SSEs.
The subsection(s) that follows describe the relevant endpoint(s) for this SSE.
Understand the Order Qualification Pipeline endpoint
This endpoint is triggered when a shopper goes to checkout for an order that contains
configured items.
The inputs for this endpoint are:
• Contact record for the shopper
• Order containing configured items.
The return for this endpoint is either a TRUE or FALSE value depending on whether the order
passed the validation check or not. If the value is FALSE the return also includes information
about which item(s) in the order failed validation.
Configure the Order Validation Pipeline SSE
This SSE enables an order qualification step in the purchasing process that can be invoked
via the Order Validation webhook. The extension can be configured to execute any final
1-13
Chapter 1
Set Up OIC Integrations
checks particular to the purchasing model before the order payment is authorized and
the order is submitted to the downstream systems for fulfillment and provisioning.
You can configure the available SSEs, OrderValidationPipeline-store.zip and
OrderValidationPipeline-agent.zip, by first downloading the SSE package.
To complete installing and configuring the SSE, refer to Understanding the general
procedure for installing and configuring the integration SSEs.
Configure the Services SSE
The Services SSE enables integration with third party asset management systems to
retrieve and execute operations available to a shopper. This SSE also serves as the
API for the integration with Oracle Configure, Price, Quote asset management. It can
be used to retrieve all the services/assets linked to a shopper’s profile or it can also be
used to retrieve details of just one asset at a time.
The Modify, Renew, Terminate, Suspend, Resume, and Upgrade actions on a service
or asset are performed using the Services SSEs (server side extensions), one set for
Storefront and one for Agent.
The Services SSEs call the integrations in
OCCS_CPQ_ASSET_INTEGRATION_X.X.par and
OCC_CPQ_Get_Asset_Upgrade_Options_1.0.par for the asset Upgrade feature.
To complete installing and configuring the SSE, refer to Understanding the general
procedure for installing and configuring the integration SSEs.
The subsection(s) that follows describe the relevant endpoint(s) for this SSE.
Understand the Services SSE endpoints
The endpoints for the Services SSE are the following:
• getServices - Calls Get OEC Account Details for OCC Profile OIC flow (to retrieve
the account model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS
(6.0) OIC flow, and OCC_CPQ_Get_Asset_Upgrade_Options_1.0 OIC Flow. This
endpoint returns the list of services for the shopper based on their service
account(s) and any upgrade options available for those services.
• getService - Calls Get OEC Account Details for OCC Profile OIC flow (to retrieve
the account model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS
(6.0) OIC flow, and OCC_CPQ_Get_Asset_Upgrade_Options_1.0 OIC Flow. This
endpoint returns the details for a single service for the shopper based on their
services account(s) and any upgrade options available for that service.
• Terminate - Calls Get OEC Account Details for OCC Profile (to retrieve the
account model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0)
OIC flow, and OCCS_CPQ_ASSET_ACTIONS (5.0) OIC flow.
• Renew - Calls Get OEC Account Details for OCC Profile (to retrieve the account
model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow,
and OCCS_CPQ_ASSET_ACTIONS (5.0) OIC flow.
• Suspend - Calls Get OEC Account Details for OCC Profile (to retrieve the account
model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow,
and OCCS_CPQ_ASSET_ACTIONS (5.0) OIC flow.
1-14
Chapter 1
Set Up OIC Integrations
• Resume - Calls Get OEC Account Details for OCC Profile (to retrieve the account model
for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow, and
OCCS_CPQ_ASSET_ACTIONS (5.0) OIC flow.
• Modify - Calls Get OEC Account Details for OCC Profile (to retrieve the account model
for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow, retrieves
iFrame URL from CPQ, and loads the Oracle Configure, Price, Quote hosted iFrame.
• Upgrade - Calls Get OEC Account Details for OCC Profile (to retrieve the account model
for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow, retrieves
iFrame URL from CPQ, and loads the Oracle Configure, Price, Quote hosted iFrame.
• Modify (v2) - Calls Get OEC Account Details for OCC Profile (to retrieve the account
model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow, and
CPQ /rest/v9/config{prodFamVarName}.{prodLineVarName}.{modelVarName}/actions/
_configure. This endpoint supports a directOracle Configure, Price, Quote API Modify
action and lets you bypass the use of an iFrame.
• Upgrade (v2) - Calls Get OEC Account Details for OCC Profile (to retrieve the account
model for the shoppers OCC Profile), OCCS_CPQ_GET_ASSETS (6.0) OIC flow, and
Oracle Configure, Price, Quote /rest/v9/config{prodFamVarName}.{prodLineVarName}.
{modelVarName}/actions/_configure. This endpoint supports a direct Oracle Configure,
Price, Quote API Upgrade action and lets you bypass the use of an iFrame.
These endpoints are triggered when a shopper performs an operation on an asset.
Note: You can customize configurations of complex assets in Commerce without being
redirected to a an Oracle Configure, Price, Quote hosted iFrame which may have a separate
and distinct user interface look and feel that creates a disjointed user experience. This
capability is known as the Direct API Configuration feature and can be used as another
option for the Modify and Upgrade actions. For more information on the Direct API
configuration feature, refer to Customize configurations in Commerce using the CPQ
Configuration API.
The inputs for these endpoints are:
• Logged in User Token.
• AssetKey, the unique ID for the asset for this operation. This may be a root, branch or
leaf asset.
The returns for the endpoints are a BOM (Bill of Materials) or an Error.
Note: For more information about C endpoints, refer to the Use the REST APIs chapter of the
Extending Oracle Commerce book.
For more information about Commerce webhooks, refer to the Use Webhooks chapter of the
Extending Oracle Commerce book.
For more information on understanding and using the asset Upgrade feature, refer to Use
Asset Based Ordering.
Configure the Configuration Validation SSE
The Configuration Validation SSE (cpq-config-validation-app) plays an important role in Asset
Based Ordering and validating asset configuration. This specific SSE performs a
configuration validation between items in a shopper's cart and the items captured in response
to configuration validation end points. For more complete information on Asset Based
Ordering, refer to the Using the Integration Functionality section of this document.
1-15
Chapter 1
Set Up Oracle Configure, Price, Quote
To use this SSE, you should first have the External Pricing webhook set to /ccstorex/
custom/v1/validateCPQConfigurations. This is done on the Settings page of the
Administration user interface.
You should also have the following endpoints configured:
• GET_CONFIGBOM_URI – This is available when
OCCS_CPQ_GETCONFIGBOM is configured.
• GET_CONFIG_URI - This is available when OCCS-
CPQ_CONFIGURATION_INTEGRATION is configured.
The GET_CONFIGBOM_URI URL gets triggered for the Suspend and Terminate
Services. The GET_CONFIG_URI URL gets triggered for the Renew, Modify, and
Resume Services. The SSE does validation between items in cart and items captured
in the response of these two end points.
The SSE package is named cpq-config-validation-app and is downloadable by this
name from the Commerce Administration user interface.
To complete installing and configuring the SSE, refer to Understanding the general
procedure for installing and configuring the integration SSEs.
1-16
Chapter 1
Set Up Oracle Configure, Price, Quote
Note: You can now customize the configurations of complex products in Commerce without
being redirected to an Oracle Configure, Price, Quote hosted iFrame. This capability, known
as the Direct API Configuration feature, builds out support in Commerce for direct API driven
product configurations where the user interface experience is controlled instead by
Commerce and can be customized by Commerce partners rather than relying on the Oracle
Configure, Price, Quote hosted iFrame. Refer to the Using Oracle Configure, Price, Quote
Features with Oracle Commerce guide in the Oracle Commerce Doc Library for complete
details.
Session parameters include currency, language, and locale preferences such as number
format, units, and date format. For example: If a Commerce self-service user’s language
preference is set to German, the text in the Oracle Configure, Price, Quote interface displays
in German when the user accesses Oracle Configure, Price, Quote. The user’s currency and
locale preferences are also passed from Commerce and display in Oracle Configure, Price,
Quote.
To enable guest access to Oracle Configure, Price, Quote:
1. Open the Admin Home page.
2. Under General, select General Site Options. The Options – General page opens.
3. Under Options – Login, set Allow Guest Access to Yes.
This setting allows Commerce to punch in to Oracle Configure, Price, Quote.
4. If multi-currency support from Commerce is required, set Allow Direct Login [Deprecated:
Please use SSO feature] to Yes.
5. Under Options – General, set Occupy entire window when the site is inside a frame to
No. This setting improves usability when punching in to Oracle Configure, Price, Quote
from Commerce.
1-17
Chapter 1
Set Up Oracle Configure, Price, Quote
Quote during the “Add to Cart” action, administrators can add the information by
creating configurable attributes and modifying the payload templates. Administrators
can then export the configurable attributes as key-value pairs from Oracle Configure,
Price, Quote to Commerce.
Payload template files (i.e. Recommended_Items_Payload-Cloud.txt and
AddToCartPayload-Cloud.txt) form the payload structure for sending a
configured item to the Commerce shopping cart. The template files support the “Add to
Cart” action and include configuration information such as config id, quantity, and BOM
items. BML reads the template files and replaces the values in brackets, such as
{{bomitems}}, with dynamic values.
Complete the following steps to add the payload template files to File Manager:
1. Open the Admin Home page.
2. Navigate to Utilities > File Manager. File Manager opens.
3. Create a new folder named CommerceCloud.
4. Under Add Files, click Browse. The Choose File to Upload dialog opens.
5. Navigate to the Recommended_Items_Payload-Cloud.txt file and click Open.
6. Click Add File. The Recommended_Items_Payload-Cloud.txt file displays in
File Manager.
7. Complete steps 1-6 for AddToCartPayload-Cloud.txt.
Shown below is the content of each of the payload template files.
Recommended_Items_Payload-Cloud.txt
{
"quantity": "{{quantity}}",
"catalogRefId": "{{part}}",
"price": "{{price}}",
"recurringCharge": { "amount":"{{recurringPrice}}",
"frequency":"{{pricePeriod}}",
"duration":"{{duration}}" }
}
AddToCartPayload-Cloud.txt
{
"messageType": "Configuration_Details",
"quantity": "1",
"catalogRefId": "{{model}}",
"amount": "{{totalPrice}}",
"price": "{{basePrice}}",
"currencyCode": "{{currency}}",
"configurationId": "{{ConfigId}}",
"childItems": [
{{ChildItems}}
],
"bomItems": [
{{BomItems}}
1-18
Chapter 1
Set Up Oracle Configure, Price, Quote
]
}
4. When the alternate CSS file opens, update the CSS to include the following CSS snippet
to hide the Home button within the iFrame.
.nav-links>a img[title="Home"]{
display: none;
}
Note: If the Home button shows both a label and an icon, administrators cannot hide the
label using only CSS. From the Admin Home page, navigate to Style and Templates >
Navigation Menus > Subheader > Home > Edit. Choose Icon for Display. The Home
button is then hidden with the CSS change.
Hide Price Books
Oracle Configure, Price, Quote uses PriceBooks as a way to associate parts with a price.
Oracle recommends hiding Price Book information from users.
To hide Price Books:
1. Open the Admin Home page.
2. Under Products, select Catalog Definition.The Supported Products page opens.
1-19
Chapter 1
Set Up Oracle Configure, Price, Quote
.pricebook-container {
display:
none;
}
12. Use the File Upload dialog to locate and select the new stylesheet.
13. Click Open. The stylesheet displays in the Regular Stylesheets List page under
the list of Alternate Stylesheets.
1-20
Chapter 1
Set Up Oracle Configure, Price, Quote
assumes part custom fields 4, 5, 6, and 8 represent recurring period, cost, duration, and
type respectively. In order to use other part custom fields, the Add to Cart BML and OIC
mappings will have to be adjusted accordingly.
• If a non-configurable SKU is later added to Commerce and intended for use by the
Oracle Commerce and Oracle Configure, Price, Quote integration, repeat the above
procedure to add the corresponding part in Oracle Configure, Price, Quote.
• In addition toOracle Configure, Price, Quote parts, configurable models must also have a
corresponding SKU in Commerce. The SKU number in Commerce should match the
model’s label and variable name.
1-21
Chapter 1
Set Up Oracle Configure, Price, Quote
Note: For all procedures and SSEs that require address information for endpoint
inputs, in addition to usingCommerce's default address formats, you can also use the
Commerce REST API to create multi-country custom address formats. Refer to the
1-22
Chapter 1
Set Up Oracle Configure, Price, Quote
Configure the Commerce Server-Side Extensions topic in this guide for more information on
address formatting.
Create Attributes at the Commerce Line Level and Add Them to the Commerce Layout
Create the Commerce attributes shown below at the Commerce line level. Once created, add
the attributes to the Commerce layout.
1-23
Chapter 1
Set Up Oracle Configure, Price, Quote
Apply Formulas
The following Commerce attributes should already exist on Base Ref App
environments. Apply the listed formulas to the attributes.
Note: An asterisk (*) next to the variable name indicates that a formula for the attribute
already exists on Base Ref App environments. You must update the existing formulas
as opposed to creating new formulas.
1-24
Chapter 1
Set Up Oracle Configure, Price, Quote
1-25
Chapter 1
Set Up Oracle Configure, Price, Quote
– Quantity
4. Set the line level action “save_l" to define the following line level attributes based
on their formula definitions:
• Actual Amount
• Annual Value
• Contract Value
• Amount (List)
• Amount (Net)
• Price (Net)
• Quantity
Notes:
• The “Save” action is already setup to use formulas for a majority of these attributes
in the Base Ref Application.
• The Request for Quote and Sync Quote flows do not support the “Copy Line
Items” action. The action is not accessible for Commerce integrated Transactions.
1-26
Chapter 1
Set Up Oracle Configure, Price, Quote
oldvalue = getoldvalue("_price_quantity",
atoi(_system_current_document_number));
return true;
}
return false;
15. On the Validation: New Rule page, select Advanced as the Action Type.
attributeDict = dict("dict<string>");
Set Up Steps
You must use Oracle Configure, Price, Quote to create a Synced step as well as step
transitions.
1. Create a new “Synced” step.
1-27
Chapter 1
Set Up Oracle Configure, Price, Quote
2. Create a step transition for the "Sync Quote" action to move from the "In Progress"
step to the "Synced" step.
3. Create a step transition for the “Save" action to move from the "Synced" step to
the "In Progress" step.
4. Create a step transition for the "Customer Rejection" action to move from the
"Synced" step to the "Rejected by Customer" step.
5. Create a step transition for the “Create Order” action to move from the “Synced”
step to the “Ordered” step.
6. Create a step transition for the “Cancel Transaction” action to move from the
“Synced” step to the “Canceled” step.
7. Hide the "Sync Quote" action from the following steps:
• Fulfilled
• Canceled
• Rejected By Customer
8. Hide all Modify actions from the “Synced” step EXCEPT the following:
• Save
• Customer Rejection
• Create Order
• Cancel Transaction
Notes:
• Make sure all of the attributes used in the Request for Quote flow have read/write
access at the Start step.
• For instructions on how to create Commerce attributes, actions, and step
transitions, refer to the Oracle Configure, Price, Quote Administration Help.
1-28
Chapter 1
Set Up Oracle Configure, Price, Quote
Note: Ensure the appropriate Commerce Product Families and Product Lines are created in
Oracle Configure, Price, Quote prior to starting the Client-Side Integration. Refer to the
Configuration > Product Families articles within the Oracle Configure, Price, Quote Online
Help for instructions.
To configure a client-side integration:
1. Open the Admin Home page.
2. Under Products, click Catalog Definition. The Supported Products page opens.
Product Families displays by default in the Navigation drop-down menu.
3. Click List. The Supported Product Families page opens.
4. Click Integrations from the Navigation drop-down menu for the product of the
Commerce product family.
5. Click List. The Edit Integration page opens.
6. Use the Edit Integration page to create a “Client-side” integration using the following
settings:
• Name: Add To Cart
• Integration Type: Client-side
• Hide in Reconfiguration: No
• Action: Define Advanced Function
7. Click Define Function for the Action and use the sample BML from one of the following
to add the Add to Cart button to the Commerce site:
• Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and
Earlier) - this sample BML is for legacy integration sites who have previously
customized their Add to Cart BML. This sample includes site-specific reference file
locations.
• Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-
Site Set Up (19D and Later) – this sample BML is for new integrations and in cases
where the setup needs to be duplicated on multiple sites. This sample does not
reference site-specific file locations.
8. Select Simple for the End-Point URL.
Enter the URL of the Commerce site to integrate with Oracle Configure, Price, Quote.
The value entered should include the basic URL or Commerce’s storefront and
administration pages. You can add multiple Commerce sites for a single integration by
listing each site delimited by the pipe delimiter (|) character.
For example:
http://cc-store.oracle.com|http://cc-admin.oracle.com|http://
second-store.oracle.com|http://second-admin.oracle.com
9. Click Apply.
Note: Ensure that all partner site lists of allowed URLs are properly addressed within Oracle
Configure, Price, Quote. These include domains that are allowed to load the Oracle
Configure, Price, Quote in an iFrame and domains that Oracle Configure, Price, Quote is
allowed to connect to in the Integration Center. You may need to file a Service Request (SR)
on My Oracle Support to include these domains on the site list of allowed URLs.
1-29
Chapter 1
Set Up Oracle Configure, Price, Quote
1-30
Chapter 1
Set Up Subscription Ordering in Oracle Configure, Price, Quote
Condition Apply Rule To Action Type Action Values to Set Set Type
Attribute
Always True Configuration Standard currencyCode Edit Function: Forced Set
return
_BM_USER_C
URRENCY;
3. Create any additional attributes that suit your organization’s needs and place them on the
Configuration flow layout.
• You must place “currencyCode”, “cC_SiteId_t”, and “quantity” on the layout, but they
do not need to display them.
• For information about configurable attributes and the steps to create them, refer to
the Oracle Configure, Price, Quote Administration Help.
4. Create a hiding rule configured as follows:
if (_transaction_id == "-1")
{ return true;}
return false;
1-31
Chapter 1
Set Up Subscription Ordering in Oracle Configure, Price, Quote
Notes:
• The Save button is disabled upon successfully saving the integration. If the
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 Configure, Price, Quote site can have any number of
Authentication Certificate integrations. There is no limit.
1-32
Chapter 1
Set Up Subscription Ordering in Oracle Configure, Price, Quote
In order to support in-flight cancellations of orders, the following custom asset fields must be
created in Oracle Configure, Price, Quote
Note: Refer to the Custom Asset Attributes article within the Oracle Configure, Price, Quote
Online Help for instructions on adding a custom asset.
Upgrade an asset
With Asset Based Ordering, the ability to upgrade an existing asset is supported when you
complete some preliminary set up work.
With Asset Based Ordering, the ability to upgrade an existing asset is supported.
Oracle Configure, Price, Quote maintains a custom upgrade options table for Commerce to
query in order to know which upgrades are available for a given asset. The sections that
follow in this topic provide information on how to set up the required tables and how to
complete some basic Oracle Configure, Price, Quote configuration steps to support asset
based ordering.
The data table column mapping information for this data table is as follows:
• currentModel – Maps to the variable name of the root config model in Oracle Configure,
Price, Quote which the upgrade offer applies to.
• currentOffer – Maps to a configurable attribute on the root config model in Oracle
Configure, Price, Quote. This needs to be stored as an attribute mapping onto the root
asset as well. This value is sent from Oracle Commerce while retrieving the upgrade
options.
• upgradeName – Maps to the _config_upgrade_name that is passed from Oracle
Commerce to Oracle Configure, Price, Quote, which drives recommendation rules on the
upgrade. Not used by Commerce for any other purpose.
• upgradeProductID – Maps to the Product Id of the upgrade offer in Commerce. Used to
show upgrade details (for example, product display name, description, images, etc.) to
the shopper.
Note: We recommend you index the currentModel and/or currentOffer columns.
1-33
Chapter 1
Enable Integrations in Commerce
1-34
Chapter 1
Enable Integrations in Commerce
11. Enter the Configuration URL using the following structure: https://<cpq_domain>/
commerce/new_equipment/products/model_configs.jsp.
12. Enter the Reconfiguration URL using the following structure: https://
<cpq_domain>/commerce/new_equipment/products/
external_reconfig.jsp
13. Enter the Modification URL using the following structure: https://<cpq_domain>/
commerce/new_equipment/products/model_configs.jsp.
Note: Enter the Configuration URL and the Reconfiguration URL for both the Production
and Preview environments.
14. Click Save. If you are using a multisite environment you must follow these instructions for
each site that uses the Oracle Configure, Price, Quote Configuration integration.
1-35
Chapter 1
Enable Integrations in Commerce
1-36
Chapter 1
Enable Integrations in Commerce
1-37
Chapter 1
Appendix A: Understand the Configurator Flow
11. Drag and drop the Quote Details widget from the Components menu to the
desired location on the Order Details layout.
12. Publish the changes.
1-38
Chapter 1
Appendix B: Understand the Request for Quote Flow
1-39
Chapter 1
Appendix C: Understand the OIC Integration Mappings
1-40
Chapter 1
Appendix C: Understand the OIC Integration Mappings
<externalData>
<name></name>
<values>
<name></name>
<variableName></
variableName>
<label>Id</label>
<displayValue></
displayValue>
<value></value>
</values>
</externalData>
< externalData>
<name></name>
<values>
<name></name>
<variableName></
variableName>
<label></label>
<displayValue></
displayValue>
<value></value>
</values>
</ externalData>
1-41
Chapter 1
Appendix C: Understand the OIC Integration Mappings
1-42
Chapter 1
Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and Earlier)
1-43
Chapter 1
Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and Earlier)
The following provides the Add to Cart BML for Customized Integrations 19C and
Earlier:
// Model/Price Properties
models = string[1];
configIdSearch = string[1];
currpath = String[1];
totalPrices = string[1];
bomTotals = string[1];
models[0] = "/configuration/configureResponse/item/model";
configIdSearch[0] = "/configuration/configureResponse/item/
@configurationId";
currpath[0] = "/configuration/configureResponse/attributes/
attribute[@_variableName='currencyCode']/value";
totalPrices[0] = "/configuration/configureResponse/price/totalPrice";
bomTotals[0] = "/configuration/configureResponse/price/bomPrice";
priceTotal = 0.0;
baseModelPrice = 0.0;
recurringSubtotal = 0.0;
payloadTemplate = urldatabyget("https://cpq-046.us.example.com/bmfsweb/
slc10xgj/image/CommerceCloud/AddToCartPayload-Cloud.txt", "", "");
model1 = "";
totalPrice1 = "";
1-44
Chapter 1
Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and Earlier)
// Get ConfigID
configId = "";
for id in configIdSearch {
configId = get(outputConfigIds, id);
}
1-45
Chapter 1
Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and Earlier)
} else {
recItems = sizeofarray(part);
recItemsInt = integer[recItems];
i = 0;
for recItem in recItemsInt {
if (selected[i] == "true") {
//recurring price from parts BMQL
part_num = part[i];
partCustomFields = bmql("SELECT part_number, custom_field5,
custom_field4, custom_field6, custom_field8 FROM _parts WHERE
part_number = $part_num");
recItemPayloadTemplate = urldatabyget("https://
cpq-046.us.example.com/bmfsweb/slc10xgj/image/CommerceCloud/
Recommended_Items_Payload-Cloud.txt", "", "");
recItemPayloadTemplate = replace(recItemPayloadTemplate,
"{{quantity}}", quantity[i]);
recItemPayloadTemplate = replace(recItemPayloadTemplate,
"{{part}}", part[i]);
if (isnumber(sPrice0)) {
priceTotal = priceTotal + atof(sPrice0);
recItemPayloadTemplate = replace(recItemPayloadTemplate,
"{{price}}", sPrice0);
} else {
recItemPayloadTemplate = replace(recItemPayloadTemplate,
"{{price}}", "0");
}
if (recItemList == "") {
recItemList = recItemPayloadTemplate;
} else {
recItemList = recItemList + "," + recItemPayloadTemplate;
}
}
1-46
Chapter 1
Appendix D: Understand the Add to Cart BML – Customized Integrations (19C and Earlier)
i = i + 1;
}
}
i = 0;
for each in bomPricesStringArray {
append(replace_lookup, isnumber(each));
i = i + 1;
}
i = 0;
for each in replace_lookup {
if (i == 0 and each == false) {
jsonpathset(bomJson, "$.fields._price_unit_price_each", "0");
}
elif(each == false) {
str = "$.children[" + string(i - 1) +
"].fields._price_unit_price_each";
jsonpathset(bomJson, str, "0");
}
i = i + 1;
}
bomItemString = jsontostr(bomJson);
bomPartsArray = jsonpathgetmultiple(bomJson, "$..partNumber");
bomPartsString = jsonarraytostr(bomPartsArray);
bomPartsString = replace(replace(replace(bomPartsString, "\"", ""), "[",
""), "]", "");
bomPartsStringArray = split(bomPartsString, ",");
bomParts = bmql("SELECT part_number, custom_field5, custom_field4,
custom_field6, custom_field8 FROM _parts WHERE part_number
1-47
Chapter 1
Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-Site Set Up (19D and Later)
IN $bomPartsStringArray");
// Unflatten
bomItemString = replace(bomItemString, "\"partNumber\":",
"\"catalogRefId\":");
bomItemString = replace(bomItemString, "On Request", "0"); // This
may only fix English users
bomJson = convertbomtohier(json(bomItemString));
payloadTemplate = replace(payloadTemplate, "{{BomItems}}",
jsontostr(bomJson));
}
1-48
Chapter 1
Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-Site Set Up (19D and Later)
The following provides the Add to Cart BML for Customized Integrations and Multi-Site Set
Up 19D and later:
// Initialize variables
MODEL_PATH = "/configuration/configureResponse/item/model";
CONFIG_ID_PATH = "/configuration/configureResponse/item/@configurationId";
CURRENCY_CODE_PATH = "/configuration/configureResponse/attributes/
attribute[@_variableName='currencyCode']/value";
TOTAL_PRICE_PATH = "/configuration/configureResponse/price/totalPrice";
SPARE_PART_PATH = "/configuration/configureResponse/spare/rule/item/part";
SPARE_QUANTITY_PATH = "/configuration/configureResponse/spare/rule/item/
quantity";
SPARE_PRICE_PATH = "/configuration/configureResponse/spare/rule/item/price";
SPARE_SELECTED_PATH = "/configuration/configureResponse/spare/rule/item/
selected";
BOM_ITEM_PATH = "/configuration/configureResponse/bomItem";
BOM_PRICE_PATH = "/configuration/configureResponse/price/bomPrice";
CART_TEMPLATE_LOCATION = "$BASE_PATH$/CommerceCloud/AddToCartPayload-
Cloud.txt";
SPARE_TEMPLATE_LOCATION = "$BASE_PATH$/CommerceCloud/
Recommended_Items_Payload-Cloud.txt";
payload = "";
sparesList = "";
priceTotal = 0.0;
baseModelPrice = 0.0;
sparePart = String[1];
spareQuantity = String[1];
sparePrice = String[1];
spareSelected = String[1];
singleSpareDict = dict("string");
configDict = dict("string");
1-49
Chapter 1
Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-Site Set Up (19D and Later)
// Add BOM total price to priceTotal (which is the REAL total price),
with the same conversion as the base price
if (NOT(isnull(bomPrice))) {
bomPrice = replace(bomPrice, ",", "");
if (isnumber(substring(bomPrice, 1))) {
bomPriceNum = getcurrencyvalue(bomPrice, currency);
priceTotal = bomPriceNum + priceTotal;
}
}
i = 0;
for eachSpare in spareArray {
if (spareSelected[i] == "true") {
1-50
Chapter 1
Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-Site Set Up (19D and Later)
1-51
Chapter 1
Appendix E: Understand the Add to Cart BML – Customized Integrations and Multi-Site Set Up (19D and Later)
bomItem = "";
} else {
// Get part numbers for each BOM item, convert to string array for
bmql
bomJson = json(bomItem);
i = 0;
for each in bomPricesStringArray {
append(replace_lookup, isnumber(each));
i = i + 1;
}
i = 0;
for each in replace_lookup {
if (i == 0 and each == false) {
jsonpathset(bomJson, "$.fields._price_unit_price_each",
"0");
}
elif(each == false) {
str = "$.children[" + string(i - 1) +
"].fields._price_unit_price_each";
jsonpathset(bomJson, str, "0");
}
i = i + 1;
}
bomItem = jsontostr(bomJson);
bomPartsArray = jsonpathgetmultiple(bomJson, "$..partNumber");
bomPartsString = jsonarraytostr(bomPartsArray);
bomPartsString = replace(replace(replace(bomPartsString, "\"",
""), "[", ""), "]", "");
bomPartsStringArray = split(bomPartsString, ",");
bomParts = bmql("SELECT part_number, custom_field5, custom_field4,
custom_field6, custom_field8 FROM _parts WHERE part_number
IN $bomPartsStringArray");
1-52
Chapter 1
Appendix F: Understand the SyncQuote BML
"\",";
recurringTemplate = "\"recurringCharge\":
{ \"amount\":,\"frequency\":,\"duration\":},";
// Unflatten
bomJson = convertbomtohier(json(bomItem));
bomItem = jsontostr(bomJson);
}
return payload;
str = "";
1-53
Chapter 1
Appendix G: AddToCartPayload-Cloud
if(row[0] == each._document_number){
str = str + each._document_number +
"~cC_CommerceItemId_l~" + row[1]+"|";
str = str + each._document_number + "~cC_ProductId_l~"
+ row[2]+"|";
}
}
}
}
return str;
Appendix G: AddToCartPayload-Cloud
Example of the AddToCartPayload-Cloud.txt file.
// Initialize variables
MODEL_PATH = "/configuration/configureResponse/item/model";
CONFIG_ID_PATH = "/configuration/configureResponse/item/
@configurationId";
CURRENCY_CODE_PATH = "/configuration/configureResponse/attributes/
attribute[@_variableName='currencyCode']/value";
TOTAL_PRICE_PATH = "/configuration/configureResponse/price/totalPrice";
SPARE_PART_PATH = "/configuration/configureResponse/spare/rule/item/
part";
SPARE_QUANTITY_PATH = "/configuration/configureResponse/spare/rule/
item/quantity";
SPARE_PRICE_PATH = "/configuration/configureResponse/spare/rule/item/
price";
SPARE_SELECTED_PATH = "/configuration/configureResponse/spare/rule/
item/selected";
BOM_ITEM_PATH = "/configuration/configureResponse/bomItem";
BOM_PRICE_PATH = "/configuration/configureResponse/price/bomPrice";
DELTA_PRICE_PATH = "/configuration/configureResponse/price/deltaPrice";
CART_TEMPLATE_LOCATION = "$BASE_PATH$/CommerceCloud/AddToCartPayload-
Cloud.txt";
SPARE_TEMPLATE_LOCATION = "$BASE_PATH$/CommerceCloud/
Recommended_Items_Payload-Cloud.txt";
payload = "";
sparesList = "";
priceTotal = 0.0;
baseModelPrice = 0.0;
totalDeltaPrice = 0.0;
sparePart = String[1];
spareQuantity = String[1];
sparePrice = String[1];
spareSelected = String[1];
singleSpareDict = dict("string");
configDict = dict("string");
1-54
Chapter 1
Appendix G: AddToCartPayload-Cloud
// Add BOM total price to priceTotal (which is the REAL total price), with
the same conversion as the base price
if (NOT(isnull(bomPrice))) {
bomPrice = replace(bomPrice, ",", "");
if (isnumber(substring(bomPrice, 1))) {
1-55
Chapter 1
Appendix G: AddToCartPayload-Cloud
i = 0;
for eachSpare in spareArray {
if (spareSelected[i] == "true") {
//Convert price, similar to Base and BOM prices above
priceString = substring(sparePrice[i], 1);
priceString = replace(priceString, ",", "");
if (isnumber(priceString)) {
sparePrice[i] = string(getcurrencyvalue(priceString,
currency));
priceTotal = priceTotal + atof(sparePrice[i]);
} else {
sparePrice[i] = "0";
}
1-56
Chapter 1
Appendix G: AddToCartPayload-Cloud
i = 0;
for each in bomPricesStringArray {
append(replace_lookup, isnumber(each));
1-57
Chapter 1
Appendix G: AddToCartPayload-Cloud
i = i + 1;
}
i = 0;
for each in replace_lookup {
if (i == 0 and each == false) {
jsonpathset(bomJson, "$.fields._price_unit_price_each",
"0");
}
elif(each == false) {
str = "$.children[" + string(i - 1) +
"].fields._price_unit_price_each";
jsonpathset(bomJson, str, "0");
}
i = i + 1;
}
i = 0;
for each in bomDeltaStringArray {
append(replace_lookupDelta, isnumber(each));
i = i + 1;
}
i = 0;
for each in replace_lookupDelta {
if (i == 0 and each == false) {
jsonpathset(bomJson, "$.fields._delta_price", "0");
}
elif(each == false) {
str = "$.children[" + string(i - 1) +
"].fields._delta_price";
jsonpathset(bomJson, str, "0");
}
i = i + 1;
}
bomItem = jsontostr(bomJson);
bomPartsArray = jsonpathgetmultiple(bomJson, "$..partNumber");
bomPartsString = jsonarraytostr(bomPartsArray);
bomPartsString = replace(replace(replace(bomPartsString, "\"",
""), "[", ""), "]", "");
bomPartsStringArray = split(bomPartsString, ",");
bomParts = bmql("SELECT part_number, custom_field5, custom_field4,
1-58
Chapter 1
Appendix G: AddToCartPayload-Cloud
// Unflatten
bomJson = convertbomtohier(json(bomItem));
bomItem = jsontostr(bomJson);
}
return payload;
1-59
2
Use Oracle CPQ Cloud Features
Use Oracle CPQ features in conjunction with Oracle Commerce.
Oracle CPQ allows you to create quote-to-cash processes, and guides users towards product
options and configurations. Integrating these features with Commerce allows you to offer
shoppers a method to successfully interact with your business, improving their contact
experience and increasing shopper satisfaction.
Introduction
Many important Oracle Configure, Price, Quote features are available via an integration
solution between Oracle Configure, Price, Quote andOracle Commerce.
This document is intended to provide the instructions on how to use Oracle Configure, Price,
Quote features with Oracle Commerce - via an integration supported by the two solutions.
Oracle Commerce is an eCommerce solution designed specifically to run in the Oracle Cloud.
The service provides you with a range of powerful tools to build a flexible, feature-rich
storefront for your shoppers.
Activities you can perform with Oracle Commerce include the following:
• Customize the design and layout of your storefront pages and preview your changes
• Display your store content in different languages
• Create or import catalog items
• Manage inventory
• Offer promotions
• Manage shopper accounts
• Allow shoppers to set up wish lists
• View reports about your store
• Test the visual elements of your store to determine which design shoppers prefer
• Develop custom features for your store through the Oracle Commerce web services API
Oracle Configure, Price, Quote is the only cloud solution to support the complete quote-to-
cash process - from shopper inquiry to order fulfillment. It guides users to optimal product
options and configurations from simple to complex, automatically applying discounts and
relevant up-sell and cross-sell opportunities.
Integrating these solutions brings together the capabilities of Oracle Commerce and Oracle
Configure, Price, Quote to provide a unified solution that enables businesses to offer
shoppers a method of interacting meaningfully with the business during the purchasing
process, and to provide agents with the means to be flexible with shoppers, improving their
contact experience and maximizing shopper satisfaction.
2-1
Chapter 2
Introduction
Objective
By integrating Oracle Commerce and Oracle Configure, Price, Quote, you increase the
number of supported available commerce shopper features.
The integration of Oracle Commerce and Oracle Configure, Price, Quote targets
support for the following shopper commerce activity:
• Product configuration: The shopper or agent can configure any product that has
been identified as configurable in the product catalog.
• Shopper quote request: The shopper can request a quote for an order.
• Agent quote request: An agent dealing with a shopper contact can request a
quote for a discount on behalf of the shopper.
• Asset Based Ordering - Asset based ordering (ABO) allows you to sell tangible
assets or subscription services delivered over a period of time; for example mobile
phone call and data plans, television and broadband packages, cloud storage
service, music streaming service, etc.
This document provides instructions on how to set up an integration between Oracle
Commerce and Oracle Configure, Price, Quote so that relevant Commerce information
is automatically passed to Oracle Configure, Price, Quote, ensuring that the decision
process has all the required information and increasing the speed at which a reply is
delivered to the shopper or agent.
This document describes the setup tasks that must be performed in Oracle Commerce
and Oracle Integration Cloud in order to use this integration flow. There are additional
setup tasks that must be performed in Oracle Configure, Price, Quote so that the
integration works as expected. Full information about these tasks that must be
performed in Oracle Configure, Price, Quote can be found in the Integrating Oracle CX
Commerce with Oracle Configure, Price, Quote article on My Oracle Support.
Chapter 2 – Configuring the Integration: provides technical instructions on the
following topics:
• How to download the Oracle Integration Cloud Integration Flows.
• How to configure the Oracle Integration Cloud Integration Flows.
• How to setup the connection to Oracle Configure, Price, Quote.
• How to setup the connection to Oracle Commerce.
• How to configure the webhooks to trigger the integration flows.
• How to configure the SSEs (Side-Server Extension) necessary for the integration
flows.
Chapter 3 – Using the Integration Functionality: provides instructions on how to use
the functionality supported by this integration.
Audience
You must follow product-provided documentation to set up and configure the
integration between Oracle Commerce and Oracle Configure, Price, Quote systems.
2-2
Chapter 2
Configure the Integration
This document is written for Oracle Commerce and Oracle Configure, Price, Quote
administrators who need to set up and configure the integration between these two systems.
Readers of this document should have experience with Oracle Commerce, Oracle Configure,
Price, Quote and Oracle Integration Cloud (OIC) administration. This document does not
provide instructions on configuring aspects other than the integration for Oracle Commerce
and Oracle Configure, Price, Quote.
Prerequisites
In order to configure and use the Oracle Commerce/Oracle Configure, Price, Quote
integration, there are specific software, account, and data prerequisites that must be met.
For the purposes of this document, it is assumed that you already have:
• An Oracle Commerce account and access to the Oracle Commerce 19.1 or later with
necessary SSEs enabled (see sections that follow).
• An Oracle Configure, Price, Quote account and access to Oracle Configure, Price, Quote
19.1 or later.
• An Oracle Integration Cloud account and access to Oracle Integration Cloud Service
18.4.5 or later.
• A synchronized product catalog to ensure that products in the Commerce catalog map to
corresponding items in the Oracle Configure, Price, Quote catalog.
• Pricing Base pricing data which is synchronized from the primary PIM (Product
Information Management)/ERP (Enterprise Resource Planning system to both Oracle
Commerce and Oracle Configure, Price, Quote.
• Profiles Shopper/Account data which is synchronized from the primary CRM (Customer
Relationship Management) system to both Oracle Commerce and Oracle Configure,
Price, Quote.
• An extension server to support any required Serve-Side Extensions for the integration.
If you do not have one or more of these, please contact an Oracle sales representative for
information on how to acquire one: http://www.oracle.com/us/corporate/contact/index.html.
Additional Resources
Addition information about Oracle Commerce can be found through the Oracle Help Center
page for Oracle Commerce.
If you require further information regarding Oracle Commerce, you can access the latest
product documentation and training videos through the Oracle Help Center page for Oracle
Commerce.
If you require further information regarding Oracle Configure, Price, Quote, you can access
the latest product documentation through the for Oracle Help Center page Oracle Configure,
Price, Quote.
The documentation mentioned contains links to blogs, developer communities, and Support.
(Please note that some of these resources require an account for access.)
2-3
Chapter 2
Configure the Integration
Five stages are required to configure the integration between Oracle Configure, Price,
Quote and Commerce. Each stage is covered in this chapter.
2-4
Chapter 2
Configure the Integration
2-5
Chapter 2
Configure the Integration
You must complete the following steps to configure the connection from the OIC
integrations to Commerce.
1. Log on to OIC as an admin user.
2. Click the Connections icon.
3. Click the Oracle Commerce connection.
4. Click the Configure Connectivity button.
5. Enter the Connection base URL. The Connection base URL is derived using the
following structure where <siteURL> is the base URL and port number of the
Oracle Commerce site that integrates with OIC. For example:
2-6
Chapter 2
Configure the Integration
2-7
Chapter 2
Configure the Integration
information about a service or asset associated with the shopper and used the
OCCS-CPQ Get Assets integration flow. This webhook called the Contact
Accounts Retrieval webhook, so that webhook also had to be configured for the
Services Retrieval webhook to function correctly.
You must configure the Production and Preview version of these webhooks to ensure
that they work in all environments. The Production webhooks send information from
your live store to production environments of your live systems, while preview
webhooks send information from your preview environment to the test or sandbox
environments of your external systems.
Follow these instructions to configure the Request Quote, Update Quote, External
Price Validation, Services Retrieval, and Services webhooks:
1. Log on to OIC as an admin user.
2. Click on the Integrations icon.
3. Click on the Integration Details icon to display information about the integration
flow.
• If you are configuring the Request Quote webhook, you should display
information for the OCCS-CPQ Create Quote integration flow.
• If you are configuring the Update Quote webhook, you should display
information for the OCCS-CPQ Update Quote integration flow.
• If you are configuring the External Price Validation webhook, you should
display information for the OCCS-CPQ External Pricing integration flow. For
this webhook, you to configure the SSE app endpoint.
• If you are configuring the Services Retrieval webhook, you should display
information for the OCCS-CPQ Get Assets integration flow. This OIC flows
requires the Services SSE to be set up and invoked from there.
• If you are configuring the Services webhook, you should display information
for the OCCS-CPQ Asset Actions integration flow. This OIC flows requires the
Services SSE to be set up and invoked from there.
4. Copy the Endpoint URL for the integration.
5. Log into Commerce.
6. Click the Menu icon.
7. Select Settings from the menu.
8. Select Web APIs from the sidebar menu.
9. Click the webhook you wish to configure.
10. Paste the Endpoint URL you copied into the URL field for the webhook.
11. Remove the “metadata” text from the end of the URL.
12. Enter the user name and Password for your OIC account.
The webhook is now configured and is triggered each time the relevant event occurs,
which in turn triggers the relevant integration flow.
Note: It is not possible to edit webhooks differently for different sites. Updating
webhooks applies changes regardless of the site selected.
2-8
Chapter 2
Configure the Integration
For more information on Oracle Commerce webhooks, please refer to Configure webhooks.
2-9
Chapter 2
Configure the Integration
Note: As written, this SSE generates outbound calls to an external credit checking
system. This means that the Credit Check SSE calls out to an external system to
perform the credit check. In order to use this SSE to connect to the external checking
of your choice, you must modify the SSE code to provide the specific calls needed to
connect to the correct credit checking system.
To complete installing and configuring the SSE, refer to the Understand the general
procedure for installing and configuring the integration SSEs section at the end of
this topic.
The subsection(s) that follows describe the relevant endpoint(s) for this SSE.
Understand the Check Credit endpoint
The Check Credit endpoint is triggered whenever a credit check is requested by
Commerce.
The inputs for this endpoint are:
• Amount information
• Recurring amount frequency
• Recurring amount duration
• Recurring amount
• Contact information
• First Name
• Last Name
• Email Address
• Telephone Number
• Address information
• Address line 1
• Address line 2
• City
• State
• Country
• Postal code
The return for this endpoint is either a TRUE or FALSE value depending on whether
the shopper passed the credit check or not.
2-10
Chapter 2
Configure the Integration
To complete installing and configuring the SSE, refer to the Understand the general
procedure for installing and configuring the integration SSEs section at the end of this
topic.
The subsection(s) that follows describe the relevant endpoint(s) for this SSE.
Understand the Create Accounts endpoint
This endpoint is triggered if the Query Accounts endpoint does not return any accounts for
the shopper.
The inputs for this endpoint are:
• User Token for the logged-in shopper.
• Account Type
• Account Name
• Primary Contact
• Billing Profile(s)
• Address(es)
• Contact ID(s)
• Contact Role(s)
The returns for this endpoint are the accounts, roles, addresses, and business profiles now
associated with the shopper.
Understand the Create Contact endpoint
This endpoint is triggered when a shopper logs in to Commerce.
The input for this endpoint is the User Token for the logged-in shopper.
The return for this endpoint is the new External Contact ID created for the shopper.
Understand the Query Accounts endpoint
This endpoint is triggered when a shopper logs in to Commerce and when they go to
Checkout for an order that contains service items.
The input for this endpoint is the User Token for the logged-in shopper.
The returns for this endpoint are the accounts, roles, addresses, and business profiles
associated with the shopper.
Understand the Query Contacts endpoint
This endpoint is triggered when a shopper logs in to Commerce.
The input for this endpoint is the User Token for the logged-in shopper.
The return for this endpoint is the External Contact ID for the shopper.
Understand the Update Accounts endpoint
This endpoint is triggered when a shopper saves an account address.
The inputs for this endpoint are:
• User Token for the logged-in shopper.
• The Account ID of the account to which the billing profile is linked.
2-11
Chapter 2
Configure the Integration
2-12
Chapter 2
Configure the Integration
This endpoint is triggered when a shopper goes to checkout for an order that contains
configured items.
The inputs for this endpoint are:
• Contact record for the shopper
• Order containing configured items.
The return for this endpoint is either a TRUE or FALSE value depending on whether the order
passed the validation check or not. If the value is FALSE the return also includes information
about which item(s) in the order failed validation.
2-13
Chapter 2
Configure the Integration
• AssetKey, the unique ID for the asset for this operation. This may be a root, branch
or leaf asset.
The returns for this endpoint are BOM (Bill of Materials) and Error.
The GET_CONFIGBOM_URI URL gets triggered for the Suspend and Terminate Services.
The GET_CONFIG_URI URL gets triggered for the Renew, Modify, and Resume Services.
The SSE does validation between items in cart and items captured in the response of
these two end points
You can configure the available SSEs, Services-store.zip and Services-agent.zip, by
first downloading the SSE package.
To complete installing and configuring the SSE, refer to the Understand the general
procedure for installing and configuring the integration SSEs section at the end of
this topic.
Understand the general procedure for installing and configuring the integration
SSEs
To use this integration, you need to install and configure the integration server-side
extensions (SSEs). The SSE code logic allows communication between Commerce
and Oracle Configure, Price, Quote - via Oracle Integration Cloud as part of the data
flow. The Commerce and Oracle Configure, Price, Quote integration functionality/
communication is provided through the configuration of these server-side extensions.
In addition to providing REST APIs and webhooks for integrating with external systems
(as well as widgets for extending your storefront), Commerce also includes support for
developing server-side extensions written in JavaScript. For more information, refer to
Working with Commerce Server-Side Extensions
The general installation and configuration procedure for the integration SSEs uses the
following steps:
• Before you configure and install the integration server-side extensions, first make
sure your custom Node.js server is associated with your Commerce environment.
• Download the integration server-side extension (SSE) files locally, so that you can
install and configure them. Select and remember the desired location where you
want the SSE .ZIP file(s) to be downloaded. See Integrating Oracle CX Commerce
and Oracle CPQ (Doc ID 2214316.1) on the My Oracle Support site for more
2-14
Chapter 2
Configure the Integration
information on the required integration SSE .ZIP files and for the links that let you
download these files.
• After downloading the required files, you need to install them. Use the POST /
ccadmin/v1/serverExtensions endpoint to do this. Specify the Content-Type as
multipart/form-data and include a reference to the file in the body of the request. For
example, your request header might look like the following:
{
"result": {
"unzipped": false,
"failedImages": 0,
"allImagesFailed": false,
"failedImagesReasons": {},
"modifiedImages": 0,
"newImages": 1,
"assignedImages": 0
},
"success": true,
"links": [
{
"rel": "self",
"href": "http://myserver.example.com:7002/ccadmin/v1/
serverExtensions"
}
],
"token": "d63c663af7f15_cd3d"
}
• Make changes to each server-side extension’s config.json file by providing the correct
URLs to complete the SSE configuration portion of that integration. The typical steps
used for working with the SSE code and making changes to the config.json file include
the following:
– Obtain and download the correct SSE .ZIP file.
– Extract the SSE .ZIP file.
– Edit and save the config.json file.
– Zip the files using the original .ZIP file name as the original.
The following example shows some configuration information (in bold) that must be
added to the config.json file for both the store and agent models of the SSE:
"hostname": "yourhostname.example.com",
"port": "7003",
"timeout": 50000,
"username_env_var": "YOUR_USERNAME",
"password_env_var": "YOUR_PASSWORD",
2-15
Chapter 2
Configure the Integration
"QUERY_CONTACTS": "/ic/api/integration/v1/flows/rest/
OCC_OEC_GET_PROFILE_SSE/1.0/contacts",
"CREATE_CONTACT": "/ic/api/integration/v1/flows/rest/
OCC_OEC_CONTACT_CREATE_SSE/1.0/contacts",
"QUERY_ACCOUNTS": "/ic/api/integration/v1/flows/rest/
OCC_OEC_GET_ACCNT_DETLS_PROF_SSE/1.0/accounts",
"CREATE_ACCOUNTS": "/ic/api/integration/v1/flows/rest/
OCC_OEC_ACOUNT_CREATE_SSE/1.0/contacts/{currentContactId}/accounts",
"UPDATE_ACCOUNT": "/ic/api/integration/v1/flows/rest/
OCC_OEC_ACCOUNT_UPDATE_SSE/1.0/contacts/{currentContactId}/accounts/
{accountId}"
All of the example endpoint URLs (paths) specified in the example, starting from
the "QUERY_CONTACTS" to the “UPDATE_ACCOUNT" keys, are coming from Oracle
Integration Cloud and are necessary for a successful integration activation
between Commerce and Oracle Configure, Price, Quote. The paths that you would
use when editing your config.json files would be the ones specific to your SSE
endpoints. The ones shown here are for example purposes only. Refer to each
specific SSE section in this topic to obtain the correct SSE and endpoint
information.
• Upload the modified SSE .ZIP file. To upload the file, click Settings then
Extensions. On the Extensions page, click Installed and then Upload Extension.
Select the location and name of the ZIP file.
2-16
Chapter 2
Configure the Integration
2-17
Chapter 2
Configure the Integration
2-18
Chapter 2
Configure the Integration
Note: Commerce provides the admin endpoint that can be used to set an environment
variable on the Commerce server. For additional information on each SSE's supported
environment variables, a README.TXT file is provided along with the config.json file that has
additional usage information.
2-19
Chapter 2
Configure the Integration
https://<cpq_domain>/commerce/new_equipment/products/
model_configs.jsp
8. Enter the Reconfiguration URL using the following structure. You must enter these
values for your production and preview environments.
https://<cpq_domain>/commerce/new_equipment/products/
external_reconfig.jsp
9. Enter the Modification URL using the following structure. You must enter these
values for your production and preview environments.
https://<cpq_domain>/commerce/new_equipment/products/
model_configs.jsp
If you are using multiple sites you must follow these instructions for each site that you
operate that uses the Oracle Configure, Price, Quote Configuration integration.
2-20
Chapter 2
Configure the Integration
11. Click Save. This returns you to the SKU frame where the SKU you updated should be
marked with an asterisk to identify it as a configurable SKU.
Note: Administrators can also perform the above setup steps in bulk by using the SKU import
program. From the Catalog page in Commerce, click Manage Catalog and select Import. In
the Import dialog, click Browse and locate the CSV file to import. Click Upload File, click
Validate, and then click Import.
2-21
Chapter 2
Use the Integration Functionality
The Quote Details and Request Quote widgets do not display on the layouts by
default. You must first make the widgets available and then place them on the
Checkout and Order Detail pages.
To add quote buttons to the Checkout and Order Details pages:
1. Log in to Commerce.
2. Click the Menu icon.
3. Select Design from the menu.
4. Select the Components tab on the Design page.
5. Click the Show Hidden button.
6. Click the Show icon for the Quote Details Widget and the Request Quote Widget.
7. Within the Design page, select the Layouts tab.
8. From the layout list, select Checkout Layout.
9. Drag and drop the Request Quote widget from the Components menu to the
desired location on the Checkout layout.
10. From the layout list, select Order Details.
11. Drag and drop the Quote Details widget from the Components menu to the
desired location on the Order Details layout.
12. Publish the changes.
Configure an item
Items marked as configurable in your catalog can be configured either by an agent via
the Commerce Agent Console or by a shopper via the Commerce Storefront.
Items that have been marked as configurable in your catalog may be configured either
by an agent via the Commerce Agent Console, or by a shopper via the Commerce
Storefront. This section provides instructions for both methods of configuring an item.
2-22
Chapter 2
Use the Integration Functionality
Request a Quote
With Oracle Configure, Price, Quote enabled in the integration price quotes may be
requested for one or more items.
Quotes may be requested for one or more items on an order either by an agent from within
the Agent Console, or by a shopper from the checkout page for their order. If you are also
using Oracle Configure, Price, Quote Configuration functionality, the order may contain a
combination of configured and non-configured items.
2-23
Chapter 2
Use the Integration Functionality
4. Once you have an order with items in the cart, click on the Request Quote link in
the order edit page. You can switch between the Request Quote page and the
Create Order page by clicking on the appropriate link.
5. Add text to the Quote Notes text box as desired.
6. Click on the Request Quote button.
Once the agent has submitted the quote request, the Request Quote webhook is
triggered and all relevant information is passed to Oracle Configure, Price, Quote
for a decision on the quote. The order status is changed to “Pending quote”. When
an order is in Pending status, the agent cannot perform any operations on the
order.
A confirmation email is sent to the shopper informing them of the status of their
order.
7. Once a response is received, the order status changes to “This order is a quote”,
and the agent then has a number of options about how to proceed. The agent can:
The agent can:
• Accept the quote: If the shopper is satisfied with the quoted price returned
from Oracle Configure, Price, Quote, the agent can accept the quote on their
behalf by clicking on the Accept button and proceeding with the order as
normal.
Once payment information has been entered and the order placed the order
status changes to “Submitted for fulfillment”. At this point the Update Quote
webhook is triggered and Oracle Configure, Price, Quote is informed that the
quote has been accepted.
At this stage the agent can click on the Edit Order button, but the only edits
allowed to the quote are changes to the shipping group, or the application of
shipping discounts or promotions. The agent may not add or remove items
from the cart, or change the quantities of items included in the order. The order
status changes to “Order being amended” until the agent clicks on the
Complete Order button.
• Request a requote: If desired, the agent can enter more details in the
Request Quote textbox and click on the Request Requote button to request an
updated quote. When the agent requests a requote the order status changes
to “Pending quote”. When an order is in Pending status, the agent cannot
perform any operations on the order.
• Reject the quote: The agent can click on the Reject Quote button to reject the
quote. This cancels the shopper’s order and the order status changes to “this
quote has been rejected”.
Note: The response to a quote request includes provision for an expiry date
for the quote. If the quote has expired the Accept Quote and Reject Quote
buttons are disabled, but an agent can request a requote for the order.
Once the agent responds to the quote a confirmation email is sent to the
shopper informing them of the status of their quote.
Order statuses relating to quotes are included in the dropdown list of order statuses in
the Order Details section of the Order Search page.
2-24
Chapter 2
Use the Integration Functionality
Understand a user case as well as the workflow used to obtain correct account-based
pricing
An example of a user case where a shopper (or agent) would want to obtain account-based
pricing could go something like this:
2-25
Chapter 2
Use the Integration Functionality
• The shopper selects a commerce site and browses through the items in the
catalog.
• The shopper selects a configurable item and clicks on the Customize button,
which opens an iFrame allowing them to customize/reconfigure the item.
• The shopper configures the item and expects to see the prices for the items which
only that customer would be allowed to see for that account.
• The shopper places the order with the customer-specific pricing. The shopper,
after submitting the order and within the designated remorse period, is able to
update the configurations of the items as well as receive the customer specific
pricing for those items.
• The shopper can cancel this order containing customer specific priced items
(within the remorse period).
• The shopper can carry out returns and refunds.
• The shopper can exchange within the same configured item(s).
Some variations to this use case could include:
• The shopper gets the account specific pricing but when shopper account details
change, the adjusted price specific to that account would appear.
• An agent placing an order for an account based shopper gets the account specific
pricing specific to that shopper.
The workflow used to obtain the correct account-specific pricing is the following:
• The store sends the Account ID(Customer ID, Customer Name) through the
Configure Product iFrame. The shopper's accountId has been encrypted using
the SSE and the encrypted details are what is sent to the Oracle Configure, Price,
Quote iFrame. Other properties like model, product line, locale, currency are not
encrypted.
• The calls made to Oracle Configure, Price, Quote at this point internally call the
Oracle Configure, Price, Quote Price API.
• The iFrame shows the account specific pricing for the account based on the
accountId.
• The Price API looks for any customer pricing rules defined in Oracle Configure,
Price, Quote and returns the correct account-specific pricing for that customer
based on the accountId. If there are no prices configured specifically for the
customer, then they are presented with the default prices.
• A sample widget can be customized by implementers to encrypt and pass
additional properties along with the accountId. The re-configuration flow works as
it already exists.
The main purpose of this workflow is to pass the customer account/organization
details to the Oracle Configure, Price, Quote system and calculate the customer-
specific price (if any pricing rules are defined).
The existing integration components should retain their existing functionality (i.e. the
customer/system implementer should be able to switch as to whether they are using
anonymous or customer specific pricing).
With this workflow, it is assumed that there is data synchronization of Customers
(Commerce account-based customer accounts) across Oracle Configure, Price, Quote
and Commerce. Oracle Configure, Price, Quote is the mechanism that has the ability
2-26
Chapter 2
Use the Integration Functionality
to set up rule-based pricing which can be customer specific. The customer specific pricing
rule(s) should be the source for the account-based pricing of the item. Finally, there is a
check done that is part of the integration which makes sure that the logged-in user is
validated.
Note: A customer can use Oracle CDM (Oracle Customer Data Management) to maintain
that the accounts (organizations) are synchronized between Commerce and Oracle
Configure, Price, Quote or they can just use the Commerce accounts. The accountId that is
passed in the integration flow varies based on the implementation model.
Understand how Commerce and Oracle Configure, Price, Quote support account-
specific pricing
To be able to obtain account-specific prices configured on Oracle Configure, Price, Quote and
display it on Commerce via the returned iFrame, you need the iFrame to be extended to
handle various attributes as part of getting the price from Oracle Configure, Price, Quote. By
extending these attributes, you can then display the account specific pricing given by the
Oracle Configure, Price, Quote system.
The cpq-config-validation-app SSE now validates the additional accountID from the
getConfiguration call made to Oracle Configure, Price, Quote to find the profile associated
with the order before calling the Submit Order endpoint. An appropriate error message is
returned if the accountId does not match the values of the orgId of the profile in order.json.
By passing these parameters from Commerce to Oracle Configure, Price, Quote during the
Configuration Page launch, the Pricing logic in Oracle Configure, Price, Quote can be
triggered within the Configuration user interface. Commerce provides the initial ability to pass
the Account ID, but an implementer can extend this to pass any other parameters from
Commerce that Oracle Configure, Price, Quote can understand.
The integration takes an Access Token Based security approach to ensure that prices meant
for users of one account are not visible to users of a different account. The key features of
using this approach are the following:
• The authentication into Oracle Configure, Price, Quote continues to be an anonymous/
guest user method as it is today.
• There is no need for user mapping between the Commerce user and Oracle Configure,
Price, Quote user as well as no need for additional user maintenance between
Commerce and Oracle Configure, Price, Quote.
• The approach follows an established approach based on Assets Modify Punch-In.
2-27
Chapter 2
Use the Integration Functionality
{
"accountId" : "or-100001",
"configurableSkuDetails" : {
"currency" : "USD",
"locale" : "en",
"model" : "sku50001",
"product_line" : "laptopConfiguration",
"product_family" : "Laptop"
}
}
2-28
Chapter 2
Use the Integration Functionality
process of re-configuring an item. Unfortunately, the only available option is to delete the
configured item and add it again as a fresh configuration.
To avoid inconvenience to the shopper, it is recommended that you add an information
message to your custom widgets. The message should be seen when an anonymous
shopper tries to add a configured item to cart, (for example, when they click the Customize
button or when they are on the Product Details page. The message should suggest that the
shopper first login and then do the configuration.
Set up and configure Commerce and Oracle Configure, Price, Quote for account-
specific pricing
Use the following procedures to set up and configure Commerce and Oracle Configure,
Price, Quote for the account-specific pricing feature:
Configure Oracle Integration for account-specific pricing
Use the following steps to configure Oracle Integration for account-specific pricing while using
the Commerce/Oracle Configure, Price, Quote integration:
• Download the Oracle Integration packages found in the OCCS-
CPQ_CONFIGURATION_INTEGRATION_4.0.par package file from Oracle Marketplace or My
Oracle Support.
• Import the package into the OIC Environment
• Configure the Oracle Configure, Price, Quote Connection in OIC.
• getConfigurations (4.0) is used to validate configuration and pricing from Oracle
Configure, Price, Quote.
For more information on using Oracle Integration, refer to the product Help Library.
The next steps you need to complete are downloading and configuring the required Server
Side Extensions (SSEs) used for account-specific pricing. There are three SSEs used by the
integration to support this. These are the following:
• cpq-config-validation-app.zip
• cpq-config-punchin-store.zip
• cpq-config-punchin-agent.zip
The information that follows describes how to download and configure these SSEs.
Download and configure cpq-config-validation-app.zip
2-29
Chapter 2
Use the Integration Functionality
• Run the Node Package Manager to install in the .ZIP contents in the root folder
• Zip the contents in the root folder.
• Upload to the Extension Server using the serverExtension endpoint
Download and configure cpq-config-punchin-store.zip and cpq-config-
punchin-agent.zip
2-30
Chapter 2
Use the Integration Functionality
sure you have set up the accounts and desired users in Commerce and have set up the
proper pricing rules in Oracle Configure, Price, Quote (since it is the provider of the prices to
sent to Commerce).
Finally, double check that you have setup pricing rules on Oracle Configure, Price, Quote
based on a parameter (for example, Account Id) and have also added the public key to the
Integration Center - Authentication Certificate in Oracle Configure, Price, Quote.
2-31
Chapter 2
Use the Integration Functionality
With the support of Quadplay/NPlay configured items, the shopper adds the Get4
Bundle to the Oracle Commerce cart as a standard multi-level hierarchical configured
item. This item also has the ability to be reconfigured if needed. The item is then
validated and checked out as usual. For more detailed information working with
Quadplay and NPlay items, refer to CX Communications - How to Customize and
Extend – Configure NPlay Bundles with Oracle Configure, Price, Quote System
Configuration white paper on the My Oracle Support site.
2-32
Chapter 2
Use the Integration Functionality
Note: Dynamic configuration metadata is not restricted to being captured on the PDP UI
widget. The dynamic configuration can be derived from any relevant information such as
shopper profile.
This means that merchants can decide what dynamic key value pair data they want to
capture and pass in the configuration request for any SKU. Dynamic configuration metadata
can be mandatory or optional (i.e., in some cases the shopper MUST enter a value for a key
and in some cases they may optionally enter a value for a key).
Configuration metadata lets merchants define a single model for all variants of a configurable
product and at purchase time pre-load the configuration model at the appropriate starting
point based on the shopper’s selection in Commerce.
The configuration metadata feature builds on the already existing support of the NPlay
feature. Earlier there was support of the purchase of NPlay products but only where there is a
one-to-one relationship between product and model (i.e., each NPlay product had to have its
own unique corresponding configuration model in Oracle Configure, Price, Quote).
Enter configuration metadata via the administration user interface
To provide the configuration metadata needed for processing an order, the
configurationMetadata property is exposed so that you can enter the information in the
Commerce Cloud Administration interface. To get there click Catalogue then Product and
finally SKU. This Administration panel lets you view, add, delete, and edit the Configuration
Metadata values as required. Any request from Commerce to configure an item will include
configuration metadata where it is available.
An example of using configuration metadata might be a case where a Commerce Cloud
Administrator receives an email from a colleague in Oracle Configure, Price, Quote to advise
them that the configuration model with the correct configuration metadata for the Family Plan
products SKUs is now complete. The email contains the information to further configure the
SKU. The SKU is called sku_fp_001 and the information provided is the following:
• Product Family – mobile
• Product Line - bundles
• Model - sku_fp_001
• Bundle Version - 18.1
• Region - EMEA
The process for entering the configuration metadata via the Admin interface would go
something like the following:
1. Navigate to the Commerce Cloud administration user interface panel and select Catalog.
2. Select the Family Plan product and select the SKU sku_fp_001 which is currently
flagged as inactive.
3. Click on Externally Configurable SKU. You see the text “Oracle Configure, Price, Quote
can configure this as a part of a complex product.”
Note: For any SKU where you want to add configuration metadata, you must make sure
that Externally Configurable SKU is checked when you first begin entering data. A new
input property will be displayed which will allow you to begin to enter one or more key
value pairs of data.
4. Slide the panel down until you see the Product Family, Product Line, and Model fields
appear on the panel. Enter all of the correct metadata details (the ones sent to you in the
email from your Oracle Configure, Price, Quote colleague) manually.
2-33
Chapter 2
Use the Integration Functionality
5. Slide the panel down to see the Configuration Metadata table, click the Add button
to add a row.
6. Add Bundle Version to the Name field. In the field next to Bundle Version, add 18.1
(as the bundle version number). You can press Tab or Enter to create a value
entry. Click the Add button when done. A new row in the metadata value table
appears.
7. Add Region to the Name field. In the field next to Region, add EMEA. You can
press Tab or Enter to create the value entry.
8. Slide the panel back up to the top of the SKU ID panel, click Active, and then click
Save.
At this point, you have entered all of the details received from your Oracle Configure,
Price, Quote contact. This information must be entered correctly. The details that are
entered are not seen by the customer. The information is designed to populate the
config iframe window with the correct information. As a final step you activate the SKU
and save the details.
Note: Since the configuration metadata must be entered manually via the Commerce
administration console, keep in mind the following rules:
1. There is no support for versioning of configuration metadata so when an SKU
record is imported, make sure it does not contain any configuration metadata that
should replace any existing configuration metadata assigned to that SKU.
2. If the imported SKU record includes configuration metadata (columns present in
the import file) but there are no values included then any existing configuration
metadata will be deleted.
3. If the import SKU record does not include configuration metadata (no columns
present in the import file), then any existing configuration metadata should be
retained.
A Commerce administrator can view, delete, edit, or add Configuration Metadata key
value pairs for any SKU where the _Externally Configurable SKU_ property is
selected. A Configuration request from Commerce to Oracle Configure, Price, Quote
always includes the configuration metadata set in Commerce for that SKU.
To work with configuration metadata you must have the following prerequisites:
• Oracle Commerce account
• Oracle Integration Cloud account
• Oracle Configure, Price, Quote account
2-34
Chapter 2
Use the Integration Functionality
• An item that may be contained at one or more branch items of the root item
• An item that may be contained at one or more of leaf items of a specific branch
Formerly, you assigned a shipping group at the root item level. The assumption was that the
integration layer managed updates to the "shipping group" relationship object. The result of
this was something where "if all sub-items are shipped then set the shippingGroupItem
status on the root item to the status SHIPPED."
The original method did not work if you sold configured items that are a combination of goods
and services and the services that needed to be assigned to separate shipping groups. It is
important that customers selling nPlay bundles be able to assign each "play" to its own
shipping group. As an example, you should reasonably expect to be able to assign separate
shipping groups to, say, a handset (shipped to your office via priority mail), a router (shipped
to your home via standard mail) and set top box (shipped to your vacation House via
standard mail).
The ability to assign different shipping groups at different levels is also important for the
Cancel In-flight order feature which lets you cancel In-Flight orders. An order which has been
submitted but not fulfilled is considered to be In-Flight. When an In-Flight order is canceled,
the process results in the creation of a new Cancel Order and may also result in the creation
of a Return Request for items that may have already shipped to the shopper and must be
returned, or at least refunded. In order to determine which items have to be returned, the
system must be able to determine the shipping status of each item in the configuration.
In summary, all items in a multi-item configuration hierarchy from the root to the leaf level are
assigned to a shipping group. You must also be aware that the assignment of shipping
groups is also dependent on other key Commerce product features that directly impact the
assignment of shipping groups.
For customers that are migrating to a release of Commerce that has this shipping group
feature, the assignment of the shipping group logic is not adapted automatically. They will
have to modify their ClientConfiguration settings. For first time users of the new release,
the logic is adapted automatically.
Finally, logic changes are adapted only when the customer is using the Commerce user
interface for all front-end behavior. If the customer is making endpoint calls directly, then they
can call the orders endpoint with the required payloads without worrying about modifying
ClientConfiguration.
2-35
Chapter 2
Use the Integration Functionality
In summary, configured item shipping groups are assigned at all of the following levels
of the configured item:
• Root item of type configurableCommerceItem
• Branch items of type configurableSubSkuCommerceItem
• Leaf items of type subSkuCommerceItem
2-36
Chapter 2
Use the Integration Functionality
Understand the tax calculation process when assigning shipping groups to sub-items
The processes for calculating taxes and shipping charges for shipping groups assigned to
sub-items differ slightly than the normal customer calculation process. In summary, the
method used is that if sub-items are shipped separately, then the root item and the child items
are sent as different items to the taxation system which contains the cost of that item alone
and no additional item in the package.
This means that there are two ways that tax calculation occurs with a shipping group. The
first way is that the price of the fully configured package is sent to the taxation system as all
the items in the product configuration have to be delivered to a single place.
In determining the correct amount of tax payable on a product, the four key parameters
passed to the tax calculator are the following:
• amount - the amount paid by the shopper
• quantity - the quantity of the item being purchases
• shipping charge - the shipping charge that has been calculated for the item
• taxCode - the tax code assigned to the product
For configured items, tax is calculated for each line item in the configuration hierarchy but the
amount passed to the tax calculator is always be the external price returned from the
configurator for that item, in the context of the overall configuration.
2-37
Chapter 2
Use the Integration Functionality
For any configured item, the price of a sub-item may be included in the price of the
root item, so that the amount passed to the tax calculator would be zero.
The net result of this is that, although tax will be calculated for each item in the
configuration hierarchy, all of the appropriate data will be passed to the tax calculator.
It is possible, however, that the amount of tax paid by the shopper may be skewed in
circumstances where the configured item contains products with different tax codes.
For configured items, shipping charges are calculated for each line item in the
configuration hierarchy. The amount passed to the shipping calculator, however, will
always be the external price returned from the configurator for that item, in the context
of the overall configuration.
For any configured item, the price of a sub-item may be included in the price of the
root item, so that the amount passed to the shipping calculator would be zero.
The net result of this is the following:
• Shipping charges are calculated for each item in the configuration hierarchy and
all of the appropriate data is passed to the shipping calculator. It is possible,
however, that the amount of shipping charges paid by the shopper may be skewed
in circumstances where the configured item price does not accurately reflect the
actual proportional amount paid for an item in the configuration hierarchy.
• Shipping surcharges are included for any item in the hierarchy where such
surcharges have been assigned to that product in Commerce.
Note: The charges are only included for the root item if the whole configuration is
sold as a package
• A merchant can always choose to apply a shipping surcharge for any item where
there is a risk that the shopper will be undercharged for shipping when a particular
product is purchased as part of a configured item.
• Shipping surcharges are not considered if any item presents itself in a virtual
shipping group as those items are non-shippable and are not required to have
shipping surcharges.
2-38
Chapter 2
Use the Integration Functionality
Understand the shipping charge calculation process when assigning costs to items
sold as a package
The processes for calculating shipping charges and taxes when assigning costs to items sold
as a package differ slightly from normal customer calculation processes. To determine the
correct amount of shipping charges payable on an item configured as a package, the
following key parameters are passed to the shipping calculator:
• shippingMethod - the shipping method selected for the item
• quantity - the quantity of the item being shipped
• amount - the amount paid by the shopper for the item
For items sold as a single item (root item) configured as a package, the following occurs:
• The amount passed to the shipping calculator is always the total price for the configured
item.
• The shippingMethod passed to the shipping calculator will always be the shipping
method assigned to the root item.
• The quantity passed to the shipping calculator is always be the quantity of the root item.
Shipping charges will be calculated accurately, given that you have decided that the
configured item must be shipped as a unit. Any shipping surcharges assigned to a sub-item
in the configuration hierarchy will not be included in the total shipping charges.
Understand the tax calculation process when assigning costs to items sold as a
package
In summary, the way that tax calculation occurs with a shipping group sold as a package is
that the price of the fully configured package is sent to the taxation system as all the items in
the product configuration have to be delivered to a single place.
To determine the correct amount of taxes payable on an item configured as a package, the
following key parameters are passed to the tax calculator:
• amount - the amount paid by the shopper
• quantity - the quantity of the item being purchased
• shipping charge - the shipping charge that has been calculated for the package item
• taxCode - the tax code assigned to the product.
For configured items sold as a package (i.e., where the soldAsPackage value for the root item
= TRUE), taxes are calculated based on the root item only. For configured items sold as a
package, the following occurs:
• The amount passed to the tax calculator is always the total price for the configured item.
2-39
Chapter 2
Use the Integration Functionality
• The taxCode passed to the tax calculator is always the tax code for the root item.
This means that although taxes are calculated for the configured item, the amount
is based only on the tax code of the root item.
2-40
Chapter 2
Use the Integration Functionality
CRM (Customer Relationship Management) system in a PCI compliant manner. For the
Oracle Telco CX Solution, the primary CRM system is Oracle Engagement Cloud (OEC).
Note: In an integration like this, transaction payment details that are stored in the CRM
system are used for recurring payments. This info is pulled by the billing system from CRM.
To compare this with Commerce, Commerce handles one time/upfront payments by
interacting with payment gateways.
At this point in time, Commerce is PCI compliant whereas Oracle Integration Cloud and
Oracle Engagement Cloud are not. Commerce supports the storing of credit cards against a
shopper profile. The card details are captured, however, in the store as part of the checkout
flow and subsequently a tokenized version of the card is obtained from an integrated
payment system as part of the payment authorization process. This token, along with a
masked version of card number and the expiration date are then stored against the shopper’s
profile so that the shopper can easily use the same card for future purchases.
A feature is now supported that offers a generic horizontal benefit to Commerce and
contributes to the Telco specific vertical requirement. This feature uses a store API endpoint
that allows a shopper to store credit cards as part of their profile without actually purchasing
an order. This endpoint can then be used to enable Commerce to pass credit card
information to Oracle Engagement Cloud as part of the shopper billing profile when creating
or for updating accounts in OEC.
The endpoint can be used to invoke Add Card requests multiple times to let you add more
than one card to a shopper Profile. Each new card is then stored against the profile. The
inputs of this endpoint are:
• cardType
• nameOnCard
• cardNumber
• expiryMonth
• expiryYear
Both versions of this endpoint trigger the Generic Payment webhook for a Tokenize operation
on the payment system. The payment system is expected to return a tokenized value of the
card which is then saved against the billing profile. The endpoint then returns back a stored
card ID.
The Admin Get Profile endpoint can then be used to get the token value of the card using the
stored card ID. See Configure Payment Processing and Create a Generic Payment Gateway
Integration for more complete information on this subject.
2-41
Chapter 2
Use the Integration Functionality
2-42
Chapter 2
Use the Integration Functionality
in, then a check is made that the basic card information has also been passed in the form of
maskedCardNumber and expiryMonth.
If the token has not been passed in (i.e., a new card has been introduced), then a check is
made to look for the following “full card” information:
• Card Type
• Name on Card
• Card Number
• CVN (card verification number)
• Expiry Month
• Expiry Year
The billing profile information passed to the OCC to OEC Account Update flow includes:
• Payment Method=Card
• Masked Card Number
• Card Expiry Date
• Tokenized representation of the card
Note: Keep in mind the following additional details regarding the OCC OEC Comms: Account
Update flow:
• A check is made to verify that the payment type is credit card/debit card. If it is credit
card/debit card, then a check is made to verify whether creditCardNumber is masked or
non-masked.
• If creditCardNumber is masked, an additional check is made to verify that the masked
creditCardNumber and creditCardId values provided are valid. If both are valid, then
only creditCardNickname is allowed to update. All other fields/properties are not allowed
to update.
• If creditCardNumber is unmasked, then the card is considered a new card. Tokenization
occurs with the provided card details is similar to the Create Account flow. The process
ends with the new card and token details stored in CDM.
Understand fields and properties supported by the billing profile
For the credit card or debit card payment type, the following fields/properties are supported:
• paymentMethod: “debitcard”/”creditcard”
• creditCardNumber (mandatory field)
• creditCardExpiryMonth (mandatory field)
• creditCardExpiryYear (mandatory field)
• creditCardContactName (mandatory field)
• creditCardType (mandatory field)
• creditCardSecurityCode
• creditCardNickname
• creditCardIin
For the bank transfer payment type, the following fields/properties are supported:
2-43
Chapter 2
Use the Integration Functionality
• paymentMethod: “bankTransfer”
• bankAccountNumber (This is the only mandatory field for bankTransfer payment
type.)
• bankRoutingNumber
• bankAccountType
• bankAccountName
• bankSortCode
• bankName
• bankAddress
• bankIban
• bankSwiftCode
2-44
Chapter 2
Use the Integration Functionality
Customer Account
This type of account represents the person or organization that owns the service. It includes
basic customer information, such as name and address and can receive both services and
bills.
Customer accounts are the highest level in the account hierarchy and can perform all
customer, service, or billing functions.
Service Account
This type of account represents the person or organization that receives the service.
The address associated with the Service account defines the physical location where the
service must be delivered. This address is used to verify service and ordering eligibility.
2-45
Chapter 2
Use the Integration Functionality
Service accounts are required when the location and/or party receiving the service
differ from the Customer account. If a Service account is required, it is always a child
of a Customer account. There can be multiple Service accounts associated with a
single Customer account.
A Service account cannot be used to perform any of the functions of a Customer or
Billing account.
Billing Account
This type of account represents the person or organization that pays for the service.
Billing accounts are required when the location and/or party paying for a service differ
from the Customer account. If a Billing account is required, it is always a child of a
Customer account. There can be multiple Billing accounts associated with a single
Customer account.
A Billing account cannot be used to perform any of the functions of a Customer or
Service account.
Billing Profile
A billing profile may be associated with either a Customer account or a Billing account.
It captures information such as billing preferences, method of payment, and contact
details. There may be more than one billing profile associated with a Customer or
Billing account, and the shopper must choose which billing profile to use when placing
an order for a service.
Note: Address information is something used extensively in Commerce transactions.
For all procedures and SSEs that require address information for endpoint inputs, in
addition to using Commerce's default address formats, you can also use the REST
API to create multi-country custom address formats. This lets you create country-
specific address formats to ensure that your address formats align with the
requirements of any external service that you might use. This means that addresses
appearing in profiles, accounts, registration requests, order addresses and more can
be customized. For more complete information on creating custom addresses and
understanding how to use custom address formatting, refer to the following:
• Customize Address Formats using the API in Extending Oracle Commerce
• Work with address types in Extending Oracle Commerce
• Account Details in Using Oracle Commerce
• Work with account addresses in Using Oracle Commerce
• Work with account registration requests in Using Oracle Commerce
2-46
Chapter 2
Use the Integration Functionality
assumed that the item is not a service or subscription item. In this case the price represents
an upfront payment and the recurring charge is the means by which the outstanding balance
is paid.
Identification of items that include a recurring charge must be carried out through your Oracle
Configure, Price, Quote Admin account. Please refer to the Synchronize Oracle Configure,
Price, Quote Cloud Parts with Commerce SKUs section of the Implementation Guide
contained in the Integrating Oracle CX Commerce with Oracle Configure, Price, Quote article
on My Oracle Support.
If a shopper adds a recurring charge item to their cart, Commerce works with Oracle
Configure, Price, Quote to display full information about the recurring charges associated with
the order. This includes how much the recurring charge is for, the frequency of the recurring
charge, and the duration for which the recurring charge will be made.
Note: The default value for frequency is monthly and the default value for duration is open-
ended. If either of these is not the right value for the item they must be corrected in the
Oracle Configure, Price, Quote Part for the item.
Items with a recurring charge are not included in order sub-total passed to the shipping
calculator. If a cart contains only recurring charge items the order sub-total passed to the
shipping calculator is zero, which means that no shipping charge is applied to the order.
2-47
Chapter 2
Use the Integration Functionality
2-48
Chapter 2
Use the Integration Functionality
systems. In this case, the term "potential" is used meaning that not every item added to a
cart gets completely fulfilled, a provisioning system may fail, etc. For configured items,
the assetKey value is assigned as part of the asset configuration process in Oracle
Configure, Price, Quote.
• Parent Asset Key - Some configured items in an order may be many levels deep in a
BOM structure. In order to ensure that the BOM hierarchy is consistent throughout the
asset life cycle, each item in the BOM hierarchy must be able to identify its direct parent.
The parentAssetKey property makes this possible. For root items in a BOM hierarchy,
the parentAssetKey value is NULL.
• Root Asset Key - Again, some configured items in an order may be many levels deep in a
BOM structure. In order to ensure that the BOM hierarchy is consistent throughout the
asset life cycle, each item in the BOM hierarchy must be able to identify its root asset.
The rootAssetKey property makes this possible. For root items in a BOM hierarchy, the
assetKey and the rootAssetKey value is the same.
Commerce only maps asset key values to commerce items that are actually "assetable." The
rules used in this process are the following:
• If the SKU selected for configuration is based on a product where the property value for
assetable = TRUE, map the asset key data.
• If the SKU selected for configuration is based on a product where the property value for
assetable = FALSE do not map the asset key data.
Understand the Asset Root
It is also important to point out that when a shopper chooses to configure a SKU in
Commerce, the root item of the BOM returned from Oracle Configure, Price, Quote may not
always be that same SKU, that is, the root item part number may not map directly to the
selected configurable SKU.
Say, for example, a mobile product bundle that is represented by the "Red Bundle" SKU in
Commerce is configured several ways. At the initial step of the configuration process, the
shopper may be asked to select either the Standard Package, Student Package, or Value
Package. Depending on the selection made, the root item of the configuration will be
different.
So, based on this example, it is possible that the SKU selected by the shopper to configure
the item will be based on a product where _assetable _= TRUE but the root item for the
resulting configuration may be based on a product where _assetable _= FALSE.
The rule that decides whether a configured item should be assigned _assetKey _ property
is based on whether the SKU that corresponds to the root item of the configuration is
"assetable" and not on whether the item that the shopper selected to be configured in
Commerce is "assetable".
2-49
Chapter 2
Use the Integration Functionality
2-50
Chapter 2
Use the Integration Functionality
• Commerce transforms the JSON returned to a commerce item and adds it the cart.
– For the Modify and Upgrade operations, the transformation is executed in the
Commerce client layer.
– For all other operations the transformation occurs in the Services SSE which uses
the Asset Action OIC flow.
• The shopper continues shopping.
• When the shopper places the order, the cpq-config-validation-app SSE is triggered
through the External Pricing Webhook. This SSE invokes getConfiguration for every
flow except when the asset actions are Terminate and Suspend. The response received
from OIC gets transformed from the cpq-config-validation-app SSE as the OIC flows,
getConfigurations, and getConfigBom return a flat structure of items which is converted
to a hierarchical structure. Validation is then done in the cpq-config-validation-app
SSE to verify that data is not manipulated on client-side.
• The order items representing Asset Based Ordering operations are submitted
downstream and contain all of the information required to ensure that the operation is
fulfilled.
The specific Services actions are described in more detail later in this section. These actions
are important for maintaining an efficient self-service channel. When a shopper performs any
one of these actions on an asset, the Oracle Configure, Price, Quote asset repository is
updated accordingly.
Since Commerce serves as the first point of contact for shoppers, it allows shoppers to
review and select their purchases. In the case of a Telco commerce solution, the Oracle
Configure, Price, Quote asset repository acts as the primary Asset system in which
Commerce makes a call to Oracle Configure, Price, Quote to retrieve the assets for a
particular profile or account. Oracle Configure, Price, Quote manages the retrieval of assets
from multiple systems.
The Commerce Telco solution gives the shopper the ability to retrieve and display the
complete set of Assets owned by the shopper/account as well as carry out the mentioned
administration operations that can be performed on those assets.
When a shopper opens the My Services management area within their account they are
presented with a list of the assets linked to their account. From here they can select an asset
and click on the Details button next to the desired asset to see the detailed view of the
service.
It is at this point that the shopper can choose between the Modify, Renew, Terminate,
Suspend, Resume, and Upgrade actions.
Modify
If the shopper chooses Modify, Commerce loads the current configuration for the service in
question and opens a screen that allows the shopper to modify the service as required. The
new monthly charge for the service is updated automatically as the shopper makes their
selections. The shopper can then add the modified service to their cart.
When the shopper goes through checkout and completes their order, Commerce submits a
service modification request to the fulfillment system.
As mentioned, earlier the steps in this operation are typically the following:
• The shopper views their list of assets.
• The shopper selects an asset.
2-51
Chapter 2
Use the Integration Functionality
• The shopper selects a Modify operation. For a Modify operation, the system loads
an Oracle Configure, Price, Quote hosted iFrame. The shopper makes their asset
modifications and selects to add it to cart.
• Oracle Configure, Price, Quote asset records are updated and Oracle Configure,
Price, Quote returns the required JSON representation the terminated/renewed/
suspended/resumed/modified asset.
• Commercetransforms the required JSON returned to a commerce item and adds it
the cart. This transformation is executed in the Commerce client layer.
• The shopper continues shopping and then checks out.
The order items representing ABO operations are submitted downstream and contain
all of the information required to ensure that the operation is fulfilled.
Renew
If the shopper chooses Renew, Commerce determines the configuration ID that
represents a renewal of the service in its current configuration and then adds a
renewal instruction to the shopping cart and opens the Shopping Cart Details page.
When the shopper goes through checkout and completes their order, Commerce
submits a service renewal request to the fulfillment system. This is handled and
invoked via the Services SSE endpoint /services/{id}/renewService and the SSE
invokes the OIC flow.
Terminate a service
If the shopper chooses Terminate, a configuration ID is sent back by Oracle Configure,
Price, Quote that represents the termination of the service in question. A termination
instruction is added to the shopping cart and the Shopping Cart Details page is then
opened
When the shopper goes through checkout and completes their order, Commerce then
submits the service termination request to the fulfillment system. This is handled and
invoked via the Services SSE endpoint /services/{id}/terminateService which
invokes the OIC flow.
Suspend a service
If the shopper chooses Suspend, it allows them to suspend a service. Commerce
provides an endpoint that is used to suspend a service. When a shopper selects to
suspend a service, they choose the Suspend action and then enter a valid suspend
date.
By clicking on the Suspend button, Commerce determines the configuration ID that
represents the suspension of the service in question, adds a suspension instruction to
the shopping cart, and opens the Shopping Cart Details page. When the shopper goes
through checkout and completes their order, Commerce submits a service suspension
request to the fulfillment system. Also, when the Suspend action is chosen from the
store user interface, the transaction date is set to current date (i.e., the date that the
shopper suspended the service. This suspension may be indefinite or for set for a
specific period of time by entering a date. A specific shopper use case example might
be letting a shopper suspend a data plan for 30 days.
The Services SSEs support the Suspend operation which returns either a Configured
Item or an Error. Services is part of the Oracle Integrated Cloud flow.
2-52
Chapter 2
Use the Integration Functionality
The Services API has an endpoint called Suspend Service. The endpoint can be triggered
when a shopper selects to suspend a service, enters a valid suspend date and time, and
selects to proceed. Inputs include the following:
• Asset Key
• Action - Suspend
• Transaction Date - The valid suspend date and time information that the shopper entered.
The Suspend date is not equal to or later than the asset end date.
The API returns either a Configured Item or an Error.
Resume a Service
If the shopper chooses Resume, it allows them to resume a service that was previously
suspended. Commerce provides an endpoint that is used to resume a service. When a
shopper selects to resume a service, they choose the Resume action and then enter a valid
resume date and time to resume the service.
By clicking on the Resume button, Commerce determines the configuration ID that
represents the service in question that is to be resumed, adds a resume instruction to the
shopping cart, and opens the Shopping Cart Details page. When the shopper goes through
checkout and completes their order, Commerce submits a resume service request to the
fulfillment system. Also, when the Resume action is chosen from the store user interface, the
transaction date is set to current date (i.e., the date that the shopper resumed the service).
The Services SSEs also support this Resume operation which returns either a Configured
Item or an Error. Services is part of the Oracle Integrated Cloud flow.
The Services API has an endpoint called Resume Service. The endpoint can be triggered
when a shopper selects to resume a service, enters a valid resume date and time and selects
to proceed. Inputs include the following:
• AssetKey
• Action: Resume
• Transaction Date: The valid Resume date and time that the shopper entered. The
Resume date is not equal to or later than the asset end date.
The API returns either a Configured Item or an Error.
Note: An action code of Renew, Terminate, Suspend, and Resume is assigned to an item
when that respective operation has been applied to that item.
Upgrade an Asset
With Asset Based Ordering, you have the ability to upgrade an existing asset. If a shopper
chooses the Upgrade operation, they can upgrade an asset to one of the upgrades available
for the product. Any Root asset may have one or more upgrade options available at any time.
Commerce SSE endpoints getServices and getServices/{id} return the upgrade options
for each of the asset if the query param "expand=occ_upgradeOptions" is passed. Once the
shopper selects the Upgrade action and clicks the Upgrade button, this action invokes the
upgradeService SSE endpoint which gets the upgrade name as input and returns the query
string that is to be used as punchin URL to launch the Oracle Configure, Price, Quote iFrame.
From the user interface point of view, a shopper selects to upgrade an asset, choose the
Upgrade action in the Asset Details view and then select the asset upgrade that they desire.
Oracle Configure, Price, Quote maintains a custom upgrade options table for Commerce to
query in order to know which upgrades are available for a given asset. The key parameter
controlling the operation is the SKU of one or more items that are part of a current asset
2-53
Chapter 2
Use the Integration Functionality
bundle. The response received after initiating this operation includes all of the eligible
SKUs that an asset can be upgraded to.
Commerce has an Upgrade endpoint to fetch all available upgrade options. The input
for this endpoint is currentModel and currentOffer. The following presents the
details on the information needed to retrieve the upgrade options table from Oracle
Configure, Price, Quote:
• Oracle Configure, Price, Quote Table Name: INT_UPGRADE_OPTIONS
• Input (via URL parameter): occ_Upgrade_options query parameter which is a list
of currentSku plus currentModel for the assets. Type: String. This query
parameter is passed from Commerce to the SSE endpoint (described further in
this section). After a getAssets call, you then pick the currentModel and
currentOffer from each asset and invoke the Oracle Configure, Price, Quote
upgrade options table.
• Output: upgradeName, upgradeProductId(OCC)
The following presents the details on the basic schema of the upgrade options table
maintained by Oracle Configure, Price, Quote that contains the specified upgrade
information:
2-54
Chapter 2
Use the Integration Functionality
It is recommended that the currentSku column is indexed. The following presents additional
details on each returned upgrade option:
• currentOffer - Maps to a configurable attribute on the root config model in Oracle
Configure, Price, Quote. This needs to be stored as an attribute mapping onto the root
asset as well. This value is sent from Commerce while retrieving the upgrade options.
• currentModel - Maps to the variable name of the root config model in Oracle Configure,
Price, Quote which the upgrade offer applies to.
• upgradeName - Maps to the _config_upgrade_name that is passed from Commerceto
Oracle Configure, Price, Quote, which drives recommendation rules on the upgrade. This
is not used by Commerce for any other purpose.
• upgradeProductId - Maps to the Product Id of the upgrade offer in Commerce. This is
used to show upgrade details (product display name, description, images, etc) to the
shopper.
As mentioned, Commerce provides an Upgrade endpoint that is used in the operation to
upgrade the asset. This endpoint is part of the Services SSE which works to complete
multiple service operations (already mentioned in the above sections) via the Services API.
For this operation, the Services API has an endpoint called Upgrade. The following
information provides more detail on what is required by the API to upgrade an asset using
this endpoint:
• SSE name: Services
• Endpoint name: Upgrade
• Endpoint trigger: The endpoint is triggered when the user clicks Upgrade against an
upgrade option
• Inputs:
– Logged in User Token
– AssetID
– upgradeName (returned from Oracle Configure, Price, Quote)
• Returns: Upgrade URL Query String. This is the string of data that is appended to the
base Modify URL to ensure that the upgrade iFrame is correctly pre-populated based on
the product that the shopper is upgrading from and the product that they are upgrading
to.
The activity that occurs at the store user interface level during the Upgrade operation is the
following:
• Select the Asset List view. This lets you view information about all of your assets/
services. This view will also show the upgrade options (if available) for the asset. You
cannot trigger an Upgrade operation from this view as the actual upgrade URL is not yet
determined until the asset details are retrieved.
• Select the asset you wish to view and click the Details button so that you can view the
asset details and as well as possible upgrade details.
2-55
Chapter 2
Use the Integration Functionality
• When you click the Details button of any asset, the asset details page is displayed
which shows all of the details associated with that asset along with available asset
action options.
• The asset details page also has a section showing the upgrade options available
for that asset. When you display the asset details page, the product details of that
SKU/Product are displayed. The Upgrade button is displayed next to any upgrade
available for that asset.
• Click the Upgrade button in the Asset view of the asset that you want upgraded.
Your upgrade option details are then displayed in the Asset Details view. You can
also get the same results by clicking the link for the available upgrade from the
Service list.
• Click Upgrade. When the Upgrade operation is initiated, the following occurs:
– If there are upgrades available for the asset, the SSE endpoint returns an
Upgrade URL Query String and creates the upgrade punch-in URL to load the
iFrame containing the information about the available upgrades.
– When you select to upgrade you are finally presented with a pre-configured
modification to your asset bundle.
– If the SSE endpoint returns an error, this means there are no upgrades
available for this asset and an appropriate error message is displayed.
• Add the upgrade to your cart and submit the order to complete the upgrading
process.
Finally, each of the Asset Based Ordering services operations described earlier may
be carried out by a shopper or by an agent acting on the shopper’s behalf.
2-56
Chapter 2
Use the Integration Functionality
• Let's say a shopper starts an upgrade configuration from the SKU "4ForUDeal" by
passing the configuration metadata offer=4ForUDeal.
• After upgrading the configuration, the BOM sent from Oracle Configure, Price, Quote may
have a different root SKU id such as "nPlay." "4ForUDeal" may be a child of it. It will also
contain an attribute "offer" with value "4ForUDeal"
• An asset with "nPlay" as the currentModel gets created and the getAssets/getAsset flows
return the asset details along with asset attribute offer=4ForUDeal.
• The offer attribute is sent as the currentOffer to the Oracle Configure, Price, Quote while
retrieving the upgrade option 4ForUDealPlus.
• Once the upgrade has been performed by passing the upgrade name 4ForUDealPlus to
Oracle Configure, Price, Quote in the queryString, the BOM returned from Oracle
Configure, Price, Quote will have the attribute "offer" with value "4ForUDealPlus".
• After submitting the order and updating the asset, the asset attribute "offer" value now
gets updated to "4ForUDealPlus".
• In subsequent getAssets and getAsset calls the asset attribute offer value will be returned
as "4ForUDealPlus", so that there are no matching records for that currentOffer in
upgrade options table in Oracle Configure, Price, Quote.
2-57
Chapter 2
Use the Integration Functionality
This code is assigned to make sure that shoppers are prevented from attempting to
reconfigure an asset. The purpose of the code is to make sure the reconfigure
session(s) fails, either at reconfiguration or order validation time.
For any given order Commerce queries the Oracle Configure, Price, Quote assets API
to retrieve the assets for the order based on the collection of assetKey values. This
query is limited to the assetKey values for the root items in the order only
2-58
Chapter 2
Use the Integration Functionality
You can now customize the configurations of complex products in Commerce without being
redirected to a Oracle Configure, Price, Quote hosted iFrame which may have a separate
and distinct user interface look and feel that creates a disjointed user experience. This
capability, known as the Direct API Configuration feature, is provided to build out support in
Commerce for API driven product configurations where the user interface experience is
controlled by Commerce and can be customized by Commerce partners. At a high level, this
feature lets you do the following:
• Create brand specific configuration user interfaces and controls at the global level.
• Create a specific user interface experience for individual customizable products at the
product level.
The goal of this feature is to provide full support of the Oracle Configure, Price, Quote
Configuration API on Commerce Storefront frameworks. This includes providing a
mechanism to dynamically create user interface elements that let shoppers select
customizable products. It then presents them with the appropriate user interface elements to
complete the customization process and add the each item to the cart. These user interface
elements are generated dynamically in response to the selections made by the shopper at
each step of the customization. The functionality of this feature is fully compliant with current
Commerce Storefront frameworks.
The principal benefits of the Direct API Configuration feature are the following:
• iFrame is not required - The current functionality requires that the configuration system
(Oracle Configure, Price, Quote) perform all of the configuration tasks. This means that
the shopper's user interface experience is managed in 2 separate applications. Up to the
point where the shopper selects a customizable product, their user interface experience
is driven by Commerce. On the other hand, the configuration user experience is
managed by Oracle Configure, Price, Quote and when the shopper adds the configured
item to the cart the user experience reverts back to the control of Commerce. The
addition of this feature means that customers will not be required to execute product
configuration via an iFrame. This lets shoppers experience a consistent user interface
with common look and feel across their storefront.
• Decoupling of the user interface and the configuration process - This feature ensures that
the user interface framework is decoupled from the configuration process. This lets
customers do the following:
– Build configuration user interface components using the Commerce Design Page
based on the Store Front 1.0 Framework.
– Build configuration user interface components using a non-Commerce design user
interface framework.
• Performance improvements - The use of the iFrame pattern also creates a performance
concern. The former integration with Oracle Configure, Price, Quote functions well and
the disjointed user experience can be managed to some extent with user interface
customization. However, there is also no reliable evidence that this design pattern
performs at the levels required for high volume customer-based Telco implementations,
where hundreds of thousands of shoppers may be configuring complex Telco bundles at
the same time. This feature attempts to address this concern.
The roles that Commerce and Oracle Configure, Price, Quote now take with this feature are
the following:
• Oracle Configure, Price, Quote remains the primary configurator and controls the
following:
– What needs to be configured
2-59
Chapter 2
Use the Integration Functionality
2-60
Chapter 2
Use the Integration Functionality
• Manages BOM (Bill of Materials) data objects returned from Oracle Configure, Price,
Quote when the configuration is saved.
This Commerce Extension supports any user interface client, including those built on
Commerce Storefront 1.0.
Understand how the Direct API Configuration feature enhances Asset Operations
As mentioned, this feature provides Commerce with support of the Oracle Configure, Price,
Quote Configuration API Layer while using the Commerce and Oracle Configure, Price,
Quote integration. This means providing functionality that lets customers, using any user
interface framework, configure and/or reconfigure customizable products by invoking the
following from Oracle Configure, Price, Quote:
• Configuration Run-Time Data Services APIs
• Configuration Administration REST APIs
Building on this foundation, the feature further supports some asset-based operations
whereby the configuration model retrieved from Oracle CPQ represents an existing asset.
This lets the shopper execute the following configuration-related Asset Operations via direct
API calls to the Oracle Configure, Price, Quote Configuration API:
2-61
Chapter 2
Use the Integration Functionality
• Modify
• Upgrade
Available Storefront and Agent endpoints for this feature let you modify and upgrade
assets via direct API calls to Oracle Configure, Price, Quote thus removing the need to
include an iFrame in this part of the shopping experience as well. This feature is
limited to API only and customers will need to build their own UI elements to invoke
these new endpoints.
By creating your own Modify and Upgrade user interface elements, you can deliver a
seamless and consistent user experience even when modifying or upgrading complex
products or services. The shopper user interface experience while modifying or
upgrading a service can then be consistent with the rest of the site navigation
experience as configuration user interface controls can be created in compliance with
the Site Theme and CSS being used.
To fully implement the Asset Operations portion of this feature you must:
• Download and install the CpqConfiguratorStoreApp and
CpqConfiguratorAgentApp SSEs
• Create a ‘Modify’ user interface element which can be coded into the Asset Details
widget (which is not elementized)
• Create an ‘Upgrade’ user interface element which can also be coded into the
Asset Details widget
The creation of the user interface elements should be a straightforward process for
any developer partner with a working knowledge of Commerce development and
knockout.js.
Refer to Use Asset Based Ordering for more information on these Asset Operations.
Understand Sys Config model support via Commerce and the Oracle Configure,
Price, Quote Configuration API
In Oracle Configure, Price, Quote, certain parts of customizable (configurable)
products are based on "Sys Config" models that are accessible via the Oracle
Configure, Price, Quote Configuration API. The "Sys Config" model consists of a
hierarchy of components and associated classes that are used to model the
hierarchical nature of the Product and Promotion structure of that configurable product.
When products in Oracle Configure, Price, Quote are structured hierarchically, Product
Families are created first. Families provide the broad classifications of products. The
next parts created are Product Lines which are used to describe more specific product
areas of Product Families. Finally, Models are created to provide detail about the most
specific product traits.
Note: In a "Sys Config" model, an attribute of a model can also be another model so it
is important that you fully understand the structured hierarchy of each product family.
Examples of the product hierarchies just described might look something like the
following:
• Product Family: "Business Laptop"
– Product Line: “EZCompute”
* Model: "EZ"
* Model: "EZ Pro"
2-62
Chapter 2
Use the Integration Functionality
2-63
Chapter 2
Use the Integration Functionality
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
2-64
Chapter 2
Use the Integration Functionality
(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.
2-65
Chapter 2
Use the Integration Functionality
2-66
Chapter 2
Use the Integration Functionality
– Pick Lists
These components are presented as the default mapping for the corresponding Oracle
Configure, Price, Quote model attributes and layout.
• Publish your changes.
2-67
Chapter 2
Use the Integration Functionality
Control user interface look and feel using the CPQ Configuration API
The Direct API Configuration feature lets you control user interface "look and feel"
using the Oracle Configure, Price, Quote Configuration API.
You can use the Direct API Configuration feature to control user interface "look and
feel" using the Oracle Configure, Price, Quote Configuration API. This ability lets you
do things like the following:
• Apply a site-specific "Look and Feel" product customization to the user interface
experience.
• Apply site-specific user interface components for a custom user interface
experience.
• Add a new UI component to the configuration flow.
• Remove tabs from the product customization user interface experience.
• Apply a product type specific set of user interface components to the configuration
flow.
Before you can accomplish these tasks, you must first make sure that the API driven
configuration feature has been implemented (described in the previous topic). Also, it
is assumed that the Commerce and Oracle Configure, Price, Quote Integration has
already been configured and enabled.
In the sections that follow, you are provided with details for using this feature to carry
out these customization tasks.
2-68
Chapter 2
Use the Integration Functionality
Note: The included version of the JavaScript Library of Knockout UI Components used to
render the Layout response from Oracle Configure, Price, Quote uses OOTB theme/
styles, (i.e., Bootstrap Forms and Components). Also, by making changes at the provided
Theme level, you can change the look and feel of the configuration UI experience without
making any changes directly to the UI elements or JS Library.
• Clone the provided the theme and apply the required specifications for:
– Backgrounds
– Buttons
– Navigation Menu
– Menu
– Typography
This is done directly in the Design page.
• Use the Design page to access the theme's CSS and apply all of the remaining UI
specifications.
• Save all your changes.
• Navigate to Layout → Product Layout → Layout Settings.
• Set the Layout Preview Product ID for 4ForU Deal offer, this is a configurable product
which allows shoppers to 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.
• The system displays the configurable options available in a combination of UI
components such as the following:
– Panels
– Tabs
– Input fields
– Radio buttons
– Checkboxes
– Multi -select lists
– Single select lists
– Date pickers
– Pick Lists
You can now see that all of the user interface components are displayed in accordance with
the new theme that you have created and are in accordance with the rest of the site.
Apply site-specific user interface components for a custom user interface experience
A case may arise where a customer wants the customization user interface experience to be
slightly different from the rest of the site to convey the feeling of personal design when they
are building their tailored product.
The customer's in-house design and brand management team has provided specifications to
make changes to the following user interface elements:
2-69
Chapter 2
Use the Integration Functionality
2-70
Chapter 2
Use the Integration Functionality
Add a new user interface component to the configuration user interface flow
Sometimes a customer may want new to add a new user interface component that shoppers
will use to select an image that will be imprinted on the shopper's mobile phone case.
In this example, the customer's in-house design and brand management team have
developed a new "Image Carousel" user interface component that shoppers will use to select
the image to be imprinted. This new user interface component is used as the user interface
control for Oracle Configure, Price, Quote model attributes which require the shopper to
select an image.
2-71
Chapter 2
Use the Integration Functionality
As a member of the SI user interface design team, you are instructed to ensure that
this new user interface component is displayed correctly in Commerce. To add the new
user interface component to the configuration user interface experience via direct API,
complete the following tasks:
• Log in to Commerce Admin and navigate to Settings → Extensions and do the
following:
– Deactivate the Oracle Configure, Price, Quote Configurator user interface
extension.
– Delete the Oracle Configure, Price, Quote Configurator user interface
extension. This extension includes the direct API versions of the Configure
and Reconfigure user interface elements as well as a common JavaScript
Library of user interface Components used to render the Layout response from
Oracle Configure, Price, Quote.
• Create new versions of the JavaScript Library to include the new 'Image Carousel'
user interface component, including HTML, JavaScript and Style Definitions which
must also be added to the global stylesheet.
• Bundle the user interface elements and new JavaScript library into a single
extension that can be uploaded in a single step.
• Navigate to Settings → Extensions and upload the edited version of the Oracle
Configure, Price, Quote Configurator user interface extension.
• Reapply the '"Customize via direct API" for Configure.
• Preview the product layout and make sure that the new image carousel user
interface component renders correctly when customizing a product.
• Preview product layout and make sure that the new image carousel user interface
component renders correctly when reconfiguring a product.
• Publish your changes.
Upon completing these tasks, you should see that the product customization user
interface now includes a new user interface component in accordance with the
customer's specifications.
2-72
Chapter 2
Use the Integration Functionality
• Navigate to Settings → Extensions and upload the edited version of Oracle Configure,
Price, Quote Configurator user interface Extension.
• Reapply the "Customize via direct API" for Configure Preview the product layout and
make sure that there are no tabs displayed when customizing a product.
• Preview the product layout and make sure that there are no tabs displayed when
reconfiguring a product.
• Publish you changes.
Upon completion of these tasks, you will note that the product customization user interface no
longer displays any tabbed layout in accordance with the customer's specifications.
Apply a product type specific set of user interface components to the configuration
flow
In this case the, the customer's in-house design and brand management team want the
shopper's configuration experience to be different when they customize shippable goods (for
example, "Build your own laptop") and when they customize services such as the Phones4All
offer.
For this, a new set of "Service Configuration user interface Components" has been developed
by the in-house design and brand management team for the following:
• Buttons
• Input Fields
• Checkboxes
• Multi-select lists
• Single select list
• Date pickers
• Color pick list
As a member of the user interface design team, you are instructed to ensure that when a
shopper is customizing a service these new user interface components will be displayed. This
is done by completing the following tasks:
• Log in to Commerce Admin.
• Navigate to Settings → Extensions.
• Deactivate the Oracle Configure, Price, Quote Configurator user interface extension.
• Delete the Oracle Configure, Price, Quote Configurator user interface Extension. This
extension includes the direct API versions of the Configure and Reconfigure user
interface elements as well as the common JavaScript Library.
• Edit the JavaScript Library by adding conditional IF statements that map the Oracle
Configure, Price, Quote user interface components to the new "Service Configuration
user interface Components" where Product Type = Service.
• Navigate to Settings → Extensions and upload the edited version of Oracle Configure,
Price, Quote Configurator user interface extension.
• Reapply the "Customize via direct API" for Configure.
• Publish your changes.
• Create a new "Services Product Layout" for products where Product Type = Service.
2-73
Chapter 2
Use the Integration Functionality
2-74
Chapter 2
Use the Integration Functionality
Apply customizations to a product by directly using the Oracle Configure, Price, Quote
Configuration API
The list of tasks that follow describe a situation where a shopper customizes a product where
the Direct API Configuration feature has been implemented in Commerce.
In this case, a System Integration Partner has already implemented the feature and the SI
user interface design team may have already done some user interface customizations by
directly using the Oracle Configure, Price, Quote Configuration API.
For this example, it is assumed that the Commerce and Oracle Configure, Price, Quote
Integration is already configured and enabled.
Use the following guidelines to accomplish the specified goals.
• As an example, let us say that the shopper has noticed a lot of web advertising by their
cell phone service for their new Phones4All offer which allows them to buy a single deal
with phones and plans for up to 6 people at huge savings on handsets, accessories and
monthly bills.
• The shopper navigates to their cell phone service and selects the Phones4All offer. The
shopper selects to customize the offer. The UI element Customize Button for Direct
API invokes the .../v1/configurations SSE endpoint passing the following
parameters:
– productFamily
– productLine
– model
– locale
– currency
– configurationMetadata
• The .../v1/configurations SSE endpoint triggers the following Oracle Configure,
Price, Quote API endpoints:
– GET_configUISettings
– GET_pageTemplates
– POST_config
– GET_Layout_ Cache
• The .../v1/configurations SSE collates the data returned from Oracle Configure, Price,
Quote, strips out all extraneous information, and returns a "combined configuration data
response."
• The shopper is presented with a set of customization options that they can use to tailor
the offer to their specific needs.
• The first option the shopper is presented with is the number of lines required.
• The shopper selects 4 lines.
• The shopper selects Next.
• The UI element Customize Button for Direct API invokes the .../v1/configurations/
{cacheInstanceId}/page SSE endpoint (where cacheInstanceId represents the current
2-75
Chapter 2
Use the Integration Functionality
2-76
Chapter 2
Use the Integration Functionality
• The shopper selects the 256GB capacity option for the handset.
• The UI element Customize Button for Direct API checks the isUpdatable property for
the handset attribute. The isUpdatable property value is FALSE (this means that when
an option is selected for this attribute the configuration model need not be updated as this
selection does not impact other model attributes).
• The shopper completes the customization for Line 1 and moves on to line 2.
• When the shopper is part way through the customization of Line 2, they decide that they
may need to make a change to the handset capacity for Line 1.
• The shopper selects Previous.
• The UI element Customize Button for Direct API invokes the .../v1/configurations/
{cacheInstanceId}/page SSE endpoint (where cacheInstanceId represents the current
reconfiguration instance in Oracle Configure, Price, Quote) passing the following
parameters:
– productFamily
– productLine
– model
– locale
– currency
– op: previous
• The .../v1/configurations/{cacheInstanceId}/page SSE endpoint triggers the
POST_previous and GET_Layout_ Cache Oracle Configure, Price, Quote API endpoints.
• The .../v1/configurations/{cacheInstanceId}/page SSE collates the data returned
from Oracle Configure, Price, Quote, strips out all extraneous information, and returns a
"combined configuration data response."
• The shopper is presented with the configuration options that they selected for Line 1.
• The shopper changes the capacity for the Line 1 handset and continues to customize the
rest of the lines.
• The shopper completes the customization of their Phones4All offer.
• The shopper selects Add to Cart.
• The UI element Customize Button for Direct API invokes the .../v1/configurations/
{cacheInstanceId}/add-to-cart SSE endpoint (where cacheInstanceId represents the
current reconfiguration instance in Oracle Configure, Price, Quote) passing the following
parameters:
– productFamily
– productLine
– model
• The .../v1/configurations/{cacheInstanceId}/add-to-cart SSE endpoint triggers
the POST_integration_add_to_cart Oracle Configure, Price, Quote API endpoint.
• The .../v1/configurations/{cacheInstanceId}/add-to-cart SSE transforms the
Oracle Configure, Price, Quote response to a Commerce cart item and adds the
configured item to the Commerce cart.
• The shopper proceeds to checkout.
2-77
Chapter 2
Appendix A: Configurator Flow
When all of this has completed, a multi-level configured item is added to Commerce
cart.
2-78
Chapter 2
Appendix B: Request for Quote Flow
2-79
3
Integrate with Oracle Content Management
Oracle Commerce provides an integration with Oracle Content Management that you can use
to display content items such as blog posts and articles on your storefront.
Oracle Content Management is a cloud-based hub for managing your content and other
digital assets. The integration enables you to create and manage a wide range of content,
and make it available on your Commerce sites. Possible uses include:
• Creating a blog or article template so any content published is automatically available
and is formatted correctly for access by shoppers and by search engines.
• Creating pages to dynamically display lists of content targeted to specific focus areas; for
example, items that mention boots.
The Oracle Content Management features you can access, and the UIs you can view,
depend on your assigned role. For more information, see the Oracle Content Management
documentation available in the Oracle Help Center.
3-1
Chapter 3
Configure Storefront Classic to display content items
Classic framework. The next two sections describe how to use the Design page in the
administration interface to enable access to this content from each storefront
framework.
3-2
Chapter 3
Configure an OSF storefront to display content items
By default, all content items are rendered using the default Content Item Layout. However,
you can create another version of that layout for specific content types by cloning the Content
Item Layout and configuring the cloned layout to associate it with a specific content type. You
may need to modify the instance of the Content Item widget in the cloned layout to ensure
content items are displayed properly on the page.
3-3
Chapter 3
Configure an OSF storefront to display content items
1. In the Content Field dropdown, select the field to use in the query. (The values in
the dropdown are taken directly from the item type.)
2. In the Operator dropdown, select the operator to use. (The operators listed are
ones that are appropriate for the type of data in the field.)
3. In the Value input, enter the value to apply the operator to.
4. Click Save.
For example, if the content type is Article, you might select the Title field, then select
the Contains operator, and enter the value baseball. If this query is applied, the items
listed by the widget will be articles whose title contains "baseball."
You can create multiple queries for a single Content Listing widget instance. If you do
this, a toggle switch appears for specifying how to combine them. Click All to list only
those items that match all of the queries, or Any to list all items that match any of the
queries.
3-4
Chapter 3
Configure an OSF storefront to display content items
3-5
4
Integrate with Customer Data Management
Integrate Oracle Customer Data Management with Oracle Commerce.
You can configure your Commerce environment to integrate with Oracle Customer Data
Management (CDM), a cloud-based application for managing organizations and contacts.
Accounts, contacts and their relationships and addresses can be synchronized from CDM to
Oracle Commerce. Similarly, accounts and contacts that are created either through self-
registration or a delegated administrator can be synchronized with CDM in real time. The
integration between Oracle Commerce and CDM occurs by both applications communicating
through Oracle Integration Cloud (OIC), a cloud-based communication platform.
For information on obtaining, installing and configuring OIC, refer to https://
docs.oracle.com/en/cloud/paas/integration-cloud/index.html.
Integrating between CDM and Oracle Commerce allows you to create scheduled jobs that
identify changes to data and then perform the following actions:
• Synchronize in bulk or individually accounts that have been created or updated in
Commerce to CDM in real time.
• Synchronize in bulk or individually contacts and profiles that have been created or
updated in Commerce to CDM in real time. Additionally, you can associated contacts to
an account during the synchronization process.
• Maintain organization hierarchy between synchronizations.
Steps and requirements for the integration
Before you can configure the integration, ensure that you have the following:
• An Oracle Commerce account and access to Oracle CX Commerce 21A or later.
• An Oracle Customer Data Management account and access to CDM 21A or later.
• An Oracle Integration Cloud (OIC) account and access to the Oracle Integration Cloud
Service.
If you require one or more of these applications, please contact your Oracle sales
representative: http://www.oracle.com/us/coporate/contact/index.html.
4-1
Chapter 4
Integrate with Customer Data Management
The integration is delivered as a .par file. To download and import the integration,
perform the following:
1. Open the integration package OCC-OEC_Integration.
2. Import the package by logging into OIC as an admin user.
3. Click the Packages button.
4. Click the Import button.
5. Click Browse to open the navigation pane.
6. Select the OCC-OEC_Integrations package.
7. Click Import.
The package is added to the packages list.
Understand integrations
The OCC-OEC_Integrations package contains three connections and six integrations.
When OEC encounters a file that contains more than 50 thousand records, it splits the
records into multiple CSV files. However, the OIC integration does not support the
conversion of multiple CSV files into JSON files. Should your export file contain more
than 50 thousand records, it will be divided into multiple files, however these files will
not be converted. To prevent this from occurring, ensure that you do not export more
than 50 thousand records at a time.
You should also ensure that CDM is configured to store states using the abbreviated
state format, such as CA or VT. This is required because Commerce stores the state
values in the abbreviated format.
The following diagram shows the flow of the integration:
4-2
Chapter 4
Integrate with Customer Data Management
4-3
Chapter 4
Integrate with Customer Data Management
Note that when synchronizing account and contact data from Commerce to CDM, the
default shipping address in Commerce is marked as the primary shipping address in
CDM. Additionally, accounts that are synchronized from Commerce to OEC are
marked as type = CUSTOMER in OEC.
4-4
Chapter 4
Integrate with Customer Data Management
Note that when synchronizing account and contact data from Commerce to CDM, the default
shipping address in Commerce is marked as the primary shipping address in CDM.
Additionally, accounts that are synchronized from Commerce to OEC are marked as type =
CUSTOMER in OEC.
4-5
Chapter 4
Integrate with Customer Data Management
4-6
Chapter 4
Integrate with Customer Data Management
.../ic/api/integration/v1/flows/rest_oraclecommercecloud/
UPDA_PROF_SYNC_FROM_OCC_TO_OEC/1.0/
or
https://CDMServer/crmRestApi/resources/latest/bulkExportActivities.
4-7
Chapter 4
Integrate with Customer Data Management
4-8
Chapter 4
Integrate with Customer Data Management
4-9
5
Integrate with Oracle Eloqua
The Eloqua Integration with Oracle Commerce enables merchants to market their products
and services by creating campaigns that seamlessly incorporate Commerce actions and
data.
These campaigns allow merchants to react quickly to market trends and customer behaviors.
They make it possible to deliver conversion and incentive-based actions, such as granting a
Commerce promotion upon shopper registration and providing special offers to registered
shoppers.
The integration is implemented as a Commerce Connector that runs within Eloqua and
facilitates movement of data and actions between the two platforms. The connector provides
an import process for Account and Contact data attributes, based on default mappings and
merchant modifications. Detailed reports enable monitoring the import process and correcting
issues. The integration adds campaign actions to Eloqua that create profiles in Commerce for
existing Eloqua contacts and that grant Commerce promotions to contacts, thus enabling
these contacts to purchase products and services.
This chapter describes how to install and configure the connector, and how to use the
Commerce actions it makes available to Eloqua. The chapter assumes you are already
familiar with creating campaigns in the Eloqua user interface. Note that many of the steps
described in this chapter, including installing integration apps such as the Commerce
Connector, are also described in the Eloqua documentation.
Note: To use the Eloqua Integration, you must be running Oracle Commerce version 22A
Revision 8 (22.1.8) or later.
5-1
Chapter 5
Configure the Commerce Connector
After you install the Commerce Connector, it will appear on the AppCloud Catalog
page under My Apps. Clicking on the connector takes you to a page for managing the
app. On this page, click on the Configure icon:
Clicking the Configure icon opens a frame with options for configuring the app:
Notice that the frame has four tabs on the left for performing the various configuration
steps. The remainder of this section describes these tabs.
You can learn more about the options for managing apps here:
https://docs.oracle.com/en/cloud/saas/marketing/eloqua-user/Help/Apps/
ManagingInstalledApps.htm
5-2
Chapter 5
Configure the Commerce Connector
In the URL field, enter the URL for accessing the administration interface of your Commerce
instance. Do not include a slash at the end. The URL format should be similar to the
following:
https://myccadmin.occa.us-ashburn-1.ocs.oc-test.com
In the Application Key field, supply the application key that has been created for you in
Commerce. In the Commerce administration interface, go to Settings > Web APIs >
Registered Applications:
Click on Oracle Marketing Connector. In the frame that opens, click the button to reveal the
application key, then select and copy it. Paste the application key into the Application Key
field in Eloqua and click Save.
For more information about using application keys for authentication in Commerce, see
REST API authentication.
5-3
Chapter 5
Configure the Commerce Connector
There are two entities you need to configure, Account and Contact, which you can
select from the Eloqua dropdown. When you select an entity, the current mappings for
that entity are displayed. The recommended mappings are configured by default, but
you can optionally modify these mappings by selecting different Commerce attributes
from the dropdowns on the right. Each entity includes a custom Eloqua attribute
(Oracle Commerce Account ID and Oracle Commerce Contact ID) that is created
by the Commerce Connector. Each of these Eloqua attributes is mapped to the ID
attribute of the corresponding Commerce entity.
Notice that a toggle labeled Sync Commerce Contact Events appears below the
Eloqua dropdown when Contact is selected. If this setting is enabled, the connector
detects when a contact is created or modified in Commerce and automatically imports
the contact into Eloqua. (There is also a Sync Commerce Account Events toggle
that appears when Account is selected.) You can also perform bulk imports of
contacts and accounts using the Import tab, as described below. Bulk import can be
used for initial syncing of the data, while event-based syncing can be enabled for
ongoing updates.
After you finish configuring the mappings, click Save.
Note that you can also map custom properties between Commerce and Eloqua.
Custom properties that are string, number, Boolean or date can be mapped to Eloqua
properties of the same type. If the Commerce property data type is not one of these
four types, it is mapped to Eloqua as a string type.
5-4
Chapter 5
Configure the Commerce Connector
The configuration from the Mapping tab specifies the Commerce properties that are used to
update equivalent Eloqua attributes. To specify the import parameters, do the following:
• Select the checkboxes for the entities whose data you want to import. You can select
Account, Contact, or both.
• You can optionally use the calendar UI control to specify a date. If you do this, only
Commerce data that has been created or modified since the specified date will be
imported. If you do not specify a date, all of the data for the mapped properties will be
imported. You may want to specify a date in order to test your attribute mapping with a
smaller dataset before syncing all records.
Click Import to initiate the import process. A report about the progress of the import will be
generated for each entity selected. You can view these reports on the Reports tab.
View reports
The Reports tab displays tables listing recent reports that can be selected for viewing. There
are three subtabs available:
• Bulk Import – Lists reports of bulk imports of contacts and accounts from Commerce to
Eloqua.
• Event – Reports errors from Commerce events tracked by Eloqua. Supported events
include New Contact, Update Contact, New Account, Update Account, and Abandoned
Cart.
• Action – Reports errors from Commerce actions triggered in Eloqua campaigns.
Supported actions include Register Shopper and Grant Promotion.
For example, the Bulk Import subtab displays a table that contains information about each
bulk import job, including its status:
5-5
Chapter 5
Use Commerce actions in Eloqua campaigns
To view a report, click the associated ellipsis icon (. . .) on the right, and select View
Report from the dropdown. The report contains information about each stage of the
process:
If an import is currently running, the ellipsis dropdown for that job includes an Abort
option that you can use to cancel the import. Note that if any data has already been
imported into Eloqua, canceling the job will not delete the data. You may need to purge
the records manually.
5-6
Chapter 5
Use Commerce actions in Eloqua campaigns
The campaign elements toolbar should look similar to the following. Note the Commerce
Actions element at the bottom:
The Commerce Actions element supports two Commerce actions, Register Shopper and
Grant Promotion, which you can use in Eloqua campaigns. For example, you could create a
campaign that, when a new contact is created in Eloqua, automatically creates a Commerce
profile for that user and grants a promotion to them.
To add a Commerce action to a campaign, drag the Commerce Actions icon from the toolbar
onto the canvas, then double-click on the new action. The following dialog box appears:
5-7
Chapter 5
Use Commerce actions in Eloqua campaigns
5-8
Chapter 5
Use Infinity to trigger Eloqua campaign actions
3. From the Action dropdown, select Grant Promotion. Two new fields appear, Commerce
Site and Promotion:
4. From the Commerce Site dropdown, select the Commerce site the promotion is
associated with. If you select an individual site, the Promotion dropdown will show only
the promotions associated with that site. If you choose Select All, the Promotion
dropdown will show all available Commerce promotions.
5. From the Promotion dropdown, select the promotion to grant.
6. Click Save.
You can modify a Commerce action by double-clicking on it and changing the current values.
Note, however, that you cannot change the action type.
Notes about granting promotions
The Promotion dropdown lists both published and unpublished promotions, but only
published promotions can be granted. If you select an unpublished promotion, you must be
sure to publish it to enable the campaign to grant it.
If the selected promotion has an associated coupon, the shopper will not need to provide a
coupon code at checkout in order for the promotion to be applied. Note, however, that
granting a promotion only makes the shopper eligible to receive the promotion; it does not
automatically mean it will be applied. Many factors determine whether or not a promotion is
applied, including the conditions of the promotion, its priority relative to other promotions, and
promotion stacking rules.
If the selected promotion does not have an associated coupon, the promotion will not be
applied.
Promotions can be granted to an unregistered shopper, for if a profile ID is not found, the
system will use the email ID received from Eloqua.
5-9
Chapter 5
Use Infinity to trigger Eloqua campaign actions
This section describes how to use Infinity, Eloqua, and Commerce together. Note that
you must have licenses for all three products to do this.
For further information about the Commerce integration with Infinity, see Integrate with
Oracle Infinity to collect data.
5-10
Chapter 5
Use Infinity to trigger Eloqua campaign actions
To define a stream, you specify a query in Infinity Streams. This query determines what data
fields are monitored. Infinity Streams are described here:
https://docs.oracle.com/en/cloud/saas/marketing/infinity-user/Help/streams.htm
This topic and the ones that follow it describe what streams are, the query syntax for streams,
and how to use the Streams UI to create and monitor streams that track events during visitor
sessions on your sites.
In this integration, the data in the streams should include properties that are sent to Infinity
from a Commerce site. (Commerce embeds the Infinity tag in pages to execute calls that
pass the data via query parameters that Infinity recognizes.) The query you create in Infinity
Streams specifies the parameters to monitor and associates them with the corresponding
Commerce properties.
For example, you could use the following query to monitor Commerce data sent to Infinity:
*, LATEST(data.wt.pn_sku) AS 'skuIds',
LATEST(data.wt.pn_name) AS 'productName',
LATEST(data.wt.page-url) AS 'productUrl',
LATEST(data.wt.oss) AS 'search',
data.wt.z_email AS 'email'
WHERE session.closed='true'
AND EXISTS(data.wt.z_email)
AND ANY(data.e='v')
AND ALL(data.wt.tx_e!='a')
AND ALL(data.wt.tx_e!='p')
HAVING data.wt.cg_n like '*'
AND data.wt.pn_sku like '*'
AND data.wt.tx_e='v'
Note that Commerce sends some of these parameters only from Open Storefront Framework
(OSF) storefronts:
• wt.pn_name – the name of the Commerce product
• wt.page-url – the URL of the product detail page for the Commerce product
• wt.z_email – the shopper’s email address
5-11
Chapter 5
Use Infinity to trigger Eloqua campaign actions
• Creating a campaign that uses the Infinity Feeder to trigger the Eloqua Email
campaign step when the Abandoned Browse is detected.
Create an Abandoned Browse action
For this example, an Abandoned Browse is determined to occur when all of the
following conditions are met:
• The shopper has logged in and has a known email address. This is necessary so
an email can be sent to the shopper.
• The shopper has viewed a product they navigated to or searched for.
• The session has ended (either by logging out or timing out) without the shopper
putting anything in the shopping cart.
You define the action in the Infinity Action Center and map the Infinity parameters to
Eloqua fields so they can be used in campaigns. The following section describes this
process:
https://docs.oracle.com/en/cloud/saas/marketing/eloqua-user/Help/Apps/Infinity/
ACFeeder/Tasks/InstallingInfinityACFeeder.htm
Use the stream that you created to track Commerce activity.
Create an Abandoned Browse email
Next, create an email to be sent to the shopper when an Abandoned Browse is
detected. You do this in the Eloqua email Design Editor, as described here:
https://docs.oracle.com/en/cloud/saas/marketing/eloqua-user/Help/EmailEditing/Tasks/
CreatingNewEmailsDesign.htm
The following graphic illustrates creating an Abandoned Browse email in the Design
Editor:
Notice that the Field Merge Browser enables you to embed a number of Eloqua fields
in your email, including fields that have been imported from Commerce. This capability
enables you to include Commerce data in the email, such as the name and URL of the
product the shopper was viewing before abandoning browsing.
Create a campaign that sends the email
5-12
Chapter 5
Use Infinity to trigger Eloqua campaign actions
Now create an Eloqua campaign that uses the Infinity Feeder to trigger the Email campaign
step when an Abandoned Browse is detected. This sequence can be a standalone campaign
or part of a larger campaign.
In Eloqua, the Infinity Feeder will appear in the toolbar on the campaign canvas. Drag the
icon onto the canvas, then double-click on the icon to configure the feeder:
Click the pencil icon to open a dialog where you can select an Infinity action. Select the
Abandoned Browse action, and then click Save:
Now drag the Email icon onto the canvas, then double-click it and select the Abandoned
Browse Mail:
5-13
Chapter 5
Configure Eloqua Campaign Attribution
Now connect the Infinity Feeder icon to the Email icon, so that when you run the
campaign, an email will be sent whenever an Abandoned Browse is detected:
5-14
Chapter 5
Configure Eloqua Campaign Attribution
For additional information on configuring Eloqua email, refer to your Eloqua documentation.
5-15
Chapter 5
Configure Eloqua Campaign Attribution
This allows Eloqua and Commerce to track campaign information whenever a recipient
of an Eloqua email access your storefront and places an order.
widget.createOrderSuccessCallBack = function(data) {
var campaigns = (data.markers && data.markers.length) ?
widget.order().getCampaigns(data.markers) : [];
...
}
Once the order has moved to the SUBMITTED state, publish the Eloqua campaign data
using the following code:
if (data.state == CCConstants.SUBMITTED ) {
widget.publishOrderSubmission(data.id, data.uuid, cartItems,
campaigns);
...
}
5-16
Chapter 5
Configure Eloqua Campaign Attribution
To use the campaign IDs and sources for reporting purposes, you must split the campaign ID
and the campaign source in Infinity and then co-relate them. To do this:
1. Log into the Infinity server that is integrated with both Commerce and Eloqua.
2. From Settings, select Parameters.
3. Select Named parameters from the drop-down list.
4. Search for Campaign ID or wt.z_campaignId.
5. Click on the Campaign ID parameter and select Edit from the Settings menu.
6. Use the Advanced Options link to click the + drop-down and select Add Split on
Character rule.
7. Enter a semicolon (;) in the Split parameter on section.
8. In the Co-relate to section, add the Campaign source, or the wt.z_campaignSource
parameter name.
9. Save your changes.
You must repeat these steps for the Campaign source parameter. Note that the Co-relate to
section is filled with the Campaign ID.
This allows Infinity to report an order attributed to different campaigns.
Create a report for Eloqua campaign conversions
You can use the Funnel for campaign conversion to create a report in Infinity:
1. Log into the Infinity server that is integrated with both Commerce and Eloqua.
2. Go to the Analytics section and choose one of the report spaces.
3. Click on New and Select Funnel.
4. Once the Funnel dialog opens, enter the Name, Permission, Category and
Visibility and then click Save.
5. On the funnel report, click Add Funnel Steps.
6. For Step 1, provide the following information: Step Name is Email Send. Parameter is
Event Type and Parameter Value is EmailSend.
7. For Step 2, provide the following information: Step Name is Email Open. Parameter is
Event Type and Parameter Value is EmailOpen.
8. For Step 3, provide the following information: Step Name is Submit Order. Parameter
is Page Views and Parameter Value is Order Submission Success.
9. Click on Segment, then Add Segment and then Create Segment.
10. Search for Eloqua's Campaign ID parameter and drag it to the Drop parameters here
section. Note that the Eloqua Campaign ID equals Campaign ID, which is the campaign
ID for which the report is generated.
11. Search for Commerce's Campaign ID parameter and drag it to the Drop parameters
here section. Note that the Commerce Campaign ID equals the Campaign ID, which is
the campaign ID for which the report is generated.
12. Join the two clauses using the OR operator from the drop-down menu.
13. Enter the Segment name and description and click Save.
5-17
Chapter 5
Create an Abandoned Carts Email Campaign
5-18
Chapter 5
Create an Abandoned Carts Email Campaign
5-19
Chapter 5
Create an Abandoned Carts Email Campaign
5-20
6
Integrate with an External Product
Configurator
Integrate an external product configurator with Oracle Commerce.
When your store is configured to sell configurable products, you may want to integrate with
an external product configurator. The recommended configuration is to integrate with Oracle
CPQ, however, you can also integrate with a third-party configurator application.
6-1
Chapter 6
Add Customize button to Product Details widget
9. Click Save. This returns you to the SKU frame, where the SKU you updated
should be marked with an asterisk to identify it as a configurable SKU.
Note: Administrators can also perform the above setup steps in bulk by using the
SKU import program. From the Catalog page in Commerce, click Manage Catalog
and select Import. In the Import dialog, click Browse and locate the CSV file to
import. Click Upload File, click Validate, and then click Import.
6-2
7
Integrate with Oracle Infinity to collect data
Through an integration between Oracle Commerce and Oracle Infinity, the Commerce Data
Ingestion feature lets you use a Universal JavaScript tag that ingests all Commerce
Storefront events and sends the data to the Infinity data repository for analytic purposes.
By using this feature, Oracle provides the Customer Data Platform (CDP) system with data
that lets marketers dynamically generate audience segments based on current and past
behaviors and data attributes.
As a critical part and foundation of the CDP, the Oracle Management Cloud (OMC) Universal
Data Ingestion Framework (DIF), by integrating with the Oracle Infinity technologies,
establishes the common data ingestion framework for collecting Commerce product
behavioral data.
7-1
Chapter 7
Understand the role of the Infinity platform in data ingestion
7-2
Chapter 7
Tag site pages to use the Infinity data ingestion feature
• Library - The Library application provides you with a way to administer reports, measures,
dimensions, segments, and any other objects that you can administer.
You may encounter the following Infinity terminology when trying to work with the Commerce
and Infinity integration to successfully collect the data that best works for you:
• Account GUID – A unique value used to identify your account. All collected data is stored
in one place for an account. All tags on an account use the same account GUID.
• Tag Id – Tag identifier used to put your tags into a hierarchical format. Each tag has a
unique ID that may be set at creation time.
• Context – A Context tag is a unique tag configuration selectable by query parameter. You
may only have one active context at a time for a tag, though you may have multiple
contexts configured for an individual tag.
• Plugin – An add-on to the tag that enables tracking libraries for functions outside of what
the base tag tracks.
For more complete details on using Infinity and its capabilities, refer to the Oracle Infinity
documentation.
A setting for Infinity is available in Commerce Admin application under the Integrations tab.
After enabling the setting, provide the Infinity Tag URL obtained from Infinity in the
Production URL field.
Note: The GUID and tagID are unique strings for your site and tag.
For more complete details on using Infinity and its capabilities, refer to the Oracle Infinity
documentation.
7-3
Chapter 7
Understand Infinity integration parameter mapping
7-4
Chapter 7
Understand Infinity integration parameter mapping
7-5
Chapter 7
Understand Infinity integration parameter mapping
7-6
Chapter 7
Understand Infinity integration parameter mapping
7-7
Chapter 7
Understand Infinity integration parameter mapping
7-8
Chapter 7
Understand Infinity integration parameter mapping
7-9
Chapter 7
Understand Infinity integration parameter mapping
7-10
Chapter 7
Understand Infinity integration parameter mapping
7-11
Chapter 7
Understand Infinity integration parameter mapping
For more complete details on using Infinity and its capabilities, refer to the Oracle
Infinity documentation.
7-12
8
Integrate with Oracle Order Management
Cloud
Integration Oracle Order Management Cloud with Oracle Commerce.
Oracle Order Management Cloud can improve order handling when working with order-to-
cash processes. You can configure fulfillment monitoring, global availability and enterprise-
wide policies that increase your shopper's satisfaction.
Introduction
Oracle Commerce and Oracle Order Management Cloud can be combined through Oracle
Integration Cloud to provide a robust architecture for capturing and fulfilling orders placed in
your online store.
Oracle Commerce is an industry-leading commerce platform re-designed for the modern
cloud. Oracle Order Management Cloud is tightly integrated with Oracle Global Order
Promising Cloud. It can improve order handling across the order-to-cash process. Pre-
integration, centrally-managed orchestration policies, global availability, and fulfillment
monitoring can lead to increased customer satisfaction and order profitability.
This document describes how to integrate these two services.
Audience
This document is written for Commerce and Order Management Cloud administrators who
are setting up and configuring the integration between these two systems.
Readers of this document should have experience with both Commerce and Order
Management Cloud. See Additional documentation for links to comprehensive information on
these services.
Features
The integration of Commerce with Order Management Cloud combines the capabilities of
these two services into a single solution.
This solution provides support for the following:
• Pushing completed Commerce orders to Order Management Cloud for fulfillment.
• Retrieving and updating the status of the order from Oracle Order Management in
Commerce real time for the orders created using Commerce.
• Furnishing returns and exchanges created on Commerce to Order Management Cloud
for fulfillment.
• Retrieving the status of the returns from Order Management into Commerce.
The default integration assumes that the orders and returns are created using Commerce
channels.
8-1
Chapter 8
Prerequisites
Architectural overview
The message flow of business entities from Commerce to Order Management Cloud
happens through Oracle Integration Cloud.
Commerce includes an Oracle Integration Cloud adapter (the Commerce adapter) that
is used for the integration. The Order Management Cloud part of the integration uses
the generic SOAP adapter of Oracle Integration Cloud to manage the integration. Data
from the Commerce store is transmitted using webhooks through Oracle Integration
Cloud to reach Order Management Cloud. The data from Order Management Cloud
reaches Commerce through Oracle Integration Cloud as well.
Additional documentation
For information about Commerce, and the Oracle Order Management Cloud, refer to
the following Oracle Help Center pages:
Oracle Commerce documentation: First Steps.
Documentation of Oracle Order Management Cloud is available through Oracle
Applications Help: Oracle Order Management Cloud documentation.
For information about Oracle Integration Cloud and the Commerce adapter, refer to
Using the Oracle Commerce Adapter in the Oracle Help Center at this URL: Getting
Started with the Oracle CX Commerce Adapter.
Prerequisites
Prerequisites for a successful integration include specific access rights to both
systems. In addition, certain assumptions exist about the way each service is used.
This section provides details about the prerequisites.
Access rights
To configure this integration, you need administrator access to the following systems:
• The Oracle Commerce administration interface, which enables you to configure
the webhook settings.
• Oracle Integration Cloud, which enables you to map the attributes between
Commerce and Order Management Cloud. Note that in earlier releases, Oracle
Integration Cloud is referred to as Integration Cloud Service (ICS). The instructions
in this guide, as well as the integration itself, apply to both cases.
• Order Management Cloud, which enables you to set up the fulfillment and
configure the products and the activities associated with fulfillment.
Assumptions
This integration makes the following functional assumptions:
• Orders can be created only on Commerce channels. Orders created on non-
commerce channels are not within the scope of this integration.
8-2
Chapter 8
Configure Oracle Commerce for Oracle Management Cloud
• The Returns and exchange orders are initiated from Commerce. The cases where the
returns and exchanges are created on Order Management Cloud are not synched back
to Commerce.
• Commerce does not capture any credit card settlement information. It is assumed that
the merchant updates the card settlement information about Commerce.
• Purchase Order status payment groups are updated as settled/No Pending Action after
the payment processing is complete.
• The inventory and product SKU information is assumed to be in synch across both the
systems.
• Commerce acts as the pricing and the promotions engine.
• The tax calculation for an order is performed in Commerce.
• The scope of this integration is restricted to simple products. Configurable products are
out of its scope.
This integration is extensible: additional attributes can be mapped on both systems without
interfering with the merchant’s use cases.
8-3
Chapter 8
Configure the Oracle Integration Cloud Adapter
Connections
The integration package includes the required connections for the servers and events
used by the integration.
• Oracle Commerce: The connection to the Commerce admin server
• Oracle Commerce Agent: The connection to Commerce agent server
• Oracle Order Management Cloud: The connection to Order Management Order
synch service
• Oracle Order Management Cloud Events: The connection to Order Management
events
• Oracle Order Management Cloud Order Information Service: The connection to
the Order Management order retrieval service
8-4
Chapter 8
Configure the Oracle Integration Cloud Adapter
Lookup configuration
The mappings for the return status, carrier information, and shipping information are updated
as part of the lookup configuration.
You should modify these as required and as configured in your order management system.
Refer to the integration settings to view the lookups used.
Integrations
The package includes integrations for order synch, return synch, and order and return status
synch.
• Order synch from Commerceto Order Management
• Return synch from Commerce to Order Management
• Order and Return status synch from Order Management to Commerce
Unpack the OracleCommerce-OrderManagementIntegration.par package. It
unpacks into three inventory archives (IARs). Unpack each IAR and update the constants as
shown in the following sections. Update the following constants for order synch from
Commerce to the Order Management flow and import using the Oracle Integration Cloud
mapper in Oracle Integration Cloud.
XSL location
XSL location is described in the following section.
<Unpacked
iar>/icspackage/project/RETU_SYNC_FROM_COMM_TO_ORDE_MGMT_01.00.0000/
resources/processor_52/resourcegroup_913
<xsl:variable name="SOURCE_SYSTEM" select="'ATG'"
xml:id="id_2076"/>
<xsl:variable name="BUSINESS_UNIT_IDENTIFIER"
select="'204'" xml:id="id_2077"/>
<xsl:variable name="LEGAL_UNIT_IDENTIFIER"
select="'204'" xml:id="id_2078"/>
<xsl:variable name="FULFILLMENT_ORG_IDENTIFIER"
select="'207'" xml:id="id_2079"/>
<xsl:variable name="INVENTORY_ORG_IDENTIFIER"
select="'207'" xml:id="id_2080"/>
<xsl:variable name="UOM_CODE" select="'Ea'"
xml:id="id_2081"/>
Update the following constant for the return synch from Commerce to the Order Management
flow and import using the Oracle Integration Cloud mapper in Oracle Integration Cloud.
<Unpacked
iar>/icspackage/project/RETU_SYNC_FROM_COMM_TO_ORDE_MGMT_01.00.0000/
resources/processor_52/resourcegroup_913
<xsl:variable name="SOURCE_SYSTEM" select="'ATG'"
8-5
Chapter 8
Configure Order Management Cloud
xml:id="id_2076"/>
<xsl:variable name="BUSINESS_UNIT_IDENTIFIER"
select="'204'" xml:id="id_2077"/>
<xsl:variable name="LEGAL_UNIT_IDENTIFIER"
select="'204'" xml:id="id_2078"/>
<xsl:variable name="FULFILLMENT_ORG_IDENTIFIER"
select="'207'" xml:id="id_2079"/>
<xsl:variable name="INVENTORY_ORG_IDENTIFIER"
select="'207'" xml:id="id_2080"/>
<xsl:variable name="UOM_CODE" select="'Ea'"
xml:id="id_2081"/>
Note: The connection details that come as part of the integration package are empty.
You provide the details of the connections and test them. You can then enable the
integration.
8-6
Chapter 8
Configure Order Management Cloud
3. Create a source system for Commerce. If necessary, create a new code entry for
Commerce.
4. Select the time zone as required.
5. Disable the cross-references between Commerce and Order Management as the cross-
references are handled by Oracle Integration Cloud.
6. When you have finished entering the setup details, the final screen for the source system
appears:
8-7
Chapter 8
Configure Order Management Cloud
Note: Ideas for rules to create are provided here; you can configure these as
necessary for your business requirements.
This process ensures that the shipping and scheduling rules cover Commerce as a
channel.
8-8
Chapter 8
Configure Order Management Cloud
8-9
Chapter 8
Configure Order Management Cloud
8-10
Chapter 8
Configure Order Management Cloud
8-11
Chapter 8
Configure Order Management Cloud
8-12
Chapter 8
Configure Order Management Cloud
8-13
Chapter 8
Order creation
4. Create a name for the connector and provide the Oracle Integration Cloud
integration details in the connector URL.
5. Verify.
Order creation
Order creation in Commerce requires no change in the functional flow with respect to
this integration. In general, orders created in Commerce are sent to Order
Management Cloud for fulfillment. Several special cases are listed in this section.
The mechanism used to send the orders created in Commerce is webhooks.
Note: Commerce provides a remorse period during which shoppers can edit their
orders. The orders are sent to Order Management Cloud for fulfillment as soon as the
remorse period ends.
SKUs
Commerce supports simple SKUs. It can also support configurable SKUs through an
integration with Oracle CPQ.
As part of this integration, simple SKUs are sent to the fulfillment system. Configurable
SKUs are not sent to the integration workflows. However, configurable SKUs are
available to the webhook and can map to Order Management Cloud attributes if
required. A separate integration exists for Oracle CPQ and Order Management Cloud.
8-14
Chapter 8
Order creation
Payment
Order pricing and payment authorization happen in Oracle Commerce. The payment
attributes are not mapped to any attribute in Order Management Cloud because the order
management system does not need the payment information for fulfillment. With account-
based (B2B) shopping, the order does have a purchase order number that is passed on to
the order management system.
Note: The scope of this integration is restricted to Order Management Cloud. Other Oracle
services can perform additional order processing. For example, Order Management Cloud
can integrate with Account Receivables post fulfillment; this functionality is outside the scope
of this integration.
Commerce currently expects the payment capture information to be updated by an external
system. This assumption holds true for this integration as well. The order payment is
authorized by Commerce via the payment gateways before the order is sent to Order
Management for fulfillment.
It is recommended that you verify that the order is ready to be shipped in Order Management
and capture the money against the authorization. This can be done by integrating with the
payment gateways and sending the updated status back to Commerce as captured/settled.
The payment group status would have to be updated once the transaction is captured in the
Commerce repository. This status unavailability hinders return processing against an order.
Order types
Orders in Commerce can be placed for consumer-based (B2C) and account-based (B2B)
shopping.
These orders, when triggered from Commerce, need to be fed to the order management
system. This integration handles both types of order and maps the attributes of Commerce
and Order Management Cloud accordingly.
Shipping methods
Commerce shipping methods are mapped to Oracle Order Management Cloud shipping
methods. The mappings are made using the Lookup service of Oracle Integration Cloud.
The shipping methods are sent to Order Management Cloud as part of order creation. If you
create a new shipping method in Commerce, map it to a shipping method in Order
Management Cloud. These mappings ensure that the orders created in Oracle Commerce
always use the shipping method chosen by the customer.
8-15
Chapter 8
Order Status
Shipping methods are creating in the Shipping Methods tab, which is described in
Work with accounts. For information about Order Management Cloud shipping
methods, refer to the Oracle Order Management Cloud documentation.
Mapping of attributes
The attribute mapping of Commerce and Order Management Cloud is done through
Oracle Integration Cloud. There could be some additional processing that is needed
on the attributes before pushing the order to Order Management Cloud.
This additional processing of attributes can be can be built into the integration layer
without a need to modify Commerce. You can build an XSLT which acts on top of the
Oracle Integration Cloud UI and provides additional flexibility. A sample XSLT is also
provided as part of the integration package. The XSLT can be uploaded into any
integration in Oracle Integration Cloud as soon as the integration has been
deactivated.
The location of the XSLT for order creation is ICSpackage9a47f2ae-5f90-4cf7-
a87f-cb612dda70d1.iar/icspackage/project/
ORDE_SYNC_FROM_COMM_TO_ORDE_MGMT_01.00.0000/resources/
processor_859/resourcegroup_755/
req_19fd482efc0a4728b838273aec72b649.xsl.
The following figure illustrates the order creation workflow from Commerce to Order
Management Cloud:
Order Status
The status of an order is updated in Commerce by Order Management Cloud. Order
Management Cloud provides notifications on the status changes of the order.
As part of this integration, the shipment group status is updated for the order as No
Pending Action as soon as the shipment is closed in Order Management. The tracking
details of the order are also updated in Commerce as and when they are available in
Order Management. The payment group status for the order is set to Authorized.
8-16
Chapter 8
Returns
The order in Commerce is set to Submitted for fulfillment. You should update the payment
group status details based on your integrations with payment gateways or using the
capabilities of products such as Oracle Fusion Payments.
Returns
The returns created in Commerce are passed to Order Management Cloud for fulfillment.
Note: All the prerequisites needed for submitting a return on Commerce are valid for this
integration.
As soon as a return is created by Commerce, a new endpoint is created for processing the
return and submitting the return order to Order Management Cloud. Because the reason
code is mandatory when the return is created in Order Management Cloud, as part of the
return submission process, the disposition code of Commerce is mapped to Return with
Refund.
As soon as the return is processed by the Order Management Cloud, the disposition code is
updated with the correct value as sent by Order Management Cloud.
8-17
Chapter 8
Exchanges
Exchanges
This topic describes exchange processing for this integration.
• The exchange request is created along with a new order for the exchange.
• The exchange and the order are submitted to Order Management Cloud as part of
this integration.
• The exchange request is submitted to Order Management Cloud for receiving the
goods.
• When the status of the exchange is set to Received, the new order created as part
of the exchange is submitted to Order Management Cloud for fulfillment.
The flows for the return and the order creation are the same as described in the
previous sections. The order is submitted to Order Management only when the return
information is available in Commerce. The flows for the exchange are the same as
previously described.
8-18
9
Manage Page Tags
Oracle Commerce lets you create script tags and embed them in each page on a site.
Business users can create, manage, and place tags without the need for a developer to make
code changes to the storefront.
Page tags are HTML script tags that are embedded in every storefront page. They let you
add both Oracle and third-party plug-in services (such as analytics, chat services, or A/B
testing) to your storefront.
9-1
Chapter 9
Create and edit page tags
Delete a tag
Deleting a tag removes it from the system. To keep a tag but stop using it, simply edit
the tag and uncheck its Enable checkbox. To delete a tag, click its Delete icon and
then confirm that you want to delete the tag.
9-2
10
Integrate with Oracle Maxymiser
The Oracle Commerce and Oracle Maxymiser integration allows you to run Maxymiser
campaigns against any of your Commerce sites.
Oracle Maxymiser Campaigns support custom A/B testing, allowing you to create specific
campaign targeting and analysis. Maxymiser campaigns are grouped under Maxymiser sites.
Please note, Maxymiser sites are different than Commerce sites. You should create one
Maxymiser site to use when defining all of your Maxymiser campaigns for Commerce, even if
those campaigns are used on different Commerce sites.
Overview
A/B testing lets you experiment with the user experience on your site in a controlled way,
testing alternatives against each other to see which one produces the best results for your
business. This allows you to test and optimize aspects of your site to drive improvements in
key metrics.
To run a test, you generally create a control variant that presents your existing experience,
then define one or more new variants that present alternative experiences.
By allocating equal groups of shoppers between all of the different variants, you can measure
key outcomes for each group of shoppers to see how the different experiences affect shopper
behavior. Once you have determined the "winning" experience you can modify your storefront
accordingly.
Once you have set up and built your Commerce environment to integrate with Maxymiser,
you can:
• Create a Maxymiser campaign that contains variants and actions.
• Define the user experience for each group of shoppers that participate in the campaign.
To do this, you use Commerce Maxymiser Campaign Variation Slots with your Maxymiser
server-side campaigns. For information on performing this task, refer to Create
Maxymiser Campaign Variants in Commerce.
• Send behavioral data to Maxymiser where you can compare the behavior of each group
of shoppers. This allows you to track the following data:
– Commerce Page View data filtered by URL, product or collection IDs, or by matching
on default and custom Commerce product or collection properties.
– Shopper registrations.
– Orders that have been submitted. Maxymiser tracks both the number of orders, as
well as the number of units sold, allowing you to compare conversion rates, revenue,
and average order value for each group of shoppers.
• Once you have determined that your Maxymiser campaign is over you can refer to the
Maxymiser Performance Report and determine which Maxymiser variant performed the
best.
Enabling the Maxymiser integration with Commerce allows you to determine how to optimize
shopping experience for your customers. Maxymiser offers feature beyond A/B testing,
including site personalization for non-Commerce sites. When using Commerce you should
10-1
Chapter 10
use the built-in audience-based personalization features rather than using Maxymiser
for personalization. The built-in personalization in Commerce is more deeply
integrated into your commerce storefront and offers features not available in
Maxymiser. To personalize your site, use Commerce Audiences, as described in
Define Audiences.
10-2
Chapter 10
Create a Maxymiser Site
7. Define the experience you want to present to shoppers in each variant of the campaign.
Use the Campaign Variation Slot in Design Studio to create the user experience for each
variant. Refer to Create Maxymiser Campaign Variants in Commerce for additional
information.
8. Use the Commerce Storefront Preview capability to preview the Maxymiser variants.
Refer to Preview your changes for additional information.
9. Publish your Campaign Variation Slots, custom content, and campaign mappings in
Commerce and publish your Maxymiser campaign in Maxymiser, as described in Publish
Your Changes in Both Commerce and Maxymiser.
10. Determine which variant performed the best and then finalize the changes to your site’s
UI by copying the best performing variant slot experience into your UI and then deleting
the slot. Refer to Work with Maxymiser Campaign Results for additional information.
10-3
Chapter 10
Create a Maxymiser Campaign
10-4
Chapter 10
Create a Maxymiser Campaign
When you set up shopper registration tracking in your Maxymiser campaign, Commerce
sends the Sign Up event to Maxymiser for any shoppers in the current campaign.
To add a shopper registration Sign Up action:
1. Use the Maxymiser administration interface to access a Maxymiser campaign.
2. In the Actions panel, select the plus sign (+) to add an action.
3. From the drop-down menu, select Track Sign Up.
4. Add a Description. You can also make this action the primary action.
5. Once you have added all the information, click Done to save your changes.
If you want to rename the Sign Up action, double click Sign Up under the Sign Up drop-
down. The name becomes editable.
When you set up Sales Amount tracking in your Maxymiser campaign, Commerce will send
the order monetary value to Maxymiser for all shoppers in the campaign for all orders that
match the currency specified in the action.
To track orders using a Sales Amount action:
1. Use the Maxymiser administration interface to access a Maxymiser campaign.
2. In the Actions panel, select the plus sign (+) to add an action.
3. From the drop-down menu, select Track Sales Amount.
4. Use the Currency drop-down to select a currency.
10-5
Chapter 10
Create a Maxymiser Campaign
Note that if you set a Sales Amount action to use Currency=None, Commerce will
only track order amounts that are in the site's default currency. If you set a Sales
Amount action to use a specific currency, Commerce will only track order amounts that
are in that currency. If you have a campaign with a Sales Amount action with
Currency=None, do not use this campaign on multiple sites with different default site
currencies. If you do, the order amounts in multiple currencies will be combined
incorrectly without any kind of conversion. Order Quantity Actions will always be
tracked regardless of the currency.
After you have associated the currency with this action, do not change the currency
once the Maxymiser campaign has gone live.
10-6
Chapter 10
Create Maxymiser Campaign Variants in Commerce
If you want to rename the Sales Amount action, double click the name of the action under the
Sales Amount drop-down. The name becomes editable.
Work with Sales Quantities
When you select a Sales Quantity action, Maxymiser captures the total number of units sold
across all line items within the order.
10-7
Chapter 10
Create Maxymiser Campaign Variants in Commerce
After configuring the Maxymiser Campaign Variation Slot, you must create the slot
experiences and target them to the Maxymiser campaign variants. To do this, add new
experiences and then click on the targeting icon. Select the Variant Audience picker
and select the variants for each experience. Once you have provided the slot
information, your layout will contain a Maxymiser Campaign Variation Slot:
The following shows an experience targeted to the Maxymiser campaign variant that
identifies the Right Side variant we defined in Maxymiser:
Your default experience should contain your standard UI, and each additional
experience should contain modified versions of that UI.
10-8
Chapter 10
Preview Your Changes in Commerce
10-9
Chapter 10
Capture Reporting Metrics
10-10
Chapter 10
Publish Your Changes in Both Commerce and Maxymiser
You can identify collection pages for tracking using your own custom category properties or
the following supported property values:
• Name
• Collection ID
• Ancestor Collections
• Description
• Parent Collections
To track page views by Product or Collection page conditions, do the following:
1. Select Product Page Conditions or Collection Page Conditions from the View Page
drop-down.
2. For Product Page Conditions, optionally select the Product Type if using subtype
properties.
3. Click Add condition and select the appropriate property for either your product page or
your collection page.
4. Add the qualifier, which can be equals, is not equal to, starts with, ends
with, contains, exists and does not exist.
5. Enter the value to match in that property.
For example, you could create a Product Page Condition that occurs whenever a shopper
views a product that is your own house brand in a campaign that promotes sales of your
house brands.
Or you could create a Collection Page Condition that occurs whenever a shopper accesses a
collection whose name contains the string “movie”.
10-11
Chapter 10
Work with Maxymiser Campaign Results
When you publish a campaign in Maxymiser and any related changes in Commerce,
you need to ensure that you publish in both Commerce and Maxymiser. Note that after
publishing some of the changes may not be available on the Storefront for 15 minutes.
Any time you modify a layout, slot or campaign mapping in Commerce, you should
ensure that you publish your changes. Whenever you set up Commerce to use a
Maxymiser campaign, the Maxymiser campaign and variant objects may appear in
your publishing queue and will need to be published. Conversely, changes that you
make in Maxymiser should be published in Maxymiser. It is a best practice to publish
in both Commerce and Maxymiser when you make changes to your configurations,
campaigns or layouts.
If you are seeing the expected behavior when working on your storefront, access the
Campaign Editor in the administration interface and see if there is an unpublished
changes message displayed. If you find this message, publish the necessary changes
on Maxymiser and return to the storefront.
If shoppers do not appear to be added to campaign variants, verify that the Campaign
Generation Confirmation site setting in Maxymiser is disabled.
For detailed information on publishing a Maxymiser campaign in Maxymiser, refer to
Publishing a campaign. For detailed information on publishing in Commerce, refer to
Understand publishing.
10-12
11
Integrate with Oracle Product Hub Cloud
Oracle Commerce provides an integration with Oracle Product Hub Cloud (PHC) that you can
use to provide a robust commerce architecture for order capture and product management.
Oracle Cloud Product Hub, part of Oracle Cloud PLM suite, is an enterprise-class product
master data management (PMDM) software, delivered via cloud for lower cost and faster
deployment.
Audience
This section is written for Commerce and Product Hub administrators who want to set up and
configure the integration between these two systems. To use this documentation, you should
have experience with Commerce, Oracle Integration Cloud (OIC), and Product Hub. This
section does not provide any instructions for configuring any other aspects of these systems
beyond those required for the integration. For information on other configurations, refer to
each product’s documentation, available on the Oracle Help Center.
Overview
This integration provides the following features:
• Syncs products created in Product Hub to Commerce
• Associate collections created in Commerce to the products
• Optionally trigger a publish event in Commerce when import is complete
• Upload images from Product Hub to Commerce and associate them with products
Sync products and SKUs: This integration assumes that products and SKUs are created
and maintained in Product Hub. The integration syncs them to Commerce and make them
available on the storefront, as described by the following process:
• The item publication job can be scheduled in Product Hub with a required frequency, for
example once per day or once every six hours. It exports new and updated items based
on the defined filter criteria. The job runs as specified by the schedule, and on
completion, it posts the exported files to Oracle Universal Content Management (UCM)
and triggers the item-publication job event.
11-1
Chapter 11
Understand the Product Hub integration
• The item publication job event triggers the OIC flow. It checks if a publish event is
currently running in Commerce. If Commerce is publishing or if another import or
export job is active, then it cannot accept new requests for import. In these cases,
the integration execution stops and is moved to a queue to be retried at a later
time. When publishing completes, the integration is resumed from the queue.
• The integration downloads the exported file from UCM. The archive file may
contain multiple XML files, which are transformed into Commerce JSON format.
The integration archives the JSON files and uploads them to Commerce. It then
triggers the bulk product import process to load the data into the Commerce Admin
server.
Publish imported items: After the import is successful, the integration flow checks if
auto-publish is enabled in the OIC lookup. If enabled, it gets the total number of
records pending publishing in Commerce for the user/application configured in the OIC
Commerce connection. If it finds any such record and the number of such records is
less than the threshold configured in OIC lookup, it publishes those records. Note that
the publish operation includes all the records for the user, not only the ones imported
as part of the current integration flow. If the threshold exceeds 10 MB, it sends an
email notification to the administrator to inform that publish was not initiated
automatically. A Commerce admin user can manually start a publish in this case.
Upload images: If Media Sync is enabled (that is, if CXCommerceMediaSyncEnabled is
set to true in OIC lookups), then media items are also synced along with the items/
products from Product Hub to Commerce. Supporting formats for images to be linked
with products in Commerce are JPG, JPEG, PNG, and GIF. Separate ZIP file will be
created with all the images of supported formats and then uploaded to Commerce. For
more information about the rules Commerce enforces for images, see Manage Media
for Your Store in Using Oracle Commerce.
Prerequisites
Configuring and using this integration requires the following. If you require one or more
of these, please contact an Oracle sales representative.
• A Commerce account and access to Commerce 20D or later.
• An Oracle Fusion Product Hub account and access to Product Hub Cloud 20B or
later.
• An Oracle Integration Cloud account and access to Oracle Integration Cloud
Service.
Assumptions
This integration makes the following functional assumptions. These assumptions
require a functional understanding of both Commerce and Product Hub.
• Catalogs, collections, and product types are created in Commerce before the
products are imported into Commerce by the integration.
• Products and SKUs data is always managed in Oracle Product Hub and is
imported into Commerce. This means that Product Hub is the only source of
products and SKUs for Commerce.
• By default, Commerce list prices are mapped to Product Hub's purchase list
prices. It's recommended to create an Extensible Flexfield (EFF) attribute for sale
list price and override the mapping.
• All changes are published on Commerce, once the products are imported.
11-2
Chapter 11
Configure Oracle Commerce with Oracle Product Hub
• Configurable SKUs, add-on products, related SKUs, services and subscriptions are not
supported by default in this integration. You will need to extend the integration if you wish
to support these components.
• PDH Item Number is mapped to Commerce Product ID and SKU ID. While Item Number
can include spaces and have a maximum length of 256 characters, Commerce IDs do
not support spaces and can have a maximum length of 165 characters. Therefore,
appropriate rules must be set in PDH to conform data to Commerce requirements. Also,
the Item Number must not be modified in PDH.
• Translations to secondary locales are not supported by default in this integration. If your
Commerce environment requires translations, this requires multiple exports to be
triggered in PDH in different locales, and any extension to this integration must handle
them accordingly in the integration flow.
• You can customize this integration to link Images to SKUs and to map an image’s path
and name under SKUs. Before you can do this, make sure that the productType is
mapped to a Commerce product type for which Allow product images at the variant
property value level is enabled in the Variant properties.
You must configure the Publish Complete and Import Complete webhooks.. Follow these
steps to configure the webhooks in the Commerce administration interface:
11-3
Chapter 11
Configure Oracle Product Hub
Attribute mappings
The following table shows the relationships between Product Hub product Item
properties and Commerce product properties.
The following table shows the relationships between Product Hub product Item
properties and Commerce SKU properties.
11-4
Chapter 11
Install and Configure the Integration in OIC
• Configure the item-publication criteria, select entities Attributes and Item Category
Assignments. You can select a date filter in criteria to filter out items, for example, items
updated within the past day, if the publication job is scheduled for a daily frequency.
• Configure the size of exported zip file. Remember that OIC will not accept ZIP files larger
than 1GB.
The exported zip files contains ITEM_*.xml files. Configure the size of XML by providing
an optimal number of records an XML file can have, so that the size of the XML doesn't
exceed 10 MB. This is to match OIC restrictions in place for performance considerations.
• Create a schedule for the publication job.
11-5
Chapter 11
Install and Configure the Integration in OIC
• Under Security Policy, select Username Password Token and enter the
login credentials to access the endpoint.
6. Select Oracle UCM Connection, The Connection Properties dialog appears.
• Enter the WSDL URL. For example: https://{productHub-server}/
idcws/GenericSoapPort?wsdl
• Under Security Policy, select Basic Authentication and enter the login
credentials to access the endpoint.
11-6
Chapter 11
Install and Configure the Integration in OIC
5. The mapper should show the new fields for Commerce product and SKU.
Configure lookups
You must update the lookup values in the lookup table Oracle-PDH_Comm_Int_Settings:
• PDHSpokeSystem : Spoke system created in Product Hub for performing item-publication
job. The integration will process the exported file for this spoke system.
• PDHCatalogsForCategory-ProductsLinks : Comma-separated list of catalogs. Configure
if the product in Commerce will be associated with specific collections and catalogs. If
this is not provided, the integration flow will link the product to all the collections specified
by the exported data received from Product Hub. If no collection or catalog associations
are required then configure this variable as NULL.
• ToEmailAddresses: Recipient email addresses to send error notifications. If an import
fails in Commerce, an email message containing a link to failed records is sent to this ID.
• FromEmailAddress: Sender email address for the error notifications.
• OICMaximumRetryCount: Maximum number of retry counts for resubmitting failed
instances. There are a number of reasons for integration instance failure, for example,
when publishing is running in Commerce, or if there is a network failure.
• CXCommerceAutoPublishEnabled – Set this to true if all the records imported to
Commerce through specific registered App ID (CXCommerceRegisteredAppId) needs to be
published automatically; otherwise, configure this variable as false.
• CXCommerceRegisteredAppId - Registered Commerce Application ID of the user for which
the all the data in the publishing queue will be published, if automatic publishing
(CXCommerceAutoPublishEnabled) is enabled.
• CXCommerceAutoPublishThreshold - Maximum number of records for which automatic
publishing will be triggered. Otherwise, the integration will send email to the administrator
so they can manually publish.
• CXCommerceMediaSyncEnabled – Set this to true if media items from Product Hub need to
be synced with Commerce; otherwise set to false.
The following example shows sample lookup values in the lookup table Oracle-
PDH_Comm_Int_Settings:
FromEmailAddress - [email protected]
PDHCatalogsForCategory-ProductsLinks – NULL
PDHSpokeSystem – CXCommerce
OICMaximumRetryCount – 5
CXCommerceRegisteredAppId – EnterYourRegisteredAppId
CXCommerceAutoPublishEnabled – false
CXCommerceAutoPublishThreshold – 1000000
CXCommerceMediaSyncEnabled - true
11-7
Chapter 11
Understand the integration flows
To learn how to customize and send email with OIC, see the following Oracle blog
posts:
• An Advanced Guide to OIC Notification via Emails
• How to send email with attachments in OIC
11-8
Chapter 11
Understand the integration flows
Listens for the Commerce Publish Complete webhook‘s POST request and re submits
the failed integrations run of Oracle PRODUCT HUB COMMERCE ItemToProductSync which
fails because of publishing is running in Commerce.
• Oracle OIC OICREST RESUBMITERRORRUN
Fetches the failed integrations for the input integration name and resubmit the first entry
in the failed integration.
• Oracle SCHEDULE OIC Product HubInt Resubmit
The schedule integration, which resubmits the failed integrations run of failed Oracle
PRODUCT HUB COMMERCE ItemToProductSync. Failures may occur because there was a
processing error with the exported file in the integration or upload and import of the
products file to Commerce was not successful.
The following diagram shows an overview of the integration flows:
11-9
Chapter 11
Understand the integration flows
11-10
12
Integrate with Oracle Responsys
Integrating Oracle Responsys and Oracle Commerce.
When you integrate Commerce and Oracle Responsys you create a unified solution for your
customers as well as the ability to communicate with those customers in a relevant and
structured dialogue based on their commerce activity.
Objective
The integration of Oracle Commerce and Oracle Responsys targets support for the following
customer commerce activity:
• Welcome: Communicate with newly registered customers to enhance their relationship
with the merchant.
• Win Back: Communicate with customers who have not created any new orders in a
significant period of time. The message to the customer can be tailored to include a
Commerce promotion to encourage them to return to the website.
• Milestone: Using Commerce profile data, communicate with customers based on
personal milestones such as their birthday or the anniversary of their registration date.
• Abandoned Cart: Communicate with customers who added items to their shopping cart
and then left the website without purchasing the items they placed in the cart. The
message to the customer can be tailored to include aCommerce promotion to encourage
them to return to the website.
This document provides instructions on how to set up an integration between Commerce and
Responsys so that Commerce information is automatically passed to Responsys ensuring
12-1
Chapter 12
Configuring the Integration
that the supported marketing campaigns are always based on current shopper activity.
This document provides instructions on the following topics:
• How to download the Oracle Integration Cloud Integration Flows.
• How to configure and set up the Oracle Integration Cloud Integration Flows.
• How to setup the connection to Responsys.
• How to set up the required data tables in Responsys.
• How to setup the connection to Oracle Commerce.
• How to configure the webhooks to trigger the integration flows.
• How to use the abandoned cart functionality supported by the integration.
Audience
This document is written for Oracle Commerce and Oracle Responsys administrators
who need to set up and configure the integration between these two systems.
Readers of this document should have experience with Commerce, Responsys, and
Oracle Integration Cloud administration.
Prerequisites
For the purposes of this document, it is assumed that you already have:
• An Oracle Commerce account and access to Oracle Commerce 16.6 or later.
• An Oracle Responsys account and access to Oracle Responsys 6.31 or later.
• An Oracle Integration Cloud account and access to Oracle Integration Cloud
Service 16.4.5 or later.
If you do not have one or more of these, please contact an Oracle sales representative
for information on how to acquire one: http://www.oracle.com/us/corporate/contact/
index.html.
12-2
Chapter 12
Configuring the Integration
12-3
Chapter 12
Configuring the Integration
Note: This is not the URL you use to connect to Responsys. You can get the URL
required here from your Responsys administrator.
6. Click OK.
7. Click on the Configure Security button.
8. Select Custom Security Policy in the Security policy list.
9. Complete the Username, Password, and Confirm Password fields. These are
the credentials required to access your Responsys account.
10. Click OK.
12-4
Chapter 12
Configuring the Integration
CC_Master_User_List Table
The following is a list of fields that must be included in a table called CC_Master_User_List
created in a folder called /CC in Responsys. The first list is the system fields for the table,
and the second list is the custom fields for the table.
12-5
Chapter 12
Configuring the Integration
CC_Submit_Order Table
The following is a list of fields that must be included in a list extension table called
CC_Submit_Order created in a folder called CC in Responsys.
12-6
Chapter 12
Configuring the Integration
12-7
Chapter 12
Configuring the Integration
4. You can choose here whether to switch on detailed tracing. Detailed tracing
collects information about messages processed by the integration flow. This may
assist in troubleshooting issues with the integration flow, but it may impact
performance.
To switch on detailed tracing, check the Enable detailed tracing checkbox.
Note: Once an integration flow is active you must deactivate it and activate it again
to switch detailed tracing on or off.
5. Click Activate.
A message should be displayed to indicate that the integration flow has been
successfully activated.
12-8
Chapter 12
Using the integration
If you are configuring the Order Submit webhook then you should display information for
the OCCS-OMC Integration Order integration.
If you are configuring the Cart Idle webhook then you should display information for the
OCCS-OMC Idle Cart integration.
4. Copy the Endpoint URL for the integration.
5. Log on to Oracle Commerce.
6. Click on the Settings icon.
7. Select Web APIs from the sidebar menu.
8. Click on the webhook you wish to configure.
9. Paste the Endpoint URL you copied into the URL field for the webhook.
10. Remove the “metadata” text from the end of the URL.
11. Enter the Username and Password for your Oracle Integration Cloud account.
The webhook is now configured and is triggered each time the relevant event occurs, which
in turn triggers the relevant integration flow.
For more information on Commerce webhooks, please refer to the Configure Webhooks
chapter of the Using Oracle Commerce document.
12-9
Chapter 12
Using the integration
The abandon custom event must listen to a specific event name that is passed by
Commerce in the API call that triggers this program. You must select
CC_Abandoned_Cart from the Listen for custom event type dropdown menu.
Commerce passes a set of dynamic variables to the program through the API call.
These dynamic variables must be specified for the program using the Settings
configuration options.
12-10
Chapter 12
Using the integration
You must then associate a specific email campaign with the Send email campaign activity.
You should use the Email Message Designer to specify the personalization rules used by the
email campaign associated with the email widget. You can do this using Responsys
Personalization Language (RPL).
The following figure shows a sample HTML code using RPL to personalize the email
message based on the dynamic variables passed by Commerce to the abandoned cart
program.
Note: This sample code is provided for guidance only and should not be directly copied as it
will not work with your integration.
12-11
Chapter 12
Using the integration
When you create the email using RPL you can see a preview of the email message
rendered with some default personalization values.
For more information on using the Email Message Designer functionality, please refer
to your Oracle Responsys documentation.
12-12
13
Integrate with Oracle Retail Order
Management System
Integrate Oracle Retail Order Management System with Oracle Commerce.
Oracle Order Management Cloud is integrated with the Oracle Global Order Promising Cloud.
Together with Commerce they allow you to provide fulfillment monitoring and global
availability for your customers.
Introduction
Oracle Retail Order Management System Cloud Service (OROMS) is an order management
system that supports retail transactions, including fulfillment, warehousing/inventory control,
customer service, merchandising, marketing and finance.
Commerce and Oracle Retail Order Management can be used together to provide a robust
commerce architecture.
Audience
This document is written for Commerce and Oracle Retail Order Management administrators
who need to set up and configure the integration between these two systems.
Readers of this document should have experience with both Commerce and Oracle Retail
Order Management administration. This document does not provide instructions on
configuring aspects other than integration for Commerce and Oracle Retail Order
Management. For that information, refer to the product documentation.
Features
The integration between Commerceand Oracle Retail Order Management provides a solution
that combines the capabilities of these two products.
This integration provides the following features:
• Turning integration on and off using the Commerce administration interface
• Providing configuration based on your environment
• Pushing completed Commerce orders to Oracle Retail Order Management for fulfillment
• Retrieving and displaying Oracle Retail Order Management order status in Commerce
This integration provides retailers with an opportunity to manage order and fulfillment
information.
Architectural Overview
Shoppers use the Commerce storefront to place an order.
13-1
Chapter 13
Prerequisites
When a retailer enables integration, the order created in the storefront is sent to
Oracle Retail Order Management where it is fulfilled. Commerce can obtain the details
of the order from Oracle Retail Order Management and display the status in the
customer storefront or the Agent Console of Commerce.
Commerce manages the promotions and discounts for the order and passes the final
price of the order to Oracle Retail Order Management. The shipping methods in both
systems are synchronized, ensuring that the customer is choosing from shipping
methods that are available from Oracle Retail Order Management.
To perform data synchronization, Commerce communicates with Oracle Retail Order
Management using REST. Commerce provides data output in JSON, while Oracle
Retail Order Management exposes REST services that accept XML. Integration
services take the JSON data from Commerce, convert it to XML using XSLT
transformers, and send it to all Oracle Retail Order Management systems. In turn,
XML data sent from Oracle Retail Order Management is read by the integration
service and converted to JSON. The webhook target that communicates with Oracle
Retail Order Management is set using the administration interface. If the integration is
disabled, the transformation logic is skipped and the webhook behaves as a standard
webhook.
Webhooks submit JSON, however, Serenade accepts only XML. When an order is
submit, it is converted from JSON to XML. Webhooks support multiple target orders,
and if the target contains
Integration services are configured using the Commerce administration interface.
When an order or order detail is queried in Commerce, a service call is made to Oracle
Retail Order Management to get the latest status for that order. Orders that are
created in Commerce are synchronized to Oracle Retail Order Management, and
order status updates regarding fulfillment from Oracle Retail Order Management are
requested by Commerce on demand.
Additional Documentation
For additional information on Commerce:
For additional information on using Commerce, see the Oracle Commerce
documentation.
Prerequisites
This section contains information on prerequisites needed before configuring the
integration.
Before you begin the integration process, you must ensure that you have met the
following conditions.
Access Rights
To configure integration, you need to have administrator access to Commerce.
This allows you to configure the integration settings using the administration interface.
13-2
Chapter 13
Prerequisites
Data Configuration
The product and SKU information should be in sync on both the Commerce and Oracle Retail
Order Management servers.
The following describes the Item and SKU fields and the mapping between them:
Item Configuration
Oracle Retail Order Management allows the ITEM_ID field to contain a maximum of 12
alphanumeric characters. Therefore, items created with Commerce should contain no more
than 12 alphanumeric characters, for example, Item001, wallet, etc.
SKU ID Configuration
The Oracle Retail Order Management system generated short_sku_number number is
unique for a company as well as a site. As such, the Commerce SKU ID should also have a
unique ID for the site. Note that the SKU ID must be numeric and limited to 7 characters.
Variant Configuration
Oracle Retail Order Management allows a maximum of three SKU attributes, for example,
color, size and collar. Note that all items will have the same elements. For example, both
the shirts and the shoe SKUs will contain the same variants, for example, color, size, and
collar.
Commerce allows more than three variants, for example, color, size, collar, and sleeve.
However, Oracle Retail Order Management cannot recognize more than three variants. If the
SKU attribute in Oracle Retail Order Management and the SKU variant in Commerce both
contain fewer than three entries, the SKU attribute will be the same.
While creating items and SKUs in Commerce and Oracle Retail Order Management, consider
the following:
• When creating SKUs, limit variants to less than three
• Create SKUS in Oracle Retail Order Management. The same SKUs with the
short_sku_number field can be manually exported and created in Commerce
• Create variants that are as general as possible so that they can be shared across items
• Before the integration process begins, the Commerce and Oracle Retail Order
Management inventories should be synchronized
For detailed information on configuring and managing catalogs and SKUs, refer to the Oracle
Commerce documentation.
Working with More Than Three Variants
Commerce allows you to configure SKUs so that they contain variants, such as color, size,
collar, etc. However, Oracle Retail Order Management can accept only up to three of these
variants. In the following example, the SKU for a shirt, as it is defined in Commerce, contains
the variants for color, size, sleeve and collar. Because Oracle Retail Order Management
can only accept three of these variants to be part of the SKU, the SKU is could be modified.
Note: If a Commerce SKU contains three or less variants, it is converted into the Oracle
Retail Order Management system without any changes.
13-3
Chapter 13
Setting Up the Integration
In the following example, the Commerce Shirt 1234 item contains the following
variants: color, size, collar, and sleeve. A SKU with the sku_id 1234567 is a
Shirt1234 item that has the variants values of black, small, crew, half.
Because the Commerce SKU has more variants than Oracle Retail Order
Management can accept, you might configure your SKU so that the last variant,
sleeve, is removed, creating three separate items: Shirt1234 Full, Shirt 1234 Half and
Shirt 1234 3/4. The Commerce SKU now matches the Oracle Retail Order
Management Shirt1234 Half item. The SKU with the Commerce sku_id 1234567
receives the system-generated short_sku_number 1234567.
The above diagram shows how the Commerce item Shirt 1234 can be converted into
three separate Oracle Retail Order Management items based on the fourth variant,
sleeve. The diagram also shows how the Commerce SKU Shirt1234 relates to the
Oracle Retail Order Management SKU 1234567.
13-4
Chapter 13
Setting Up the Integration
Commerce Configuration
Before you set up the Oracle Retail Order Management integration with Oracle Commerce
ensure that the necessary integration software is running on your server.
Configuring Webhooks
As described in the Architectural Overview section, the integration service is based on the
Web API settings in Commerce.
Web APIs allow you to subscribe to events for your products and orders by creating
webhooks that push JSON notifications to a URL you specify. For additional information on
webhooks, refer to Use Webhooks.
Before you can configure the integration settings, the webhook must be configured. To do
this, ensure that the Order Submit Event API has been configured with the URL necessary to
connect to the Oracle Retail Order Management server.
To Configure the Order Submit Event API
1. From the Commerce administration interface, select the Settings menu.
2. Open the Web API page and select the Webhook tab.
3. Open the Order Submit Event API.
4. Provide the URL of the server that will be accepting the order, including the server name
and port used for the CWOrderIn service. For example:
https://my.example.com:8443/SerenadeSeam/sxrs/SerenadeREST/CWOrderIn
5. Provide a user name and password for accessing the server.
6. If you are using HMAC authentication, you can view or reset the key.
7. Click Save to save your changes.
Production Configuration
The Production Configuration section configures a number of details as well as the mappings
for payment types and shipping methods. These values are passed to Oracle Retail Order
Management allowing the orders to be identified.
Note: These settings are duplicated in the other Oracle Retail Order Management Integration
setting, Preview Configuration.
13-5
Chapter 13
Setting Up the Integration
The following properties are set in the fields provided by the Production Configuration
page. Note that all fields are required unless otherwise noted.
Field Description
XSLT Path Name of the custom XSLT file to load.
Source Identifies the source of the XML message. The
source should default to IDC.
Target Identifies the target of the XML message. The
target should default to RDC.
If multiple webhooks are specified in the Target
field, all of the systems receive the same data.
Transformation for specific URLs can be
performed by adding the URLs to both the
webhook and integration settings.
Company Code Identifies the company for the order. The
company code is validated against the
Company table.
Source Code Updates the source code field in the Order
Header table. The source code provides
information about the currency code. You must
provide the Commerce currency code to the
Oracle Retail Order Management System
source code mapping using the Currency
Code mapping table.
Order Type Updates the order type field in the Order
Header table.
URL The URL path to the Oracle Retail Order
Management Web Service CWMessageIn. For
example:
https://my.example.com:8443/
SerenadeSeam/sxrs/SerenadeREST/
CWMessageIn
Note: Use the same hostname and port
number that you provided for the Order Submit
URL on the Web APIs Webhook page.
User Name The name of the user who should have access
to the Web Service.
Password The password associated with the user name.
To see the password, click the Reveal button to
display the password.
In an environment with multiple sites, you could configure the settings like this:
13-6
Chapter 13
Setting Up the Integration
Select the site with the site picker and select the appropriate Oracle Retail Order
Management source code. Each source code points to a single offer record, which contains
the currency code. This is how the offer record can provide the currency representation for an
order.
Using XSLT
You can use the customized XSLT capability to extend the default integration. The system
contains an internal XSLT file that maps all attributes. The merchant does not have access to
this XSLT file; however, you can provide a path to the XSLT. The XSLT should contain the
logic that customizes the Oracle Retail Order Management createOrder payload so that it
includes dynamic properties or makes mapping changes.
This XSLT workflow is active only when the Oracle Retail Order Management integration is
enabled. The merchant must upload the XSLT using Oracle Commerce’s file upload
endpoints. If no customized XSLT file is uploaded, the system uses the default XSLT file to
pass orders, ignoring any custom attributes.
When creating a custom XSLT file:
• The default mapping can be overridden and mapped to other attributes as necessary.
• The merchant can use dynamic attributes created with Oracle Commerce to map
attributes of the Oracle Retail Order Management.
• Because mapping is configured in the customized XSLT file, the merchant can map
custom attributes that were created for an Order header level in Commerce to an order
header or order line status in Oracle Retail Order Management.
To use a customized XSLT file, do the following:
1. Create a new XSLT file mapping.
2. Upload the XSLT file to Commerce using the file endpoints.
3. Use the Oracle Retail Order Management Integration Settings to provide the name of the
uploaded XSLT.
The following illustration defines the way that the merchant’s transformation is applied when
the XSLT path is provided.
13-7
Chapter 13
Setting Up the Integration
XSLT Example
The following is an example of an XSLT file:
13-8
Chapter 13
Setting Up the Integration
</Payments>
<ShipTos>
<xsl:for-each select="request/Message/Header/ShipTos/ShipTo">
<ShipTo>
<xsl:copy-of select="@*" />
<Items>
<xsl:for-each select="Items/Item">
<Item>
<xsl:copy-of select="@*" />
<!-- **************************************************
Updating an existing mapping
******************************************************** -->
<!-- To change the mapping of an existing OROMS attribute, comment the line
(<xsl:copy-of select="@*" />) and uncomment below line and replace
<oroms_attribute> with the attribute name required in output and
<occ_attribute>
with attribute name in occ XML map an attribute in oroms XML to a different
value,
comment the above line and uncomment below line and replace
<oroms_attribute> with
the attribute name required in output and the <occ_attribute> with attribute
name
in occ XML -->
<!-- *********************************************************
Mapping a dynamic attribute of OCC to a new attribute in OROMS
*********************************************************** -->
<!-- To add a new attribute "category" at item level in oroms XML, which
reads the
data from the dynamic attribute shopperCategory. Replace <occ_attribute>
with the
dynamic attribute name in occ. -->
<!-- *******************************************************
Mapping a dynamic attribute of OCC with comma separated item level
data to a new attribute in OROMS
************************************************************** -->
<!-- To map a dynamic attribute in occ in format skuId1-value1,skuId2-value2.
Replace <occ_attribute> with the dynamic attribute name in occ and
<oroms_attribute> with oroms attribute name. -->
<xsl:for-each select="str:tokenize($vOrder/<occ_attribute>,',')">
<xsl:variable name="temp" select="str:tokenize(.,'-')"/>
<xsl:if test="$temp[1]=$vOromsAttribute">
<xsl:attribute name="<oroms_attribute>"> <xsl:value-of select="$temp[2]" />
13-9
Chapter 13
Setting Up the Integration
</xsl:attribute>
</xsl:if>
</xsl:for-each> -->
<!--
*******************************************************************
Mapping a dynamic attribute of OCC in JSON with a new attribute in
OROMS
******************************************************************** --
>
<!-- To map a dynamic attribute in occ in json format (sample json
format is given
below ). Replace <occ_attribute> with the dynamic attribute name in
occ,
<oroms_attribute> with oroms attribute name and
<dynamicAttributeFieldName> with
specific field name in the dynamic attribute json -->
13-10
Chapter 13
Setting Up the Integration
</ShipTo>
</xsl:for-each>
</ShipTos>
</Header>
</Message>
</xsl:template>
<xsl:template name="readCustomProperty">
<xsl:param name="json" />
<xsl:param name="skuId" />
<xsl:param name="dynamicAttributeName" />
<xsl:call-template name="readCustomPropertyBySkuId">
<xsl:with-param name="fullSkuJson" select="$fullSkuJson" />
<xsl:with-param name="remainingJson" select="$remainingJson" />
<xsl:with-param name="skuId" select="$skuId" />
<xsl:with-param name="dynamicAttributeName" select=
"$dynamicAttributeName" />
</xsl:call-template>
</xsl:template>
<xsl:template name="readCustomPropertyBySkuId">
<xsl:param name="fullSkuJson" />
<xsl:param name="remainingJson" />
<xsl:param name="dynamicAttributeName" />
<xsl:param name="skuId" />
<xsl:variable name="temp" select="normalize-space
(substring-after($fullSkuJson,$skuIdWithQuots))" />
<xsl:variable name="skuIdValue" select="normalize-space
(substring-before($temp,'\'))" />
<xsl:if test='$remainingJson'>
<xsl:variable name="temp1" select="normalize-space
(substring-after($remainingJson,'{'))" />
<xsl:variable name="fullSkuJson1" select="normalize-space
(substring-before($temp1,'}'))" />
<xsl:variable name="remainingJson1" select="normalize-space
(substring-after($temp1,'}'))" />
<xsl:call-template name="readCustomPropertyBySkuId">
<xsl:with-param name="fullSkuJson" select="$fullSkuJson1" />
<xsl:with-param name="remainingJson" select="$remainingJson1" />
<xsl:with-param name="skuId" select="$skuId" />
<xsl:with-param name="dynamicAttributeName"
select="$dynamicAttributeName" />
13-11
Chapter 13
Setting Up the Integration
</xsl:call-template>
</xsl:if>
Order Creation
Orders created in Commerce are sent to Oracle Retail Order Management using the
Submit Order webhook.
Note that the Oracle Retail Order Management webhook overrides the Submit Order
Webhook to send XML messages that contain the entire XML payload. If the webhook
is configured to send to multiple destinations, all of the destinations will receive this
XML payload.
The following is an XML example of an order creation message received by Oracle
Retail Order Management.
Sample Order Creation Message
13-12
Chapter 13
Setting Up the Integration
cc_exp_month="03"
cc_exp_year="2018" auth_amount="75.88" auth_date="01011970"
ecommerce_indicator="Y" already_tokenized="Y"
transaction_id="1ni4eg211lj6iqt6097hopidv7" vendor_response="100"/>
</Payments>
<ShipTos>
<ShipTo shipping_method="01" freight_tax_override="Y"
freight_tax_amount="4.22" calc_frt="N" ship_to_fax_phone=""
ship_to_evening_phone="212-555-1977" ship_to_day_phone="212-555-1977"
[email protected] ship_to_zip="13202" ship_to_state="NY"
ship_to_country="US" ship_to_city="Syracuse" ship_to_address3=""
ship_to_address2="" ship_to_address1="21 Cedar Ave" ship_to_company=""
ship_to_suffix=""ship_to_lname="Anderson" ship_to_fname="Kim"
ship_to_prefix="" freight="50"contact_name="KimAnderson">
<Items>
<Item tax_override="Y" price_override="Y" short_sku_number="130"
item_id="LAPTOP" actual_price="6.67" tax_amount="1.11"
quantity="2"/>
<Item tax_override="Y" price_override="Y" short_sku_number="130"
item_id="LAPTOP" actual_price="6.66" tax_amount="0.55"
quantity="1"/>
</Items>
<ShipTo>
<ShipTos>
</Header>
</Message>
Payment Methods
Oracle Retail Order Management uses payment methods that are identified with unique
integers. For integration, Commerce Payment Methods are mapped to Oracle Retail Order
Management numeric payment methods.
You can obtain a list of the payment methods available by calling the following endpoint:
GET /ccadmin/v1/merchant/paymentGateways
13-13
Chapter 13
Setting Up the Integration
This returns a list of available payment methods. The response also includes the ID of
the merchant, whether the method has been enabled, and the repository ID of the
payment method. The repository ID identifies the payment method code to use. The
following example displays a partial response that identifies a CyberSource payment
method:
{
"paymentGateways": [
{
"sopCredentials": {
"storefront": {
"sopURL": "http://10.101.101.101:8080/ccstore/v1/PM/
cybersourceSOP",
"expirationDate": "2019-01-28T11:54:30.207Z",
"profileId": "Admin",
"applicationName": "storefront",
"hasSecretKey": true,
"hasAccessKey": true,
"repositoryId": "SOP-A"
},
In an environment with multiple sites, you need to pass the siteId value in header to
get payment gateway details for the site. To fetch payment gateways specific to a site,
you need to pass x-ccsite header. For example, to fetch payment gateways for
siteUS site, the header should include x-ccsite: siteUS.
You can find information about individual endpoints in the REST API documentation
that is available through the Oracle Help Center.
Note that this documentation reflects the most recent version of Commerce. If you are
currently using an earlier version of Commerce, the API documentation on the Oracle
Help Center may include endpoints that are not available on your version.
Once you have obtained the repository ID, use it to map the payment method as
follows:
As orders are created in Commerce and passed to Oracle Retail Order Management,
the payment mappings are passed to Oracle Retail Order Management for fulfillment
and settlement with the required payment gateways.
Note: To ensure PCI compliance, no credit card or gift card numbers are sent to
Oracle Retail Order Management. The transaction reference and the authorization ID
are sent with the order.
Payment Gateways
13-14
Chapter 13
Setting Up the Integration
Commerce has preconfigured integrations with Chase and CyberSource payment gateways.
By default, the CyberSource payment gateway is selected for the integration. The Oracle
Retail Order Management System requires a credit card to be provided when using the
Chase gateway, however, Commerce does not store credit cards and cannot provide them.
As such, Chase credit cards are not supported with this integration. Oracle Retail Order
Management supports CyberSource and PayPal gateways by default.
Note: When using the CyberSource payment gateway, you must provide the AuthNumber for
reauthorization and settlement. Because Commerce does not store the AuthNumber, the field
is set to NA by default. You must update this field with the AuthNumber values for the
CyberSource gateway.
To configure integrations with other order processing systems, use the Generic Payment
Framework, as described in the Oracle Commerce documentation. Generic payment is not
supported by default; however, Oracle Retail Order Management APIs can support sending
payment details separately for an order. Whenever a generic payment is used in Commerce,
payment details are not sent and the order is put into an error state. Once you update the
payment details for the order, the Oracle Retail Order Management System changes the
order to an open state.
External Pricing
Note that this integration does not support external pricing. If you are using a combination of
external prices and sale prices from Commerce, this integration will average the prices of
items of the same SKU. For example, a customer qualifies for a promotion in Commerce that
enables him to purchase 5 hats for the sales price of $5 each, instead of the list price of $6. If
the customer wants to buy 10 hats, in Commerce, 5 of the hats would be sold at $5 and 5 of
the hats would be sold at $6 for a total of $55. Oracle Retail Order Management does not
differentiate between the price lists. Instead, it averages the final price between all of the
hats, therefore all 10 hats are priced at $5.50 each for a total of $55. This may impact return
processes, as in the above example, the return price of a hat would be $5.50 and not $5
or $6.
Payment Types
Payment Types are set up and configured using the Payment Processing setting and the
Payment Types tab, which is described in the Oracle Commerce documentation. For
information on Oracle Retail Order Management payment types, refer to the Oracle Retail
Order Management documentation.
Shipping Methods
Oracle Retail Order Management uses shipping methods that are identified by unique
integers. You can configure multiple shipping methods. For integration, Commerce shipping
methods are mapped to Oracle Retail Order Management numeric shipping methods.
The shipping methods are sent to Oracle Retail Order Management during fulfillment.
Commerce and Oracle Retail Order Management shipping methods should be synchronized.
These mapping ensure that the orders created on Commerce refer to and use similar
shipping method chosen by the customer for shipping.
You can obtain a list of the shipping methods available by calling the following endpoint:
GET /ccadmin/v1/merchant/shippingMethods
This returns a list of available shipping methods. The response also includes information on
each shipping method, and the repository ID of the shipping method. The repository ID
13-15
Chapter 13
Setting Up the Integration
identifies the shipping method code to use. The following example displays a partial
response that identifies a ground shipping method:
"enabled": true,
"displaySequence": 0,
"eligibleForProductWithSurcharges": false,
"ranges": [
{
"amount": 4.75,
"high": 14.99,
"low": 0,
"repositoryId": "groundRange1"
}
Once you have obtained the repository ID, use it to map the shipping method:
Shipping methods are set up and configured using the Shipping Methods setting,
which is described in the Oracle Commerce documentation. For information for
integrating with external shipping systems, refer to the Oracle Commerce
documentation. For information on Oracle Retail Order Management shipping
methods, refer to the Oracle Retail Order Management documentation.
External Shipping Methods
Commerce supports external shipping methods. However, these shipping methods
may not be available in the list of shipping methods displayed in the administration
interface when configuring your Oracle Retail Order Management integration. To use
the shipping methods for your external system you must add them to the Shipping
Methods mapping table.
Once all of the integration parameters have been configured and saved, the
integration process can occur.
13-16
14
Integrate with Oracle Subscription
Management
Integrating with Oracle Subscription Management allows shoppers on your Oracle Commerce
site to purchase and manage their subscriptions.
Subscriptions are an increasingly popular way that allows your shoppers to buy products and
services online. When you offer shopper subscriptions, you help strengthen customer
relationships and take advantage of a solution that supports complex products and services.
Prerequisites
The following software, account, and data prerequisites are required before you can install
and configure the subscription.
• An Oracle Commerce account and access to the Oracle Commerce 20.3.12 or later.
• An Oracle CPQ account and access to Oracle CPQ 20D or later. You must have already
configured the integration between Oracle CPQ and Commerce. See Configure the
integration for more information.
• An Oracle Subscription Management Cloud account and access to Subscription
Management Cloud 20C or later.
• Oracle Financials Account Receivables (AR)
• Oracle Customer Data Management (CDM)
• An Oracle Integration Cloud account and access to Oracle Integration Cloud Service.
• Oracle Product Master Data Management
• The Oracle CX Commerce to CPQ Get Assets integration - version 7. (Downloadable as
OCCS_CPQ_ASSET_INTEGRATION_7.0.par).
14-1
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
Assumptions
This integration makes the following functional assumptions:
• Profile and Account are in sync with Oracle Customer Data Management.
• Products are in sync between Oracle Product Hub, Oracle CPQ, and Oracle
Subscription Management Cloud.
• Only configurable products from CPQ are eligible for the integration and all
subscription-based products need to be configured in CPQ with recurring prices.
• Asset Based Ordering must be enabled in CPQ, so that Asset Keys get generated
as part of the configuration. These Keys are used to track the relationship between
configuration details in Commerce items, Subscription products and CPQ Assets.
For Commerce to store Asset Keys at Commerce item level, products in
Commerce Catalog must have their assetable property set to TRUE.
14-2
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
14-3
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
Entity mappings
This section shows the relationships between entities across different systems in the
integration. Not all entities are mapped to all systems in the integration.
B2B Account
• CDM: PartyNumber
Commerce:externalOrganizationId
14-4
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
• CDM: PartyId
Commerce: occ_partyId (custom)
B2B Contact
• CDM: PartyNumber
customerContactId
• CDM: PartyId
Commerce: occ_partyId (custom)
B2C Contact
• CDM: PartyNumber
customerContactId
• CDM: PartyId
Commerce: occ_partyId (custom)
Account/Contact Address
• CDM: AddressNumber
Commerce: externalAddressId
• CDM: AddressId
B2B Order Account
• CDM: PartyId
Commerce: occ_accountPartyId (custom)
CPQ: Customer
SMC: PrimaryPartyId
B2B Order Contact
• CDM: PartyId
Commerce: occ_contactPartyId (custom)
CPQ: _asset_custom_contactPartyId (custom)
SMC: QuoteToContactId
B2B Order Address
• CDM: AddressNumber
Commerce: occ_AddressNumber (custom)
• AR: CustomerAccountId
CPQ: accountNumber_t
SMC: BillToAccountId
• AR: CustomerAccountSite > CustomerAccountSiteUse > SiteUseId
CPQ: billToSiteUseId_t
SMC: BillToSiteId
B2C Order Contact
• CDM: PartyId
Commerce: occ_contactPartyId (custom)
CPQ: customer
SMC: PrimaryPartyId
14-5
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
14-6
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
• CPQ_USERNAME: Specifies the basic authentication username for requests that go directly
to Oracle CPQ.
• CPQ_PASSWORD: Specifies the basic authentication password for requests that go directly to
Oracle CPQ.
• OSS_USERNAME: Specifies the basic authentication username for requests that go directly
to Oracle Subscription Management.
• OSS_PASSWORD: Specifies the basic authentication password for requests that go directly to
Oracle Subscription Management.
The following example issues a POST request to the doCreateExtensionVariable endpoint
that sets the OSS_USERNAME:
/ccadmin/v1/extensionEnvironmentVariables POST
{
"name": "OSS_USERNAME",
"value": "conmgr"
}
14-7
Chapter 14
Configure Oracle Commerce with Oracle Subscription Management
• /ccstorex/custom/v1/assets/{assetId}/modify
/ccagentx/custom/v1/assets/{assetId}/modify
Issue a POST request to modify an asset(with CPQ punch-in).
• /ccstorex/custom/v2/assets/{assetId}/modify
/ccagentx/custom/v2/assets/{assetId}/modify
Issue a POST request to modify an asset (with CPQ configurator API).
• /ccstorex/custom/v1/assets/{assetId}/renew
/ccagentx/custom/v1/assets/{assetId}/renew
Issue a POST request to renew an asset.
• /ccstorex/custom/v1/assets/{assetId}/resume
/ccagentx/custom/v1/assets/{assetId}/resume
Issue a POST request to resume an asset.
• /ccstorex/custom/v1/assets/{assetId}/upgrade
/ccagentx/custom/v1/assets/{assetId}/upgrade
Issue a POST request to upgrade an asset. (with CPQ punchin).
• /ccstorex/custom/v2/assets/{assetId}/upgrade
/ccagentx/custom/v2/assets/{assetId}/upgrade
Issue a POST request to upgrade an asset. (with CPQ configurator API).
• /ccstorex/custom/v1/assets/{assetId}/terminate
/ccagentx/custom/v1/assets/{assetId}/terminate
Issue a POST request to terminate an asset.
• /ccstorex/custom/v1/assets/{assetId}/suspend
/ccagentx/custom/v1/assets/{assetId}/suspend
Issue a POST request to suspend an asset.
Create SSE routes to validate billing addresses
Oracle Subscription Management expects an account level address for a business
account subscription. If an address which is linked to a contact is passed, Subscription
Management rejects it with an appropriate error.
You should design your storefront in a way that allows contacts to select only account
addresses when placing subscription orders. In the case where a contact is allowed to
enter a contact-level address instead, it is a good idea to validate the billing address
before the order is submitted.
If a contact enters their billing address instead of the account’s billing address when
creating a subscription order, the integration fails and the following error is logged: The
value of the attribute Billing Account is invalid. (OKC-195787).
Since the billing details can be updated even after order validation, this validation can’t
be handled as part of the order validation logic and hence this validation is not
available by default. You can avoid this error by adding validation code to the payment
webhook (genericCardPayment webhook for credit card payments and
genericPayment wehook for invoice payments) and creating a new SSE route (/v1/
validateSubscriptionOrderBillingAddress) to perform the validation. Point the
webhook to the newly created route.
14-8
Chapter 14
Install and Configure the Integration in OIC
For details about account and contact addresses, see Manage an Account-based Storefront
in Using Oracle Commerce.
Configure payments
In this release of the integration, Commerce shoppers can pay for subscription orders with
either a credit card or an invoice. For credit cards, create a custom CyberSource integration
using the Generic Payment webhook. A payment gateway configured with the Generic
Payment webhook handles stored credit cards and tokens, which , which are required for this
integration. See Create a Generic Payment Gateway Integration in Extending Oracle
Commerce for more information.
Credit card payments
For credit card payments to work properly, Commerce must send a multi- use token to Oracle
Subscription Management.
Commerce does not store the complete credit card data. Instead, when a shopper stores a
credit card, the payment processor associated with the payment gateway sends back a token
that represents the card number. The token is used for each transaction associated with a
subscription payment.
When the shopper submits a subscription order, Commerce, through the gateway, authorizes
a one-time payment against the card. When you implement this integration, you should
populate the muilti use token for the credit card used to pay for the order in statusProps.
After the initial one-time charge, further subscription and billing is not authorized by
Commerce. Instead, Commerce will send the multi-use token to Oracle Subscription
Management, which, in turn, sends the token to the Oracle Accounts Receivable module.
As part of the payment integration, you need to return back a reusable credit card token to
the generic payment webhook response in the property token under statusProps under
authorizationStatus. This value will be sent to Oracle Subscription Management for the
periodic billing.
"paymentGroups": [
{
"authorizationStatus": [
{
"amount": 50,
"statusProps": {
"token": "12345678"
}
}
]
}
]
14-9
Chapter 14
Install and Configure the Integration in OIC
14-10
Chapter 14
Install and Configure the Integration in OIC
Enter the OSC Services Catalog WSDL URL, Interface Catalog URL, and Security
(Username Password Token). For example:
OSC Services Catalog WSDL URL: https://host/fscmService/
ServiceCatalogService?wsdl
Interface Catalog URL: https://host/helpPortalApi/otherResources/latest/
interfaceCatalogs
6. Select Oracle REST Trigger Employee Service. This is the trigger connection for the child
integration Oracle Financials Bill To Account Integration. No configuration is necessary;
just test and save the trigger.
7. Select CDM_AR. This is connection to Oracle Financials Accounts Receivable.
Enter the WSDL URL and Security (Username Password Token). For example: https://
host/foundationParties/CustomerAccountService?WSDL
Constant Value
subscriptionProfile zOSS_SP_ServiceStartFixed_Advance_Month
InternalApproval NOTREQUIRED
SourceSystem CX_CLOUD_COMMERCE
GenerateBillingSchedule Y
GenerateBillingScheduleForfullperiod Y
ChargeDefinition QP_RECURRING_SALE_PRICE,
QP_SALE_PRICE
ExternalKey Recurring fee, Activation fee
ExternalParentKey Mapped to catalogRefId in order payload
PriceSystem CPQ
name Activate , resume, suspend and close
RelationShipTypeCode RENEW, AMEND
PriceType ORA_ONE_TIME, ORA_RECURRING
Configure lookups
You must update the following lookup tables to map the following relationships:
• Site Merchant Details – Provides a mapping relationship between Site id, Definition
Organization ID, Business Unit ID and Legal entity ID.
14-11
Chapter 14
Customize Storefront Widgets
14-12
Chapter 14
Customize Storefront Widgets
the details from Oracle Subscription Cloud. The Assets widget appears on the Assets layout.
The following illustration shows a shopper’s subscriptions, displayed in the widget.
When the shopper clicks the Show Products button, the Subscription Asset Details widget
displays in the Asset Details layout.
Customize the Assets widget code
By default, the Assets widget shows the root level assets on the assets page and clicking on
the Details link redirects the shopper to the asset details. For this integration, you will
customize the widget to show the subscriptions on the page first, then give the shopper the
option to view subscription products. By checking details of a particular subscription product,
the shopper will be directed to the root asset details associated with the product.
To make these changes to the Assets widget, update the widget’s .js file.
if ( !this.user().loggedIn() ) {
navigation.doLogin(navigation.getPath(), this.links().home.route);
}
widget.showProductsFlag(false);
}
14-13
Chapter 14
Customize Storefront Widgets
ccRestClient.endpointRegistry[ENDPOINT_VIEW_ACCOUNT_ASSET] = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_VIEW_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "GET",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets",
"useOptimisticLock": false
};
ccRestClient.endpointRegistry.getAllSubscription = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": false,
"httpsRequired": false,
"id": GET_ALL_SUBSCRIPTIONS,
"localeHint": "assetLanguageOptional",
"method": "GET",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/oss/subscription/getAll",
"useOptimisticLock": false
}
ccRestClient.endpointRegistry.getAllSubscriptionProducts = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": false,
"httpsRequired": false,
"id": GET_ALL_SUBSCRIPTION_PRODUCTS,
"localeHint": "assetLanguageOptional",
"method": "GET",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
14-14
Chapter 14
Customize Storefront Widgets
"url": "/ccstorex/custom/v1/oss/subscription/products",
"useOptimisticLock": false
}
});
// Use the widget's asetsPerPage config
// option value if it has been set
if ( widget.assetsPerPage && !isNaN(widget.assetsPerPage()) ) {
widget.pageSize(10);
}
widget.currentPage = ko.pureComputed(function() {
var returnValue = Math.ceil( ( widget.offset() +
widget.pageSize() ) / widget.pageSize() );
return returnValue;
});
widget.previousPage = ko.pureComputed(function() {
var calculatedPreviousPage = widget.currentPage() - 1;
var returnValue = ( ( calculatedPreviousPage < 1 ) ? 1 :
calculatedPreviousPage );
return returnValue;
});
widget.nextPage = ko.pureComputed(function() {
var calculatedNextPage = widget.currentPage() + 1;
var returnValue = ( ( calculatedNextPage > widget.totalPages ) ?
widget.totalPages : calculatedNextPage );
return returnValue;
});
widget.onFirstPage = ko.pureComputed(function() {
return ( widget.currentPage() === 1 );
});
widget.onLastPage = ko.pureComputed(function() {
var returnValue = false;
if ( widget.totalPages() > 1 ) {
if ( widget.currentPage() === widget.totalPages() ) {
returnValue = true;
}
}
else if ( !widget.onFirstPage() && !widget.hasMore() ) {
returnValue = true;
}
return returnValue;
14-15
Chapter 14
Customize Storefront Widgets
});
widget.pageLinks = ko.pureComputed(function() {
// This would be a good place to do something more
// sensible with the individual page links that
// are displayed when there are a large number of
// results e.g. could display just the 5 pages either
// side of the current page. For now display every
// individual page.
var links = [];
return links;
});
widget.shouldShowGoToLastPage = ko.pureComputed(function() {
return ( widget.totalPages() > 1 );
});
widget.isPagingRequired = ko.pureComputed(function() {
var returnValue = false;
if ( widget.totalPages() > 1 ) {
returnValue = true;
}
else if ( widget.hasMore() ) {
returnValue = true;
}
else if ( !widget.onFirstPage() ) {
returnValue = true;
}
return returnValue;
});
14-16
Chapter 14
Customize Storefront Widgets
widget.assets(data.items);
widget.offset(data.offset);
widget.hasMore(data.hasMore);
// if totalPages is not returned (i.e. is null)
// then set to -1; in this scenario only simple
// paging will be available (i.e. go to first page,
// go to previous page and go to next page) and
// the hasMore value will be used to control
widget.totalResults(data.totalResults || -1);
spinner.destroyWithoutDelay(widget.spinnerOptions.parent);
// }
navigation.doLogin(navigation.getPath,
widget.links().home.route);
} else {
navigation.goTo(widget.links().profile.route);
}
spinner.destroyWithoutDelay(widget.spinnerOptions.parent);
}
if ( widget.user().loggedIn() ) {
var calculatedOffset = ( pageNumber - 1 ) * widget.pageSize();
spinner.create(widget.spinnerOptions);
var queryString = 'Status=ORA_ACTIVE';
var payload = {
limit: 10,
offset:calculatedOffset,
q: queryString,
orderBy:"CreationDate:desc"
};
ccRestClient.request(
GET_ALL_SUBSCRIPTIONS,
payload,
success,
error
);
}
};
widget.handleQuickViewClick = function(pIsModal) {
var popup;
if(pIsModal === true && this.productDetails) {
widget.productDetails(this.productDetails);
popup = $("#cc-upgrade-asset-display");
14-17
Chapter 14
Customize Storefront Widgets
popup.modal('show');
}
};
//---------------------------------------------------//
//Function Specific to subscription products table
widget.productTotalPages = ko.pureComputed(function(){
var returnValue = Math.ceil(widget.productsTotalResults()/
widget.productPageSize())
return returnValue;
});
widget.productCurrentPage = ko.pureComputed(function(){
var returnValue = Math.ceil((widget.productsOffset()
+widget.pageSize())/widget.pageSize());
return returnValue;
});
widget.previousProductPage = ko.pureComputed(function() {
var calculatedPreviousPage = widget.productCurrentPage()-1;
var returnValue = ( ( calculatedPreviousPage < 1 ) ? 1 :
calculatedPreviousPage );
return returnValue;
});
widget.nextProductPage = ko.pureComputed(function() {
var calculatedNextPage = widget.productCurrentPage() + 1;
var returnValue = ( ( calculatedNextPage >
widget.productTotalPages ) ? widget.productTotalPages :
calculatedNextPage );
return returnValue;
});
widget.onProductFirstPage = ko.pureComputed(function() {
return ( widget.productCurrentPage() === 1 );
});
widget.onProductLastPage = ko.pureComputed(function() {
var returnValue = false;
if ( widget.productTotalPages() > 1 ) {
if ( widget.productCurrentPage() ===
widget.productTotalPages() ) {
returnValue = true;
}
}
else if ( !widget.onProductFirstPage() && !
widget.productshasMore() ) {
returnValue = true;
}
return returnValue;
});
widget.shouldShowGoToProductsLastPage =
14-18
Chapter 14
Customize Storefront Widgets
ko.pureComputed(function() {
return ( widget.productTotalPages() > 1 );
});
widget.isProductPagingRequired = ko.pureComputed(function() {
var returnValue = false;
if ( widget.productTotalPages() > 1 ) {
returnValue = true;
}
else if ( widget.productshasMore() ) {
returnValue = true;
}
else if ( !widget.onFirstPage() ) {
returnValue = true;
}
return returnValue;
});
widget.productPageLinks = ko.pureComputed(function() {
var links = [];
return links;
});
widget.goToProductPage = function(pageNumber) {
function showProductSuccess(data) {
widget.subscriptionProducts(data.items);
widget.productsOffset(data.offset);
widget.productshasMore(data.hasMore);
widget.productsTotalResults(data.totalResults || -1);
spinner.destroyWithoutDelay(widget.spinnerOptions.parent);
}
function showProductFailure(err) {
if (data.status == ccConstants.HTTP_UNAUTHORIZED_ERROR) {
widget.user().handleSessionExpired();
navigation.doLogin(navigation.getPath,
widget.links().home.route);
} else {
navigation.goTo(widget.links().profile.route);
}
spinner.destroyWithoutDelay(widget.spinnerOptions.parent);
}
14-19
Chapter 14
Customize Storefront Widgets
if (widget.user().loggedIn()){
var calculatedOffset = ( pageNumber - 1 ) *
widget.pageSize();
//let queryString = `SubscriptionNumber=$
{widget.currentSubscriptionNumber()};Status=ORA_ACTIVE;ExternalParentAs
setKey is NULL`;
//var queryString = "SubscriptionNumber=" +
widget.currentSubscriptionNumber();
var queryString = "SubscriptionNumber=" +
widget.currentSubscriptionNumber();
var payload = {
limit: 25,
offset:calculatedOffset,
q: queryString,
orderBy:"StartDate:desc"
};
ccRestClient.request(
GET_ALL_SUBSCRIPTION_PRODUCTS,
payload,
showProductSuccess,
showProductFailure
);
}
};
// Call WAPI.
14-20
Chapter 14
Customize Storefront Widgets
ccRestClient.request(
ENDPOINT_VIEW_ACCOUNT_ASSET,
payload,
widget.getAssetDetailsSuccess,
widget.getAssetDetailsError
);
};
widget.getAssetDetailsSuccess = function(data) {
/* if(data && data.items) {
data.items.forEach(function(item){
$.extend(item, {
route:
`${widget.links().assetDetails.route}/${item.assetId}`
})
})
} */
if(data.items.length>0)
navigation.goTo(widget.links().assetDetails.route + "/" +
data.items[0].assetId);
else
navigation.goTo(widget.links().profile.route);
};
widget.getAssetDetailsError = function(data) {
if (data.status == ccConstants.HTTP_UNAUTHORIZED_ERROR ||
data.status == ccConstants.BAD_REQUEST) {
widget.user().handleSessionExpired();
navigation.doLogin(navigation.getPath,
widget.links().home.route);
}
else {
navigation.goTo(widget.links().profile.route);
}
spinner.destroyWithoutDelay(widget.spinnerOptions.parent);
};
14-21
Chapter 14
Customize Storefront Widgets
The following illustration shows the details of a subscription, displayed in the widget.
ccRestClient.registerInitCallback(function(){
ccRestClient.endpointRegistry[ENDPOINT_VIEW_ACCOUNT_ASSET] = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_VIEW_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "GET",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}",
"useOptimisticLock": false
14-22
Chapter 14
Customize Storefront Widgets
};
ccRestClient.endpointRegistry[ENDPOINT_RENEW_ACCOUNT_ASSET] = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_RENEW_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "POST",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}/renew",
"useOptimisticLock": false
};
ccRestClient.endpointRegistry[ENDPOINT_MODIFY_ACCOUNT_ASSET] = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_MODIFY_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "POST",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}/modify",
"useOptimisticLock": false
};
ccRestClient.endpointRegistry[ENDPOINT_TERMINATE_ACCOUNT_ASSET] = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_TERMINATE_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "POST",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}/terminate",
"useOptimisticLock": false
};
ccRestClient.endpointRegistry[ENDPOINT_SUSPEND_ACCOUNT_ASSET] = {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
14-23
Chapter 14
Customize Storefront Widgets
"httpsRequired": false,
"id": ENDPOINT_SUSPEND_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "POST",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}/suspend",
"useOptimisticLock": false
};
ccRestClient.endpointRegistry[ENDPOINT_RESUME_ACCOUNT_ASSET] =
{
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_RESUME_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "POST",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}/resume",
"useOptimisticLock": false
};
ccRestClient.endpointRegistry[ENDPOINT_UPGRADE_ACCOUNT_ASSET]
= {
"authRequired": true,
"cachingEnabled": false,
"hasDoc": false,
"hasPathParams": true,
"httpsRequired": false,
"id": ENDPOINT_UPGRADE_ACCOUNT_ASSET,
"localeHint": "assetLanguageOptional",
"method": "POST",
"requestType": "application/json",
"responseType": "application/json",
"singular": false,
"url": "/ccstorex/custom/v1/assets/{}/upgrade",
"useOptimisticLock": false
};
});
14-24
Chapter 14
Integration Flows
Integration Flows
This integration includes six process flows.
This integration includes the following process flows:
• Create/View Subscription
• Modify Subscription
• Renew Subscription
• Terminate Subscription
• Suspend Subscription
• Resume Subscription
To learn more about the product abbreviations used in these flows, see Understand the
Subscription Management Integration.
Modify Subscription
The integration modifies configurations, changes quantities, upgrades or downgrades the
service as defined in the CPQ configuration.
1. CDM: Get AddressId using AddressNumbers (shipping and billing addresses) for Account
2. CDM: If Account addresses are not found, get AddressId using AddressNumbers
(shipping and billing addresses) for Contact
3. CDM: If Contact addresses are not found, create the addresses
4. AR: Check if a site exists for the addresses
5. AR: If not, then create a site
6. Subscription: Get subscription lines details for each line in a loop
7. Subscription: Add/Update/Delete subscription lines for each line in a loop
8. Subscription: Activate subscription
14-25
Chapter 14
Integration Flows
Suspend Subscription
The integration suspends, but does not terminate, an active subscription.
1. CDM: Get AddressId using AddressNumbers (shipping and billing addresses) for
Account
2. CDM: If Account addresses are not found, get AddressId using AddressNumbers
(shipping and billing addresses) for Contact
3. CDM: If Contact addresses are not found, create the addresses
4. AR: Check if a site exists for the addresses
5. AR: If not, then create a site
6. Subscription: Get subscription lines details for each line in a loop
7. Subscription: Update subscription lines for each line in a loop
Resume Subscripiton
The integration resumes a suspended subscription.
1. CDM: Get AddressId using AddressNumbers (shipping and billing addresses) for
Account
2. CDM: If Account addresses are not found, get AddressId using AddressNumbers
(shipping and billing addresses) for Contact
3. CDM: If Contact addresses are not found, create the addresses
4. AR: Check if a site exists for the addresses
5. AR: If not, then create a site
6. Subscription: Get subscription lines details for each line in a loop
7. Subscription: Update subscription lines (Resume SubscriptionProducts) for each
line in a loop
8. Subscription: Get updated subscription lines details for each line in a loop
9. Subscription: Update subscription lines (with asset key) for each line in a loop
10. Subscription: Activate subscription
Terminate Subscription
The integration deletes a subscription.
1. CDM: Get AddressId using AddressNumber for Account
2. CDM: If Account addresses are not found, get AddressId using AddressNumber
for Contact
3. CDM: If Contact addresses are not found, create address
4. AR: Check if a site exists for the address
5. AR: If not, then create site
6. Subscription: Get subscription lines details for each line in a loop
7. Subscription: Update subscription lines (Close) for each line in a loop
14-26
Chapter 14
Integration Flows
Renew Subscription
The integration renews subscriptions at the end of period of their original subscription date.
Note that a shopper cannot renew a subscription unless a renewal draft subscription has
been created in Oracle Subscription Management via the ESS job. The Subscription
Management GET subscription product endpoint returns renew as a valid action if a draft
subscription is present for the current subscription.
1. CDM: Get AddressId using AddressNumber for Account
2. CDM: If Account addresses are not found, get AddressId using AddressNumber for
Contact
3. CDM: If Contact addresses are not found, create address
4. AR: Check if a site exists for the address
5. AR: If not, then create site
6. Subscription: Get draft renew subscription
7. Subscription: Get original subscription lines
8. Subscription: Create new subscription
9. Subscription: Add contact for account-based subscription
10. Subscription: Activate subscription
12. Subscription: Delete draft subscription lines for each line in a loop
14-27
15
Integrate with Oracle Unity
You can integrate Oracle Commerce with Oracle Unity. Oracle Unity allows you to combine
customer data from various sources to create a single view of each customer within your
Commerce instance.
Once you have integrated Oracle Unity with Commerce, you can personalize and customize
your shopper's experience on your web site by using Commerce Audience rules. You can
propagate data from Unity's unified customer and account models to attributes of Commerce
profile and account objects. Once you have the attributes, you can configure Audience rules
to present your shopper with personalized content.
For detailed information on working with Oracle Unity, refer to https://docs.oracle.com/en/
cloud/saas/cx-unity/cx-unity-user/index.htm. For detailed information on developer-based
tasks, refer to https://docs.oracle.com/en/cloud/saas/cx-unity/cx-unity-develop/index.htm. For
detailed information on working with Commerce Audiences, refer to the Define Audiences
section.
Integration Overview
Unity imports data from multiple systems into raw import tables. This raw data is moved into
source data tables within the data warehouse, meaning that records from multiple sources
are combined into a single source data table. Then a pipeline imports data from multiple
sources into a master data table according to the rules that you have configured. By default,
Unity uses the email field as the cluster key, although you can define any field, or set of field,
as the key. Each cluster is linked to a single master record in a master entity and fields
included in that master record are merged from the clustered source records. You can use
the Customer 360 API to directly query source and the master tables.
You can then use the Commerce Admin API to map Commerce profile properties to the
attributes of the Unity entities such as MasterCustomer and MasterAccount.
Note that there are two ways that your Commerce profile and account data are shared with
Unity. When you initially set up your configuration, you should manually export all of the
profile and account data form Commerce and import it into Unity. Once the integration is
enabled and configured, an automated process will periodically export all Commerce profiles
and accounts that have been updated and upload the export file to OOS.
15-1
Chapter 15
Configure Oracle Unity for Oracle Commerce
describe configuring a Unity data source to connect to the OOS, and then configuring
a Unity ingest job to read files from the OOS. You will also need to incorporate
Commerce Customer and Account records into the Unity mastering process and then
run an ingestion pipeline.
Configure synchronization
Before you configure Unity components, it is recommended that you export your
Profiles and Accounts to CSV files and upload the files to the Oracle Object Store.
This allows you to configure an Ingest Job using your data. To do this use the
Commerce Admin API and the exportProcess endpoint.
For detailed information on exporting data endpoints, refer to Export data endpoints.
When dynamically synchronizing profile and account data from Commerce to Unity,
the OOS works as a data transfer repository. The integrator configures an OOS bucket
that is accessible to both Commerce and Unity. It is recommended that you use a
dedicated OOS bucket to transfer data between Commerce and Unity. Only a single
bucket is required, and you can use the same bucket between manual bulk uploads, or
for automated incremental uploads that the integration feature performs.
You should also create or identify a user that has permissions to manage objects in the
OOS.
Next, you must upload the exported profile and account CSV files to the Oracle Object
Storage (OOS). It is recommended that you use the same file name prefixes as used
in the automatic incremental profile and account export, which are occs-profiles and
occs-accounts. This allows you to use the same Unity data source and Ingest Job
definition for both batch and any incremental imports.
Note: Because Unity does not provide a mechanism for removing files after ingestion,
it is recommended that you implement an appropriate Object Lifecycle Management
policy to eventually archive and/or delete these files. You must grant service
permissions to the Object Storage Service so that OOS may archive and delete
objects. For information on Object Lifecycle Management, refer to the Using Object
Lifecycle Management section in the Unity documentation.
Commerce uploads incremental export files to the OOS through a pre-authenticated
request (PAR) URL, which is configured by the integrator. For information on creating
this URL, refer to Using pre-authenticated requests. You must configure the PAR to be
write-only, with access to the appropriate bucket. OOS requires that you set an
expiration date on the PAR. Note that when the PAR expires, the synchronization of
Profiles and Accounts from Commerce to Unity will not work until you configure a new
PAR.
15-2
Chapter 15
Configure Oracle Unity for Oracle Commerce
15-3
Chapter 15
Configure Oracle Unity for Oracle Commerce
subrule must reference its own DSV, which allows you to search for fields related
to the subrule and return related fields.
• Data Source View (DSV) - The DSV specifies the attributes that are populated in
the IDGraph table, as well as the attributes you can use when performing a search
query and what is returned in the search results. DSVs must be referenced by the
ID Graph Rule and each subrule within the ID Graph Rule.
For additional information on creating ID Graph Rules, subrules and DSVs, refer to this
tutorial in the Unity documentation.
When you create the main DSV:
• The main DSV is the DSV that is associated with the primary IDGraphRule object.
• There are two outputAttributes with the DSV:
– Inside operands objects, also known as inner outputAttributes objects -
These are the column names that you specify after the SELECT keywords in an
SQL query. You can select as many attributes as needed from the table, which
is specified in the objectName object.
– Inside MCPSQuery objects, also known as outer outputAttributes objects - To
use attributes with this object, the attribute must be referenced before the
inner outputAttributes object. The outer outputAttributes object in the
IDGraphRule object specifies the attributes that you can search across and the
attributes that are returned in the search results.
The following example shows how you would extract five attributes from the Customer
table. This includes ID, SourceCustomerID, SourceID, Email and AccountID. These
attributes are pulled from the inner outputAttributes object and then exposes those
in the outer outputAttributes object. This allows you to search them and return
search results.
Issue a POST command to {{Tenant URL}}/{{api-metadata_v1}}/{{MCPS Tenant
Key}}/metadata/datasourceviews.
{
"tenantId": 100052,
"name": "OCC_Profile_DSV",
"versionTS": 1611872531438,
"active": true,
"dataSourceViewID": "OCC_Profile_DSV",
"sourceTableQuery": {
"MCPSQuery": {
"tenantId": 0,
"operation": {
"ctype": ".SetOperation",
"tenantId": 0,
"operands": [{
"ctype": ".ObjectSet",
"tenantId": 0,
"name": "c1",
"objectName": "Customer",
"outputAttributes": [{
"atype": ".ReferenceAttribute",
15-4
Chapter 15
Configure Oracle Unity for Oracle Commerce
"tableName": "c1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceCustomerID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "Email"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "AccountID"
}
],
"distinct": false
},
null
],
"operator": "INTERSECTION",
"distinct": false,
"outputAttributes": [{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceCustomerID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "Email"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "AccountID"
}
15-5
Chapter 15
Configure Oracle Unity for Oracle Commerce
],
"joinConditions": []
},
"type": "DW"
}
}
}
{
"tenantId": 100052,
"name": "OCC_Account_DSV",
"versionTS": 1628229524814,
"active": true,
"lastModifiedBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdTS": 1628229524814,
"dataSourceViewID": "OCC_Account_DSV",
"sourceTableQuery": {
"MCPSQuery": {
"tenantId": 0,
"operation": {
"ctype": ".SetOperation",
"tenantId": 0,
"operands": [
{
"ctype": ".ObjectSet",
"tenantId": 0,
"name": "a1",
"objectName": "Account",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "a1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "a1",
"attributeName": "SourceAccountID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "a1",
"attributeName": "SourceID"
}
],
"distinct": false
},
null
],
"operator": "INTERSECTION",
"distinct": false,
15-6
Chapter 15
Configure Oracle Unity for Oracle Commerce
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "a1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "a1",
"attributeName": "SourceAccountID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "a1",
"attributeName": "SourceID"
}
],
"joinConditions": []
},
"type": "DW"
}
}
}
}
}
{
"tenantId": 100052,
"name": "OCC_Profile_Subrule_DSV",
"versionTS": 1620369103427,
15-7
Chapter 15
Configure Oracle Unity for Oracle Commerce
"active": true,
"lastModifiedBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdTS": 1620369103427,
"dataSourceViewID": "OCC_Profile_Subrule_DSV",
"sourceTableQuery": {
"MCPSQuery": {
"tenantId": 0,
"operation": {
"ctype": ".SetOperation",
"tenantId": 0,
"operands": [{
"ctype": ".ObjectSet",
"tenantId": 0,
"name": "c1",
"objectName": "Customer",
"outputAttributes": [{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceCustomerID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "AccountID"
}
],
"distinct": false
},
{
"ctype": ".ObjectSet",
"tenantId": 0,
"name": "m1",
"objectName": "MasterCustomer",
"outputAttributes": [{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Email"
},
{
15-8
Chapter 15
Configure Oracle Unity for Oracle Commerce
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "FirstName"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "LastName"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Age"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Gender"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "AOV"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "City"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Country"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "JobTitle"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "months_since_last_purchase"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "days_since_last_purchase"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "first_purchase_date"
},
{
15-9
Chapter 15
Configure Oracle Unity for Oracle Commerce
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "okToEmail"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "okToText"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Phone"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "State"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "top_brand"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "top_product"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "top_product_category"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_order_count"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_purchase_count"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_return_count"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_spent_amt"
},
{
15-10
Chapter 15
Configure Oracle Unity for Oracle Commerce
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ZipCode"
}
],
"distinct": false
}
],
"operator": "INTERSECTION",
"distinct": false,
"outputAttributes": [{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceCustomerID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "SourceID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "AccountID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "FirstName"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "LastName"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Email"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Age"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Gender"
},
15-11
Chapter 15
Configure Oracle Unity for Oracle Commerce
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "AOV"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "City"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Country"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "JobTitle"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "months_since_last_purchase"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "days_since_last_purchase"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "first_purchase_date"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "okToEmail"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "okToText"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Phone"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "State"
},
15-12
Chapter 15
Configure Oracle Unity for Oracle Commerce
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "top_brand"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "top_product"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "top_product_category"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_order_count"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_purchase_count"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_return_count"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "total_spent_amt"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ZipCode"
}
],
"joinConditions": [{
"left": {
"atype": ".ReferenceAttribute",
"tableName": "c1",
"attributeName": "ID"
},
"right": {
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ID"
}
}]
},
"type": "DW"
15-13
Chapter 15
Configure Oracle Unity for Oracle Commerce
}
}
}
The following is an example of an Account subrule DSV. Note that the account subrule
DSV POST request does not contain a reference to the Account object because you are
not referencing any attributes from that object. If you need to reference an attribute
from an object in Unity, you would need to specify the object from which you would be
referencing. As in the case of the Profile subrule DSV, you referenced the attributes
from the Customer object as c1 and the MasterCustomer objects as m1.
{
"tenantId": 100052,
"name": "OCC_Account_Subrule_DSV",
"versionTS": 1628229554895,
"active": true,
"lastModifiedBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdTS": 1628229554895,
"dataSourceViewID": "OCC_Account_Subrule_DSV",
"sourceTableQuery": {
"MCPSQuery": {
"tenantId": 0,
"operation": {
"ctype": ".SetOperation",
"tenantId": 0,
"operands": [
{
"ctype": ".ObjectSet",
"tenantId": 0,
"name": "m1",
"objectName": "MasterAccount",
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "AddressLine1"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "AddressLine2"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "City"
},
{
15-14
Chapter 15
Configure Oracle Unity for Oracle Commerce
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Country"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Name"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "State"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Type"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ZipCode"
}
],
"distinct": false
},
null
],
"operator": "INTERSECTION",
"distinct": false,
"outputAttributes": [
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ID"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "AddressLine1"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "AddressLine2"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "City"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
15-15
Chapter 15
Configure Oracle Unity for Oracle Commerce
"attributeName": "Country"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Name"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "State"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "Type"
},
{
"atype": ".ReferenceAttribute",
"tableName": "m1",
"attributeName": "ZipCode"
}
],
"joinConditions": []
},
"type": "DW"
}
}
}
{
"tenantId": 100052,
"name": "occ7",
"versionTS": 1611942055656,
"active": true,
"ruleId": "occ7",
"inputDsvId": "OCC_Profile_DSV",
"mainIdentifier": {
"atype": ".DSVAttribute",
"dsvId": "OCC_Profile_DSV",
"attributeName": "ID"
},
"dedupeTargetId": "customer_mastercustomer",
15-16
Chapter 15
Configure Oracle Unity for Oracle Commerce
"subRules": [{
"tenantId": 100052,
"name": "OCC Profile Subrule",
"versionTS": 1611790281085,
"active": true,
"ruleId": "occ7",
"subRuleId": "OCC_Profile_Subrule",
"masterEntity": true,
"inputDsvId": "OCC_Profile_Subrule_DSV",
"identifier": {
"atype": ".DSVAttribute",
"dsvId": "OCC_Profile_Subrule_DSV",
"attributeName": "ID"
},
"maxRecords": 100
}]
}
{
"tenantId": 100052,
"name": "occ9",
"versionTS": 1628299175767,
"active": true,
"lastModifiedBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdBy": "fc524ec322dd4bdca13c06e6261cc725",
"createdTS": 1628299175767,
"ruleId": "occ9",
"inputDsvId": "OCC_Account_DSV",
"mainIdentifier": {
"atype": ".DSVAttribute",
"dsvId": "OCC_Account_DSV",
"attributeName": "ID"
},
"dedupeTargetId": "account_masteraccount",
"subRules": [
{
"tenantId": 100052,
"name": "OCC Account Subrule",
"versionTS": 1628229619713,
"active": true,
"createdTS": 1628229619713,
"ruleId": "occ9",
"subRuleId": "OCC_Account_Subrule",
"masterEntity": true,
"inputDsvId": "OCC_Account_Subrule_DSV",
"identifier": {
"atype": ".DSVAttribute",
"dsvId": "OCC_Account_Subrule_DSV",
"attributeName": "ID"
},
"maxRecords": 100
}
15-17
Chapter 15
Configure Commerce for Oracle Unity
]
}
15-18
Chapter 15
Configure Commerce for Oracle Unity
Once you have enabled the Unity integration, you are presented with the Unity
Configuration page, which requires you to:
• Enter the Server URL
• Enter the Channel ID
• Enter the Channel Token
• Add Unity Users.
You must set the Unity Profile Attributes by selecting the attributes of the data objects
available for the Profile, such as Account, Address and Customer. The following attributes are
for Account:
• Account Name - The name of the account.
• DUNS# - The Dunn & Bradstreet 9 digit business identifier.
• Employee Total - The number of employees within the company.
• NAICS Code - The North American Industry Classification System 6 digit code for the
business type.
• SIC Code - The Standard Industrial Classification 4 digit code for the company industry.
• Year Established - The year the company was established.
• Account Type - The type of the account.
• Account Status - The status of the account.
• Annual Revenue - The annual revenue of the company.
• Line of Business - The line of business.
The following attributes are for Address:
• Account ID
• Address Line 1
• Address Line 2
• City
• State
• AV is Valid - A flag that indicates if the address is valid or invalid
• Commerce Address Type - The type of address, for example, Shipping or Billing.
• Latitude
• Longitude
Set the Unity Behavioral Attributes, which include:
• Customer ID
• Severity - The severity level of the incident, including Critical, Major and Minor
• Sentiment
• Coupon Code
Set the Unity Transactional Attributes, which include:
• Customer ID
• Order Date
15-19
Chapter 15
Configure Commerce for Oracle Unity
• Quantity
• Discount
• Subtotal
• Tax Total
Set the Unity Product Attributes:
• Product ID
• Product Name
Set any other attributes necessary for your environment.
Once you have selected the attributes, save the page. Commerce creates the profile
extension table with the selected attributes.
Property Description
Token URL This is the URL to the Identity Cloud Service Oauth2 Token API.
Use the following format: https://idcs-
xxxxxxx.identity.oraclecloud.com/oauth2/v1/
token
Username The name of the Unity API user with access to the Unity API. You
must have the Instance Admin role access.
Password The Unity API user's password.
Client ID The client ID of the Unity application.
Client Secret The client secret for the Unity application.
Tenant URL The URL of your Unity instance.
IDCS App Scope The IDCS scope for the Unity application in the form https://
unityTenantUrl/cxunity.
Tenant Key The MCPS tenant access key. If you do not know this key, contact
your Unity administrator.
You must also configure the Oracle Object Store (OOS), which contains the Object
Store Pre-Authenticated Request (PAR) URL, which is the URL used by Commerce to
upload incremental export files. For information on creating this URL, refer to Using
pre-authenticated requests.
15-20
Chapter 15
Configure Commerce for Oracle Unity
which Commerce Organization or Profile properties. To do this, you must use the Commerce
API.
Unity attributes must be mapped onto existing Profile and Organization properties. You may
want to create custom properties to receive these mappings. Before defining the property
mappings, the Organization and Profile types should be extended using the itemTypes and
shopperTypes endpoints.
PUT /ccadmin/1/itemTypes/organization
{
"specifications": [
{
"label": "Account Notes",
"id": "internal_notes",
"default": null,
"required": false,
"localizable": false,
"internalOnly": false,
"textSearchable": false,
"searchable": false,
"multiSelect": false,
"type": "richText",
"uiEditorType": "richText"
}
]
}
PUT /ccadmin/v1/shopperTypes/users
{
"properties": {
"social_media_rating": {
"label": "Social Media Rating",
"type": "shortText",
"uiEditorType": "shortText",
"internalOnly": false,
"default": null,
"required": false,
"audienceVisibility": "all"
},
"top_brand": {
"label": "Favorite Brand",
"type": "shortText",
"uiEditorType": "shortText",
"internalOnly": false,
"default": null,
"required": false,
"audienceVisibility": "all"
}
15-21
Chapter 15
Configure Commerce Audiences with Unity Data
}
}
Once you have extended the properties, you must define property mappings using
the /enrichmentMaps endpoint. For example:
PUT /ccadmin/v1/enrichmentMaps
{
"IDGraphRuleName": "occ1",
"subRuleName": "OCC_Profile_Subrule",
"configMap": [
{
"sourceName": "Social_Score",
"sourceType": "string",
"targetName": "social_media_rating"
},
{
"sourceName": "top_brand",
"sourceType": "string",
"targetName": "top_brand"
}
],
"source": "customer",
"target": "profile"
}
15-22
Glossary
Glossary-1
Index
Index-1