Administration
Interact parameters can result in less overall delay when using CPQ web services.
The "ajaxSensitive" parameter will prevent state value difference between the client and server. This parameter indicates if an interact request is performed when an attribute is modified.
The "ajaxSensitive" should be set to "true" for the following attribute conditions:
- An attribute is marked auto-update
- An attribute is used in Formulas and AJAX rules
- An attribute is the action attribute of AJAX rules
This parameter supports user cache interaction, which is used for interim state storage for AJAX rule execution. When invoking any action the user can pass in optional parameter called cacheInstanceId. If the cache instance ID is not provided, previous changes to the cached object are ignored and the requested action will process the last saved instance of the transaction.
- When "
cacheInstanceId": "-1" is provided in an action request body, then system will perform the requested action and load the complete transaction into the user's cache. The "cacheInstanceId" value is returned in the response. - In subsequent requests the "
cacheInstanceId": "value" parameter can be used to work with the cached data. -
A cache instance is shared between a Transaction and Transaction Lines. The shared cache will save and reflect updates as a customer navigates between a Transaction and Transaction Line items.
Use Case Examples
- Open transaction 18097326, and load the document into user cache.
URI Endpoint Sample
https://sitename.oracle.com/rest/v17/commerceDocumentsOraclecpqoTransaction/18097326/actions/_open_transactionRequest Body Sample
{"cacheInstanceId": "-1"}Response Sample
"cacheInstanceId": "E9JuyC9QCgTDS9edghTNxRGOVUm34EMR7RJt9alFbkGTN0X5byTjHGRu1CxrSl1p"
- Retrieve cache instance and remove transaction line 8.
URI Endpoint Sample
https://sitename.oracle.com/rest/v17/commerceDocumentsOraclecpqoTransaction/18097326/actions/_remove_transactionLineRequest Body Sample
{ "cacheInstanceId": "E9JuyC9QCgTDS9edghTNxRGOVUm34EMR7RJt9alFbkGTN0X5byTjHGRu1CxrSl1p", "selections": ["transactionLine/8"] }
The cache refresh parameter makes the "cacheInstanceID" parameter of interact service optional, and allows users to invoke the interact service without prior initiation of a cache instance on the server. Additionally, administrators can pass a new parameter, "refreshCache" = true, to reload the current cache and discard the changes.
For example: Assume a customer modifies a few attributes on a Transaction, and then wants to discard these unsaved changes, this service can be used to refresh the page with the saved data. This enhancement would imitate the current Transaction's "Refresh" action behavior, where the Transaction page is reloaded and any of the unsaved changes are discarded.
|
Interact Parameters |
Cache Behavior |
|---|---|
|
cacheInstanceId = "null" |
The response contains saved data and state information as specified by the request. A cache instance is not created. |
|
cacheInstanceId = "-1" |
The response contains saved data and state information as specified by the request and a new cacheInstanceId. A new cache instance is created. |
|
cacheInstanceId is not "-1", and refreshCache = "true" |
The response contains saved data and state information as specified by the request and the cacheInstanceId. The existing cache instance is updated. |
Delta Behavior
When customers take advantage of the delta functionality, they can significantly reduce the response size and processing time by only returning relevant changes. Instead of returning contents for the entire document, the response is limited to components affected by the requested services.
To use the delta functionality with REST API actions, cache must already be initiated and the delta flag in the request set to “true”. When the delta flag is set, the response will only consist of data and state properties that have changed from the cache image as a result of performing the action. Delta is only calculated for the requested criteria. Consumers can take advantage of this functionality by returning only the most relevant changes, which reduces the response size.
Delta functionality for the Run-Time Data REST services will also honor the input payload. If the input is providing a new value for the attribute, then the delta comparison is performed between the input value and the final output value. If there is no input specified for the attribute, then the cache value is used for the comparison.
Since the delta feature interacts with the cache instance, prior initiation of a cache is required to utilize delta functionality. When the delta flag is set to “true”, the response excludes some data and properties that have not changed from the cache instance resulting from the requested action. Delta is only calculated for the requested criteria
Notes:
- The delta response elements are a subset of what was requested. If the request contains criteria to filter the output, delta can only filter it even more. The response will not include changed elements that were filtered by the request criteria.
- To reduce the size of the REST API response, HTML attributes are not returned when the delta input parameter is set to 'true' for Oracle CPQ REST API requests version v9 and above. To retrieve HTML attributes when using these versions, set delta to 'false' or do not include delta in the request.
The following example shows the behavior of delta when there is input and cache involved.
- Apply the state object details on the quote level.
The delta response will consist of information that changed from its previous view in the context of requested criteria. Only the attributes where any of the state properties have changed are included and only the properties that changed are included. -
Apply the state object at the collection level to a particular collection.
-
Apply the default row state to the collection rows.
In the current Commerce REST APIs, the default row state in the majority of use cases is empty. The Commerce implementation does not cause any delta difference in default row, so there is no change in row state. Any information present in the default row state is applied to all the rows of the collection in the response before applying row specific behavior. - Apply the individual row state information.
Any rows that do not have any data change or state change as a part of this request will consist of a placeholder with the id field populated to indicate there is no new change to the row in terms of data and state.
The focus object identifies when a user is editing a specific item and is sent with Interact calls. It lists active collaboration users and specifies if a user has locked the focused item.
The following table describes the server behavior when a request contains the following focus values.
|
Focus Value |
Server Behavior |
|---|---|
|
Attribute Varname |
The server sets the user's focus to the corresponding attribute with a five second timeout. |
|
Empty String |
The server removes the user's focus. |
|
Null |
The server does not modify or remove the user's focus. Clients should avoid sending null focus values. |
