Use of External Options
In this article:
The External Values option enables CPQ to receive and convert data from external sources, such as Vendor APIs.
CPQ offers 3 external use options:
-
Use External Values - Useful to retrieve subscription id's, statuses - it is not possible to have such value defined in pricing plan in advance.
-
Use external Values with prices - Allows to set multiple values which will be returned from external source, supports price setup for each unique value. Missing values will result failure for a specific configuration.
-
Run External Validation - allows to validate configuration. As an example: customer has 5 licenses of a particular subscriptions and wants to change license count to 4, this data is sent to vendor API to validate whether it is allowed to have 4 in form data.
Whenever there is an update to the form in buy page, any control is changed or clicked All the fields with external options enabled in CPQ will create API calls to api/integration/externalOptions endpoint and then this information will be sent to AI to process.
How to set up external values in CPQ:
- Create or edit existing Pricing Plan:
- Add dropdown or multi dropdown to the form:
- Check "Use external values with prices" on the dropdown element and fill in the values which will be used by sequences later:
Use Case
As an example, we have Vendor Offer with offer levels which are received from Vendor API. In this scenario customers has specific levels which define the discount applied to the offers. Receiving the correct level will adjust the price.
Request is being sent to the following Vendor endpoint:
examplevendor/¦AzureTenant.ExternalId§/orders
The Level is received for the corresponding setup of the customer on the Vendor side using Vendor Customer ID
With following parameters:
{
"currencyCode": "EUR",
"orderType": "PREVIEW",
"lineItems": [
{
"extLineItemNumber": 1,
"offerId": "¦Offer.VendorExternalId§",
"quantity": "¦customerInput.LicenseQuantityKey§"
}
]
}
And returns the Level which then is displayed on UI:
{
"creationDate": "2024-01-23T11:41:43Z",
"currencyCode": "EUR",
"customerId": "P1005076435",
"externalReferenceId": "",
"lineItems": [
{
"extLineItemNumber": 1,
"offerId": "65327721CA01A12",
"quantity": 1,
"status": "",
"subscriptionId": ""
}
],
"orderId": "",
"orderType": "PREVIEW",
"referenceOrderId": "",
"status": ""
}
The sequence is executed based on these conditions:
{
"uniqueKey": "priceLevelKey",
"¦AzureTenant.ExternalId§": "#notblank",
"¦customerInput.action§": "placeOrder"
}
"uniqueKey" is the indication which field is using the external options
Payload received by CPQ:
[
{
"title": {
"en-US": "Level 1 (65327721CA01A12)"
},
"value": "65327721CA01A12"
}
]
Response Sequence for above payload:
[
{
"title": {
"en-US": "¦DynamicParams.Level§ Part Number: ¦DynamicParams.offerLevelId§"
},
"value": "¦DynamicParams.offerLevelId§"
}
]
It is defined by Sequences with Operation "GetExternalData"
Payload sent to AI:
{
"customerId": "",
"customerInput": {},
"action": "",
"universalTenantDomainKey": {
"DomainName": "",
"InternalId": ""
},
"ExternalId": "",
"effectiveDate": "",
"offerId": "",
"operation": "",
"resellerId": "",
"uniqueKey": "",
"userId": "",
"vendorId": ""
}
Example of the response sequence which returns data to CPQ:
{
"Id" : "02379CCC-09BC-42CB-BA9E-5F80EBB7108A",
"Link" : "",
"Sequence" : 115,
"Params" : "",
"Hints" : "{\"EnforceUtf8\":true,'STOP':'STOP'}",
"Method" : "RESPONSE",
"Response" : "[{'value': '¦DynamicParams.offerLevelId§','title': {'en-US': '¦DynamicParams.Level§ (¦DynamicParams.offerLevelId§)'}}]",
"OfferId" : "00000000-0000-0000-0000-000000000000",
"Header" : "",
"ExecutionCondition" : "{'uniqueKey':'priceLevelKey','¦customerInput.action§':'placeOrder','¦DynamicParams.Level§':'#notblank'}",
"ExternalMapping" : "",
"ExternalSystemId" : "00000000-0000-0000-0000-000000000000",
"Comments" : "LEVEL DISCOUNT - Return successful values",
"RethinkMapping" : "",
"Operation" : "GetExternalData",
"VendorTenantId" : "00000000-0000-0000-0000-000000000000",
"PlatformId" : "00000000-0000-0000-0000-000000000000",
"VendorId" : "02F64CF6-E340-4086-A244-315D0E61534F",
"Source" : "SequenceUploader",
"CreatedBy" : null,
"CreatedDate" : null
}
If Multi dropdown is being used:
With following values:
Process is similar, except the output contains array with values, for example:
{
"OfferId": "",
"FormData": {
"dropdownKey": ["value1", "value2", "value3", "value4"],
"numberKey": 1
},
"OrderDate": "2024-01-23T00:00:00Z",
"ParentOfferId": null
}
And response sent to CPQ is following:
[
{
"value": "value1",
"title": {
"en-US": "Create an Order"
}
},
{
"value": "value2",
"title": {
"en-US": "some option1"
}
},
{
"value": "value3",
"title": {
"en-US": "some option2"
}
},
{
"value": "value4",
"title": {
"en-US": "some option3"
}
}
]
Limitations
- If "Use external options with prices" is used on subscription edit page the dropdown will contain all options and won't be updated until user clicks inside any field that will trigger the external data update call. In subscription edit page when opening:
After clicking any field:
- Dynamic control will not work if "Use external values" option is selected:
- If field is not read only and the value is empty or null CPQ will load the new value from AI and cause no issues. If field is read only and empty or null during checkout there will be the following error:
Was this article helpful?
Articles in this section
- Industry-specific offers and pricing
- Product Management Overview
- How to create new Products?
- How can I modify product details in Product Management/SKU Builder?
- How to Create New Offers?
- Custom CTA for an offer
- How to create a copy of the existing offer?
- Offer can be published only when pricing plan is set up
- Automatic offer provisioning
- How to create new Add-on?
Add comment
Please sign in to leave a comment.