Use case: Displaying the ServiceNow CPQ native UI via direct URL

Learn how to initialize a configuration UI using a URL instead of an external library.

This article provides an outline of how a ServiceNow CPQ Configuration UI can be initialized using a configuration URL rather than relying on an external library (such as easyXDM).

The base configuration URL is in the format https://{tenant}.cpq/ui/configure/{configurableProductId}, where:

• {tenant} is the ServiceNow CPQ tenant that you are using, which can be found in Salesforce or if using ServiceNow CPQ headless, the base URL of the Admin experience
• {configurableProductId} is the Product ID of the ServiceNow CPQ Configurable Product to use for the configuration

Example configuration URL: https://demo6.demo.logik.io/ui/configure/01t5f000006QKynAAG?v=1

Configuration URL query parameters

Additional settings and data can be passed via URL query parameters.

Table 1. Configuration URL query parametersParameters described, along with their valid values

Parameter	Description	Required	Values / Notes
v	Version	true	1
pid	Pricebook ID		Salesforce Pricebook ID
id	Configuration ID		ServiceNow CPQ UUID of existing configuration to load
lid	Quote Line ID		Salesforce Quote Line ID
qid	Quote ID		Salesforce Quote ID
log	Log Execution (Flightpath)		None | Available | Active This parameter is case sensitive.
cm	Committed Configuration ID		When a contracted order is amended, ServiceNow CPQ identifies the prior configuration ID. That ID then becomes the committed Configuration ID.
fields	Fields		Array of field objects. For example, [{"variableName ":"textField1","value":"test"},{…}] In JavaScript, use encodeURI to ensure any special characters are escaped
ac	Action Context		null or "Amendment"
e	Editability		One of: "Tm9uZQ" (None) "QXZhaWxhYmx l" (Available) "QWN0aXZl" (Active) This parameter is case sensitive.
layout	Layout Variable Name		Name of the layout to load from the blueprint of the configurable product
return	Return URL		URL to set window.location to on save or cancel. Needs to be encoded and URL-safe
rt	Runtime Token	See note below	Runtime token from ServiceNow CPQ Admin Setup
rta	Runtime API URL		Needs to be encoded and URL-safe. Highly recommended if using the runtime token parameter. Use encodeURI in Javascript to ensure that any special characters are escaped, especially when calling an API.
currency	Currency ISO Code

Note:

When using the runtime token (rt) parameter, it is highly recommended to also include the rta as well to ensure that all of the requests can be authenticated when using the Firefox or Safari browsers.

If you are not accessing the configuration URL where you have already authenticated (via Salesforce or directly), the runtime token will be required to authenticate. If you are accessing the configuration URL before authenticating through the associated SFDC environment or accessing the configuration URL for a headless environment, the ServiceNow CPQ tenant URL needs to be listed as an origin for the leveraged runtime client. For example, https://<yourCPQUrl>.test.cpq.

If the version parameter is not included, the UI will not load, and you will receive the following error: "Error: A version must be specified."

If a return URL is not included, the UI will broadcast a postMessage up to the parent, with the UUID on save (such as {"uuid": "8b88c843-d10b-468b-8c49-17f8c9698799"}) and an empty object on cancel ({}).

Using the configuration URL

The configuration URL can be used either as the top level window or in an iframe on a page.

Unlike when using the easyXDM example to initialize a configuration, configuration data will not be sent to the browser console in Javascript when using the configuration URL.

Considerations for using the configuration URL as the top level window URL:

• On the save or cancel actions, the ServiceNow CPQ UI will make the call to the ServiceNow CPQ backend to save or cancel the configuration. These calls can be viewed in the Network tab of the browser to see the data being sent and returned.
• If a return URL is included, the UI will attempt to set the window location to that URL on save ("Quote") or on cancel.

Considerations for using the configuration URL in an iframe:

• If a return URL is included, the UI will attempt to set the window location to that URL on save ("Quote") or on cancel. If a return URL is not included, the ServiceNow CPQ UI will broadcast a postMessage up to the parent, with the UUID on save (such as {"uuid": "8b88c843-d10b-468b-8c49-17f8c9698799"}) and an empty object on cancel ({}).
• For either implementation, after executing the save or cancel action, the configuration is removed. Subsequent save actions will result in a 404 error with an error message: "No Rules Engine found for Tenant with Config ID '<ServiceNow CPQ UUID>'. Subsequent cancel actions will also result in a 404 error.

Configuration result

The result of the saved Configuration can be accessed by using the GET API to retrieve the BOM data.

Postman Collection with Config API URL

The result can be sent to a downstream system via Webhook. See Webhooks.