Overview
The following information will aid existing Oracle CPQ customers in transitioning Configuration SOAP API web services to REST API web services. Unlike SOAP APIs, REST APIs will not ignore errors sent in the request. Therefore, administrators should use the following guidelines to ensure valid REST API requests.
This topic applies to Oracle CPQ Update 19B or later.
Why convert From SOAP APIs to REST APIs?
REST APIs promote simpler API calls and more robust integrations using HTTP standards.
Retrieve the Configuration REST Swagger Definition
Within the Interface Catalog for a given REST service, you will find definitions, properties, and links. Definitions give you a description of the type of resource you are working with via that REST service. Properties describe the attributes that are used by the resource you are accessing.
- Click Admin to go to the Admin Home Page.
-
Click Interface Catalogs under Integration Platform.
The Interface Catalogs page opens.
Configuration definitions follow a required product hierarchy starting with the product family, then the product line, followed by the model. The Configuration REST definition names use the following format:
config<productFamilyVarName>.<productLineVarName>.<modelVarName>
For example, the Vision | Servers | Ultra Power Solution Package model definition is:
configvison.servers.ultraPowerSolutionPackage
JSON Syntax for CPQ Attributes
Boolean, Date, and Text Attributes
Boolean, Date, and Text attributes are expressed as JSON name-value pairs. Name-value pairs consist of a field name (in double quotes), followed by a colon, and then followed by a value.
Attributes that Accept JSON Name-Value Pairs
| Attribute Type | Descriptions, Examples, and Errors | |
|---|---|---|
| Boolean | Acceptable values for Boolean attributes are: 'true' or 'false' | |
|
Example |
"redundantPowerSupply": true |
|
|
Sample Error |
If an unacceptable value is sent, you will receive the following error: Unrecognized token 'yes': was expecting ('true', 'false' or 'null') |
|
| Date | Ensure that the date complies with the application and user profile information. | |
|
Example |
"dateModified": "01/18/2019" |
|
|
Sample Error |
If the date is not formatted correctly, you will receive the following error: "Attribute dateModified has an invalid payload." |
|
| Text | Enclose text string in double quotes. | |
|
Example |
"enclosure": "Vision Blade 6000 Chassis" |
|
|
Sample Error |
If the text string is not enclosed in quotes, you will receive the following error: Unrecognized token 'Vision': was expecting ('true', 'false' or 'null') |
|
| Float | Float attributes are floating point numbers with decimal values. | |
|
Example |
"duration": 6.5 |
|
|
Sample Error |
If Data Validation is set for the attribute and an invalid value is sent, you will receive the following error: "Invalid value from punchin. Float Attribute must be in the range of 0.0 to 12.0 inclusive. Attempt to set value 25.0 failed." |
|
| Integer | Integer attributes are whole numbers (i.e. numbers without decimal values). | |
|
Example |
"quantity": 4 |
|
|
Sample Error |
If a decimal value is sent, you will receive the following error: "Invalid value from punchin. Value 2.5 for attribute Quantity should be a integer number. |
|
Currency, Single Select Menu, Multi-Select Menu, and Auto Lock Attributes
Currency, Single Select Menu, and Multi-Select Menu attributes are expressed as JSON objects. Attributes that have the Set Type property set to "Set" also require a composite lock mode object to denote the lock status.
Attributes That Require Composite JSON Objects
| Attribute Type | Descriptions, Examples, and Errors | |
|---|---|---|
| Currency | Currency attributes use composite objects that contain "value" and "currency" items. | |
|
Example |
"price": { "value": 3.33, "currency": "USD" } |
|
|
Sample Error |
If you send a currency attribute as a name-value pair, you will receive the following error. "Attribute price has an invalid payload." |
|
| Single Select Menu | Single Select Menu attributes use composite objects that contain "value" and "displayValue" items. | |
|
Example |
"cloudStorage": { "value": "500 GB", "displayValue": "500 GB" } |
|
|
Sample Error |
If you send a Single Select Menu attribute as a name-value pair, you will receive the following error. "Attribute cloudStorage has an invalid payload." |
|
| Multi-Select Menu | Multi-Select Menu attributes use an array of composite objects that contain "value" and "displayValue" items. Even if only one item is selected, the request must be sent as an array. | |
|
Example |
"servicesRequested": { "items": [{ "value": "Network Technician", "displayValue": "Network Technician" }, { "value": "Security Analyst", "displayValue": " Security Analyst" } ] } |
|
|
Sample Error |
If a Multi-Select Menu attribute is not sent as an array item, you will receive the following error: "Attribute servicesRequested has an invalid payload." |
|
| Auto Lock Attributes |
Attributes that have the Set Type property set to "Set" require a composite lock mode object. The lock mode object contains two items:
|
|
|
Example |
"oSLicenses": { "value": 3, "locked": true } |
|
|
Sample Error |
If you send an attribute with lock mode enabled as a name-value pair, you will receive the following error. "Attribute osLicenses has an invalid payload." |
|
To identify attributes that have the Set Type property set to "Set", navigate to the Attributes Administration List page for the applicable model:
Admin > Products > Catalog Definition > Product Families > Product Lines > Models > Attributes
Configuration array attribute values must be set as items under their parent array set. Array set names begin with "_set".
| Configuration Array Sets | |
|---|---|
| Example | The following example shows the JSON format for a Configuration array set attribute with two items. |
|
"_setofficeServices": { "items": [{ "_index": 0, "serviceType": { "value": "Pantry Service", "displayValue": "Pantry Service" }, "startDate": "01/01/2020", "endDate": "01/01/2021" }, { "_index": 1, "serviceType": { "value": "Cleaning Service", "displayValue": "Cleaning Service" }, "startDate": "01/01/2020", "endDate": "02/01/2020" } ] } |
|
| Notes | To return an array set in the response include the childDef criteria in the request. |
|
"criteria": { "childDefs": [{ "name": "_setofficeServices", "queryDef": { "state": true, "offset": 0, "totalResults": true } } ] } |
|
Remove Invalid Attributes from the REST Request
An attribute is considered invalid when it cannot be modified or it does not exist for the current Product Family, Product Line, or Model. When invalid attributes are included in the REST request, the REST call will fail and return an error.
-
When unrecognizable attributes are included in the REST request, the following error is returned:
"Field <attributeVarName> doesn't exist or is not accessible for current user."
-
When uneditable attributes are included in the REST request, the following error is returned:
"Attribute <attributeVarName> cannot be modified."
Remove the following invalid attributes:
- Attributes that are not associated with the current Product Family, Product Line, or Model
- Attributes with syntax errors or misspelled names
- System attributes (i.e. attributes beginning with an underscore,
such as:_bm_model_name,_BM_USER_LOGIN,_configuration_id) -
Read Only, Inactive, or Internal attributes
How to identify Read Only, Inactive, and Internal attributes.To identify Read Only, Inactive, and Internal attributes; navigate to the Attributes Administration List page for the applicable model:
Admin > Products > Catalog Definition > Product Families > Product Lines > Models > Attributes
- Refer to the "Attribute Type" column to identify Read Only attributes
- Refer to the "Status" column to identify Inactive and Internal attributes
Set the "legacyMode" attribute to "true" in order to replicate configuration flow behavior (i.e. rules only execute for attributes that are included in the flow).
{
"cacheInstanceId": "-1",
"legacyMode": true,
"configData": {
...
}
}
Sample Configuration REST API Request
The following sample shows a simple Configuration REST request.
{
"cacheInstanceId": "-1",
"legacyMode": true,
"configData": {
"enclosure": "Vision Blade 6000 Chassis",
"powerSupply": {
"value": "600W PSU",
"displayValue": "600W PSU"
},
"oSLicenses": {
"value": 3,
"locked": true
}
}
}
To view a more detailed request, refer to the Configure a Model REST API examples.
Notes
Make sure there are not any pending attribute changes before invoking any transaction actions (e.g. _addToTxn, _cm_{processVarName}, _save etc.). Pending attribute changes can occur when an attribute change invokes Recommended Items or BOM Mapping rules that change the items list.
