Attribute Basket Cache Exclusion

To increase performance and reduce overhead, you can specify whether product attributes are excluded from the API cache.

When defining product and pricing metadata, product administrators have a goal of maximizing the effectiveness of the application caching infrastructure. To achieve this, a product administrator typically identifies and excludes those attributes that do not affect pricing or configuration validity, because these attributes do not define the minimum unique set of API cache entries. The Attribute Basket Cache exclusion feature provides Product Administrators this ability by selectively excluding basket cache attributes from the context that defines API call uniqueness.

The Attribute Basket Cache exclusion feature reduces the number of possible basket combinations to achieve a minimum set of unique and useful entries. As a result, there is increased likelihood of cache hits and the elimination of additional cache entries that are effectively redundant.

To determine whether a product attribute is excluded from the cache, observe whether Exclude From Basket Cache is checked in the attribute's General Properties.

The Attribute Basket Cache exclusion feature may be used with caching either on the Salesforce platform or on the Digital Commerce Gateway. The operation of the feature is subtly different between configurations. Please review the information below within the context of your deployment choice.

Prior to the Fall '20 release, executing the Basket API, all attribute values (whether updated or not) were saved to a basket and returned in the response.

In contrast, beginning with the Fall '20 release, attributes that are defined as “Excluded” will be ignored in the API request from the standpoint of pricing or configuration. The best practice for application developers is to not populate the excluded attributes in the request. This will reduce the potential for inappropriate re-use of data in the API response.

API Responses:

The behavior of the API response is different depending upon the cache deployment configuration selected.

On Platform Cache:  In this configuration, when a cache hit occurs, the API response will reflect the specific response that triggered the creation of the cache record. The response might include excluded attribute data if it was provided in the initial request. In this situation, all excluded attributes in any API response should be disregarded. Observing the best practice of not providing any excluded attributes in any request alleviates this potential issue.

Digital Commerce Gateway Cache: In this configuration, when a cache hit occurs, the API response will include the “excluded attribute" data mirrored from the current request. Again, the best practice is not to provide excluded data in the request.

In either configuration, any excluded attributes provided will not be saved to the basket.

Management of "Excluded Attribute" data for UI Application Use:

If your implementation requires the UI to display previously entered updated values for “excluded attributes” then note the following:

On Platform Cache: Store the requested updated values outside of the request and then append the values as part of the response.

Digital Commerce Gateway Cache: The best practice is to store the requested updated values outside of the request and then append the values as part of the response. While it is possible to consume the provided excluded attributes from the API response, be aware that this will increase message size and excluded attributes will not be saved in the basket cache, nor will they trigger the pricing or validation calculations.

The following scenario illustrates an example of how attribute exclusion works and the subtle differences between on- and off-platform usage. Consider a scenario in which an on-platform user initiates a PostConfigure or Basket API call. Suppose a user wishes to purchase a mobile phone, which has three attributes: color, capacity, and IMEI (international mobile equipment identity).

During the product definition phase, the mobile phone was configured using the Enterprise Product Console (EPC) with the color and capacity attributes identified as cacheable, while IMEI was set to non-cacheable. Generally, IMEA is not associated with the device until the mobile phone is provisioned, and is left blank during order capture.

Now suppose a user adds the mobile phone to the basket and configures all three attributes. A cache miss occurs because the attribute values are not contained in the cache.

Here is a step-by-step workflow through the example:

  • User 1 initiates a PostConfigure or Basket API call wanting to purchase a mobile phone that has three attributes:

    • Product: Mobile Phone

      • Attribute 1: Color (Identified as cacheable)

      • Attribute 2: Capacity (Identified as cacheable)

      • Attribute 3: IMEI (Identified as non-cacheable)

  • An API call is made specifying updates to attributes 1, 2, and 3 as shown here:

    • Update Attribute 1: "Black"

    • Update Attribute 2: "64GB"

    • Update Attribute 3: "111111111111111"

  • The result is a cache miss because none of the attributes exist in the cache response object for the request. After the update, the attribute values are as follows:

    • Attribute 1: "Black"

    • Attribute 2: "64GB"

    • Attribute 3: "111111111111111"

Now consider a second nearly identical API call but this time two of the three attributes are now contained in the cache because of the previous call. Note that in this case attribute 3 is not changed from "111111111111111" to "123456789123456" because "111111111111111" was contained in the cache.

  • User 2: Initiates PostConfigure or Basket API with the following:

    • Product: Mobile Phone

      • Attribute 1 (cacheable)

      • Attribute 2 (cacheable)

      • Attribute 3 (non-cacheable)

  • Request

    • Update attribute 1: "Black"

    • Update attribute 2: "64GB"

    • Update attribute 3: "123456789123456"

  • The result is a cache hit because attribute 1, "Black" and "64GB" exist in the cache. The value for attribute 3 remains the same because the value was stored in the cache from the previous API call.

    • Update attribute 1: "Black"

    • Update attribute 2: "64GB"

    • Update attribute 3: "111111111111111" - Note that the response does not change with the updated value.

Now consider the same scenario as before but run on off-platform. The results are nearly but not quite identical. As before, a user initiates a PostConfigure or Basket API call with one product that has three attributes. Attribute 1 and 2 have been configured as cacheable while attribute 3 is not cacheable:

  • User 1 initiates a PostConfigure or Basket API call with the following:

    • Product: Mobile Phone

      • Attribute 1 (cacheable)

      • Attribute 2 (cacheable)

      • Attribute 3 (non-cacheable)

  • An API call is made specifying updates to all three attributes:

    • Update attribute 1: "Black"

    • Update attribute 2: "64GB"

    • Update attribute 3: "111111111111111"

  • The result is a cache miss because attribute 1, "Black" and attribute 2 "64GB" do not exist in the cache response object for the first request.

    • Update attribute 1: "Black"

    • Update attribute 2: "64GB"

    • Update attribute 3: "111111111111111"

As before, a second nearly identical API call is made but this time attributes 1 and 2 are now contained in the cache because of the previous API call. In this case, however, attribute 3 is updated with the second API call.

  • User 1 initiates a PostConfigure or Basket API call with the following:

    • Product: Mobile Phone

      • Attribute 1 (cacheable)

      • Attribute 2 (cacheable)

      • Attribute 3 (non-cacheable)

  • An API call is made specifying updates to attributes 1 and 2:

    • Update attribute 1: "Black"

    • Update attribute 2: "64GB"

    • Update attribute 3: "123456789123456"

  • The result is a cache miss because attribute 1, "Black" and attribute 2, "64GB" do not exist in the cache response object for the first request. However, attribute 3 is updated.

    • Update attribute 1: "Black"

    • Update attribute 2: "64GB"

    • Update attribute 2: "123456789123456" <-- The responses does change with the updated value.

1 In either configuration, excluded attributes are not saved to the basket. Therefore, best practice is to omit values for non-cacheable attributes during a basket operation; instead, append them after the Salesforce order record is created.