REST API Support for Commerce Transaction Arrays
Overview
Oracle CPQ provides Transaction Array support for Commerce action REST APIs. This section provides information for interaction process flow, size control attributes, and array set row numbers.
Interaction Process Flow
A typical interaction process flow includes open, interact, and modify actions. These actions can impact the array set size and rows within the array set.
Open Action
Open actions are the first step of interacting with a Commerce document. Expansion, selection, pagination, and state items can be specified for array sets when the opening a main or sub-document.
Request Body Sample
{
"cacheInstanceId": "-1",
"criteria": {
"expand": ["lineItem", "fees"],
"fields": ["quoteId", "quoteAmount"],
"childDefs": [{
"name": "lineItem",
"queryDef": {
"fields": ["_part_number", "_price_unit_price_each"]
}
}, {
"name": "fees",
"queryDef": {
"state": true,
"fields": ["feeType", "feeAmount"],
"limit": 20,
"offset": 21
}
}
]
}
}
Sample Response Body
Interact Actions
After a document is opened, auto updates can be used to modify array sets. This is realized by interact actions, which support query, pagination, creation and deletion of array rows, and updates to array attributes. Typically, delta functionality is enabled for interact actions. This reduces the response size and processing time by only returning relevant changes, but customers can also disable delta functionality.
Query and Pagination
Query and pagination requests are performed using an interact call on the parent document.
Request Body Sample
{
"cacheInstanceId": "mu5bm9VnnfwCTnn02bzekMfXUf2ftkxy4UvAWzhZFu2JBevbaEf9cQQDnle21DdY",
"criteria": {
"fields": [],
"childDefs": [{
"name": "fees",
"queryDef": {
"state": true,
"fields": ["feeType", "feeAmount"],
"limit": 20,
"offset": 21
}
}
]
}
}
Insert
Inserting a new row is represented by either of the following:
- a row without a
_row_number field,
- a row whose
_row_number is zero.
Insert One Row Example
In the following example, one row is inserted into the fees array set.
{
"cacheInstanceId": "mu5bm9VnnfwCTnn02bzekMfXUf2ftkxy4UvAWzhZFu2JBevbaEf9cQQDnle21DdY",
"criteria": {
"fields": ["quoteId", "quoteAmount"],
"childDefs": [{
"name": "lineItem",
"queryDef": {
"fields": ["_part_number", "_price_unit_price_each"]
}
}, {
"name": "fees",
"queryDef": {
"state": true,
"fields": ["feeType", "feeAmount"],
"limit": 20,
"offset": 21
}
}
]
}
"delta": true,
"documents": {
"fees": {
"items": [ {
"_row_number": 0,
}
]
}
}
}
The response contains the requested item created with its temporary (negative) _row_number, as well as default values to the attributes if they are set up by the administrator.
{
"documents": {
"fees": {
"items": [{
"_row_number": -5,
"feeType": "One-Time Charge",
"feeAmount": {
"value": 0.0,
"currency": "USD"
}
}
]
}
},
"cacheInstanceId": "mu5bm9VnnfwCTnn02bzekMfXUf2ftkxy4UvAWzhZFu2JBevbaEf9cQQDnle21DdY",
}
Insert Three Rows Example
In the following request fragment, three new rows are inserted into the fees array set:
"documents": {
"fees": {
"items": [
{ },
{
"_row_number": 0,
}, {
"_row_number": 0,
"feeType": "Monthly",
"feeAmount": 10
}
]
}
}
}
Update
To update a row, its row number in the request body must be a number other than zero.
Request Body Sample
In the following request fragment, two rows are to be updated. The row number -1 indicates an ad-hoc row that has not been inserted into the database yet.
"documents": {
"fees": {
"items": [{
"_row_number": -1,
"feeType": "One-Time"
}, {
"_row_number": 5,
"feeType": "One-Time"
}
]
}
}
Delete
“deleteRows” is used to remove rows from an array.
Request Body Sample
{
"deleteRows": ["fees/3", "fees/-1"],
"documents": {
"fees": {
"items": [{
"_row_number": 4,
"feeAmount": {
"value": 30,
"currency": "USD"
}
}
]
}
},
"cacheInstanceId": "mu5bm9VnnfwCTnn02bzekMfXUf2ftkxy4UvAWzhZFu2JBevbaEf9cQQDnle21DdY"
}
Auto Update
An array attribute can trigger auto update. In release 18D, Oracle CPQ only supports auto update from an array attribute against the interact action of their parent document. For example:
- When the interact end point is the main document, main document array attributes can trigger auto update.
- When the interact end point is the sub-document, the sub-document array attributes can trigger auto update.
Note: Array set attributes cannot be added to Line Item Grids.
Trigger Attribute Variable Name Syntax
{arraySetVarName}/{_row_number}/{arrayAttributerVarName}
Request Body Sample
{
"cacheInstanceId": "lvCx8oE7P6DRniQbzeV8vRA0N3GELfLjDX3tTtBZ7SHukU7Q1L0LMdMiGWI1lkVj",
"criteria": {
"state": true,
"fields": [...],
"childDefs": [{
"name": "feeArraySet",
"queryDef": {
"state": true,
"limit": 1,
"offset": 0,
"fields": ["feeType", "feeAmount", "_row_number"]
}
}
]
},
"delta": true,
"documents": {
"feeArraySet": {
"items": [{
"_row_number": 2,
"feeAmount": 100
}
]
}
},
"triggerAttrVarName": "feeArraySet/2/feeAmount"
}
Note: To save changes made using interact actions, a modify type action must be invoked after interact calls and the cacheinstanceId from the interact response must be included in the Modify request body.
- If a Modify action is not invoked, interact call changes will be discarded.
- If the cacheInstanceId from the interact response is not provided in the modify request, the quote is directly loaded from the CPQ database and the interact call changes are overwritten with the last saved version of the quote.
Modify Actions
When a user clicks a button that triggers a modify type action (e.g. Save), the cached instance is saved to the Oracle CPQ database. Expansion, selection, pagination, state, and cache instance items can be specified in the modify action request body. When delta is enabled, only the relevant changes are returned in the REST API response. If delta is disabled the complete documents item is returned.
Note: To save changes made using interact actions, a modify type action must be invoked after interact calls and the cacheinstanceId from the interact response must be included in the Modify request body.
- If a Modify action is not invoked, interact call changes will be discarded.
- If the cacheInstanceId from the interact response is not provided in the modify request, the quote is directly loaded from the CPQ database and the interact call changes are overwritten with the last saved version of the quote.
Request Body Example
{
"cacheInstanceId": "mu5bm9VnnfwCTnn02bzekMfXUf2ftkxy4UvAWzhZFu2JBevbaEf9cQQDnle21DdY",
"criteria": {
"expand": ["lineItem", "fees"],
"fields": ["quoteId", "quoteAmount"],
"childDefs": [{
"name": "lineItem",
"queryDef": {
"fields": ["_part_number", "_price_unit_price_each"]
}
}, {
"name": "fees",
"queryDef": {
"state": true,
"fields": ["feeType", "feeAmount"],
"limit": 20,
"offset": 21
}
}
]
},
"delta": true,
"documents": {
"fees": {
"items": [{
"_row_number": -2,
"feeAmount": {
"value": 30,
"currency": "USD"
}
}, {
"_row_number": 4,
"feeAmount": {
"value": 30,
"currency": "USD"
}
}
]
}
}
}
Array Size REST Service Behavior
When a size control attribute is defined, the array set size can be controlled by either the request payload to create or delete rows or the size control attribute.
Array Set Behavior for REST Service Requests
|
N
|
Y
|
The
array set row count is updated according to the size control attribute. For
deletions, the last rows are removed. For insertions, rows are added at the
end, row numbers are updated accordingly.
Inserting
or deleting rows by changing size control attributes occurs on the server
side during the Modification phase before Formulas are executed.
|
|
Y
|
Y
|
The input value of the size
control attribute is ignored.
- The array set size is modified based on the insert or delete
request.
- The size control attribute is updated after the insertion or
deletion.
This use case occurs when
the end user clicks the Add or Remove button.
The insert or delete request takes priority over the size control attribute.
|
|
Y
|
N
|
The size control attribute
is updated after the insertion or deletion.
|
Size Control Best Practices
- When the array size control attribute is the primary method to change the array size, the Array Set Table Add and Remove buttons should not be exposed.
- When the Array Set Table Add and Remove buttons are enabled, the array size control attribute should not be included on the Transaction UI.
- If the array set size control attribute is a Single Select Menu, the array set size can only be changed by the size control attribute and the Add and Remove buttons for Array Set Table should not be exposed.
Row Number Behavior
Each row in the array set has a non-negative row number. Similar to document numbers, the row numbers must be unique. Once a row is deleted, its row number will not be reused. Web services use delta changes. The row number input may be zero or not present, negative, or positive.
- Zero or no row numbers indicate an insert request. For insert requests, a new row is inserted with a generated negative row number, attributes are defaulted, and then attributes are updated according to the input request.
- Negative row numbers are used to update a row that has not been inserted into the Oracle CPQ database. Negative numbers are only applicable to interact actions or save functions following interact actions. If the negative row number does not exist, the invocation will fail. When a modify action is invoked, negative row numbers are replaced with an actual row number.
- Positive row numbers are only used for update actions. If the positive row does not exist, the invocation will fail.
Notes
Notes:
-
Array sets must be accessed from their parent document REST endpoints.
For example: When a sub-document contains an array set, the sub-document array set must be accessed from sub-document REST endpoints. Manipulation of sub-document array sets from main document REST endpoints is not supported.
- The state information is only returned when the State property is set to "True".
Related Topics
See Also
