Configure the 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).

Available Commerce server-side extensions (SSEs) can be installed and configured 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 in Extending Oracle Commerce 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. Finally the last section of this topic, Understand the general procedure for installing and configuring the integration SSEs , provides general instruction on downloading, installing, and configuring the available SSEs.

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.

Note: This SSE is optional and can be used if you want a credit check to be done as part of an order submit task.

You can configure the available SSEs, CheckCredit-store.zip and CheckCredit-agent.zip, by first downloading the SSE packages.

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.

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. In detail, this SSE is meant to get account details from CDM masters like OEC Communications and is required in Telco kind of installations

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 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.
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, see the Use Asset Based Ordering section of this guide.

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 the Understand the general procedure for installing and configuring integration SSEs section at the end of this topic.

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 Qualification 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. It also contains a module to check if the cancel in-flight is allowed for a given order.

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 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 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 the Understand the general procedure for installing and configuring the integration SSEs section at the end of this topic.

Configure the Services SSE

The Services SSE is used to perform modify, renew, terminate, suspend, and resume actions on a service or asset - one SSE for Storefront and one for Agent. The SSE also contains a module to check if the cancel in-flight feature is allowed for a given order and is also used to retrieve the assets and asset details

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.

The subsection(s) that follows describe the relevant endpoint(s) for this SSE.

Understand the Services SSE endpoints

The Server Side Extension Endpoints for the Services SSE are the following:

Modify
Renew
Terminate
Suspend
Resume

These endpoints are triggered when a user performs an operation on an asset.

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 this endpoint are BOM (Bill of Materials) and Error.

Configure the Configuration Validation SSE

The Configuration Validation SSE 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
GET_CONFIG_URI

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 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:
```
POST /ccadmin/v1/serverExtensions  HTTP/1.1
Content-Type: multipart/form-data
Authorization: Bearer <access_token>
```

The request body should consist of the <YOUR_SSE_NAME>.zip file, uploaded as multipart/form data. The response to the request should look similar to this:

{
    "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",
"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.

Understand the environment variables supported by the integration SSEs

When communicating with Commerce via its REST APIs, you need to authenticate your requests using confidential information. The need to authenticate is not just limited to Commerce as many 3rd party services require the same. It is recommended that you do not store confidential information in extension files but that you use environment variables to maintain value confidentiality. In the previous example config.json file, environment variables are used to make username and password information confidential. Commerce SSEs include the nconf package which provides a hierarchical node.js configuration with files, environment variables, command-line arguments, and atomic object merging. Use the hierarchy provided by nconf to manage your configuration values and maintain different values for different environments used in your integration. You can also use environment variables to pass through API information you want protected. Refer to "REST API authentication" in the Commerce REST API documentation for more info on how to authenticate Commerce API calls.

The specific environment variables supported by the integration SSEs are the following:

Table 2-1 Integration SSE environment variables

SSE name	Supported variable name	Description
CustomerAccountModel-Store	CRM_USERNAME	Specifies the basic authentication username for the accounts integration. In this case, for Oracle Integration Cloud (OIC) which integrates OEC Comms.
CustomerAccountModel-Store	CRM_PASSWORD	Specifies the basic authentication password for accounts integration. In this case, for OIC which integrates OEC Comms.
CustomerAccountModel-Agent	CRM_USERNAME	Specifies the basic authentication username. In this case, for Oracle Integration Cloud (OIC) which integrates OEC Comms.
CustomerAccountModel-Agent	CRM_PASSWORD	Specifies the basic authentication password for accounts integration. In this case, for OIC which integrates OEC Comms.
Services-Store	OIC_USERNAME	Specifies the basic authentication username for the accounts integration and Oracle Configure, Price, Quote integration that proxies via OIC.
Services-Store	OIC_PASSWORD	Specifies the basic authentication password for the accounts integration and Oracle Configure, Price, Quote integration that proxies via OIC.
Services-Store	CPQ_USERNAME	Specifies the basic authentication username for requests that go directly to Oracle Configure, Price, Quote.
Services-Store	CPQ_PASSWORD	Specifies the basic authentication password for requests that go directly to Oracle Configure, Price, Quote.
Services - Agent	OIC_USERNAME	Specifies the basic authentication username for the accounts integration and Oracle Configure, Price, Quote integration that proxies via OIC.
Services-Agent	OIC_PASSWORD	Specifies the basic authentication password for the accounts integration and Oracle Configure, Price, Quote integration that proxies via OIC.
Services-Agent	CPQ_USERNAME	Specifies the basic authentication username for requests that go directly to Oracle Configure, Price, Quote.
Services-Agent	CPQ_PASSWORD	Specifies the basic authentication password for requests that go directly to Oracle Configure, Price, Quote.
Order Qualification Pipeline	ORDER_QUALIFICATION_PIPELINE_USERNAME	Specifies the basic authentication username for securing the `/v1/orderQualification` route.
Order Qualification Pipeline	ORDER_QUALIFICATION_PIPELINE_PASSWORD	Specifies the basic authentication password for securing the `/v1/orderQualification` route.
Order Qualification Pipeline	VALIDATION_USERNAME	Specifies the basic authentication username for accessing the `/v1/crm/accounts` route in the Customer Account Model to retrieve accounts data.
Order Qualification Pipeline	VALIDATION_PASSWORD	Specifies the basic authentication password for accessing the `/v1/crm/accounts` route in the Customer Account Model to retrieve accounts data.
Order Qualification Pipeline	OIC_USER_NAME	Specifies the basic authentication username for accessing the services integration that integrates with Oracle Configure, Price, Quote to retrieve asset/services data.
Order Qualification Pipeline	OIC_PASSWORD	Specifies the basic authentication password for accessing the services integration that integrates with Oracle Configure, Price, Quote to retrieve asset/services data.
Order Validation Pipeline	ORDER_VALIDATION_PIPELINE_USERNAME	Specifies the basic authentication username for securing the /`v1/orderValidation` route.
Order Validation Pipeline	ORDER_VALIDATION_PIPELINE_PASSWORD	Specifies the basic authentication password for the `/v1/orderValidation` route
cpq-configurator-app-store	CPQ_USERNAME	Specifies the basic authentication username for requests that go directly to Oracle Configure, Price, Quote.
cpq-configurator-app-store	CPQ_PASSWORD	Specifies the basic authentication password for requests that go directly to Oracle Configure, Price, Quote.
cpq-configurator-app-agent	CPQ_USERNAME	Specifies the basic authentication username for requests that go directly to Oracle Configure, Price, Quote.
cpq-configurator-app-agent	CPQ_PASSWORD	Specifies the basic authentication password for requests that go directly to Oracle Configure, Price, Quote.

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.