Extension Point Framework Release Notes

Learn about Extension Point Framework releases.

1.3.2.af519b3d67

Released: June 2024

New in this release

Shopping Cart Events extension point

A new extension point has been added that notifies an extension when shopping cart events occur.

For more information, see Shopping Cart Events extension point.

Shopping Cart Line Item Events extension point

A new extension point has been added that notifies an extension when shopping cart line item events occur.

For more information, see Shopping Cart Item Events extension point

Customer Events extension point

A new extension point has been added that notifies an extension when customer events occur.

For more information, see Customer Events extension point.

Order Release Events extension point

A new extension point has been added that notifies an extension when an order is released and ready to be sent to the fulfillment system.

For more information, see Order Release Events extension point.

Lazy loaded fields are now excluded from all equals, hashcode, and toString methods on XPF entity classes

All lazy loaded fields (those with the @LazyLoaded annotation) are now configured to be excluded from the equals, hashcode, and toString implementations generated by Lombok. This means that lazy loaded fields won't be unintentionally invoked when these methods are called.

Added new convenience method for retrieving a single setting value

Often Extension Point Framework plugins will have single-valued settings that need to be retrieved within the plugin implementation. These setting values are defined in extensions.json or plugins.json.

A lot of boilerplate code can be required to retrieve these setting values because developers need to verify that the setting exists, that the setting value exists, and then retrieve the first value from the collection. Now, this is all taken care of automatically by the new getSingleSettingValue(String settingKey) method on the plugin context. See the following example:

Optional<XPFPluginSettingValue> apiKeySettingValue = SegmentPlugin.getInstance().getContext().getSingleSettingValue("api_key");

Added payment details to order hold strategies context so hold decisions can be made based on payment details

The XPFOrderHoldStrategyContext class now contains a set of XPFPayment objects so order hold strategy extensions can access details about the payment reservations and make decisions about whether to hold the order. A common use case for this is to use fraud score details from the payment gateway to decide if the order should be held for manual review.

As an example, if the payment plugins populate a data field called fraudScore, then an extension class could implement OrderHoldStrategy as follows:

    @Override
    public Optional<XPFOrderHold> evaluate(final XPFOrderHoldStrategyContext context) {
        Optional<Double> fraudScore = context.getPayments().stream()
                .map(xpfPayment -> Double.valueOf(xpfPayment.getPaymentData().get("fraudScore")))
                .findFirst();
        if (fraudScore.isPresent() && fraudScore.get() > FRAUD_THRESHOLD) {
            XPFOrderHold orderHold = new XPFOrderHold();
            orderHold.setHoldDescription("Fraud score of " + fraudScore.get() + " exceeds threshold of " + FRAUD_THRESHOLD);
            return Optional.of(orderHold);
        }
        return Optional.empty();
    }

1.2.0.5079a708c1

Released: September 2023

New in this release

Added OpenID Connect Claims Extractor extension point

A new Extension Point has been added to allow extensions to specify which claims from the Identity Provider should be used to update the customer profile attribute values and customer group values on the registered user record.

Added customData field to all extension point entity and context classes

A new class named XPFEntity has been created and all XPF*Entity and XPF*Context classes now extend this class. This adds a customData map field to all entity and context classes:

@NonNull
private final Map<String, Object> customData = new HashMap<>;

This allows developers to create customizations that can pass data to custom extensions without needing to extend or modify extension point entity and context classes.

Added name field to XPFProductType

This allows extensions to make decisions based on the name of a product type when accessing information about products.

Added customerType field to XPFCustomer

This allows extensions to make decisions based on the type of customer (ACCOUNT, SINGLE_SESSION_USER, REGISTERED_USER).

Fixed broken backwards compatibility in Tax Calculation Extension Point

A non-null taxProviderName was added to the XPFTaxedItems class. Since plugins instantiate this class, this change modified the constructor, which broke existing plugins. The taxProviderName field has been changed to optional to support backwards compatibility.

1.1.0.06b3c0d032

Released: July 2022

New in this release

Added Tax Calculator extension point

A new Extension Point has been added to support tax calculations. This allows project teams or third-party developers to create extensions that provide tax calculation support that can be invoked by Elastic Path Commerce. For more information, see Tax Calculator Extension Point.

Additionally, an external plugin for Avalara AvaTax is now available.

Added Inventory Flow extension point

A new Extension Point has been added to support transactional inventory operations. This allows project teams or third-party developers to create extensions that provide inventory tracking capabilities. For more information, see Inventory Flow Extension Point.

Added Base Price Finder extension point

A new Extension Point has been added to support base price determination. This allows project teams or third-party developers to create extensions that return unit-price tiers for product SKUs. For more information, see Base Price Finder Extension Point.

Allow extensions to throw a business state exception

When an extension or plugin detects a problem that needs to be surfaced, it can throw a Java exception. In Extension Point Framework version 1.0, we provided the XPFPluginRuntimeException for plugins to use. In this version, we’ve also added a XPFPluginInvalidBusinessStateException which should be used if the problem is something that the end-user can resolve. For more information, see Exceptions.

Added helper methods to XPFHttpTagSetContext

The following helper methods have been added to XPFHttpTagSetContext:

• String getUserIdFromRequest(): This returns the current username from the x-ep-user-id header in the request.
• Collection<String> getUserScopesFromRequest(): This returns the specified scopes (store codes) from the x-ep-user-scope and x-ep-user-scopes headers in the request.
• Collection<String> getUserRolesFromRequest(): This returns the specified user roles from the x-ep-user-role and x-ep-user-roles headers in the request.
• Map<String, String> getUserTraitsFromRequest(): This returns the specified traits from the x-ep-user-trait and x-ep-user-traits headers in the request.
• Collection<String> getMultipleValuesHeader(String... headers): This returns all values from the specified headers in the request. This can handle both the situation where the same header is specified multiple times in the request, or a single header with multiple comma-separated values. If multiple headers are specified, the values are merged.
• Map<String, String> getKeyValuePairsHeader(String... headers): This returns a map of values from the specified headers in the request. The header values are expected to be in the form key1=value1,key2=value2,etc. If multiple headers are specified, the values are merged.

Support for lazy loading expensive entity fields

Normally, the entity objects passed to Extension Point methods are fully populated before the method is invoked. However, some entity class values are slow to calculate while at the same time may not be required by the configured extensions. To address this, we’ve added the ability to lazy load certain values when the entity class getter is called by the extension. These methods can be identified by the existence of the @LazyLoaded annotation on the method. For more information, see Lazy-loaded entity fields.

Fixed issues

• Several Extension Point entity classes have getAttributeValueByKey(String key, Locale locale) or getDisplayName(String key) methods, including XPFCustomer, XPFCategory, XPFProduct, and XPFProductSku. These methods had several bugs that have now been addressed:
  • Locale fallback support was missing. Now a fallback algorithm is followed:
    • Lookup the attribute value using the passed locale (i.e. en_US_va).
    • If no value is found, lookup the attribute value using the locale without the variant (i.e. en_US).
    • If no value is found, lookup the attribute value using the locale without the county (i.e. en).
  • If a value could not be found for the specified locale, a NullPointerException was thrown. Now if all the fallbacks fail to find a value, the method correctly returns Optional.empty().
• Added a useful toString implementation to XPFStructuredErrorMessage.