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:

Items.png

  1. Use External Values - Useful to retrieve subscription id's, statuses - it is not possible to have such value defined in pricing plan in advance.

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

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

  1. Create or edit existing Pricing Plan:

1q.png

 

  1. Add dropdown or multi dropdown to the form:

2q.png

  1. Check "Use external values with prices" on the dropdown element and fill in the values which will be used by sequences later:

3q.png


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": ""
}

4q.png

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

5q.png

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:

6q.png

With following values:

7q.png

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

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

8q.png

After clicking any field:

9q.png

  1. Dynamic control will not work if "Use external values" option is selected:

11q.png

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

12q.png

Was this article helpful?

0 out of 0 found this helpful

Add comment

Please sign in to leave a comment.