Configure the Commerce server-side extensions

To perform specific functions relating to asset-based orders, you need to install and configure the related Commerce server-side extensions (SSEs).

Commerce includes some server-side extensions (SSEs) that you can configure to perform specific functions relating to asset-based orders.

For more complete information on server-side extensions and how to develop them for use with Commerce, refer to Develop server-side extensions section in the Extending Oracle Commerce book found in the Commerce Help Library.

The next sections in this topic explain the purpose and configuration of each available SSE as well as provide information on the inputs required for their respective endpoints.

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

Configure the Credit Check SSE

Since Commerce does not provide a pre-built integration with any particular credit checking system, the Credit Check SSE is used to connect to a third-party credit check system so that you can perform a credit check on the logged-in shopper.

As written, this SSE generates outbound calls to a master 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.

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.

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.

Configure the Customer Account Model SSE

This SSE is used to return information about the customer account model for a registered shopper or to update the customer account model when required.

You can configure the available SSEs, CustomerAccountModel-store.zip and CustomerAccountModel-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 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.
The new address as provided by the shopper.

The returns for this endpoint are the accounts, roles, addresses, and business profiles associated with the shopper.

Configure the Order Qualification SSE

This SSE is used to perform any final checks on an order before payment is authorized and the order is submitted to downstream systems for processing and fulfillment.

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.

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

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

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.