Extension Point Framework Frequently Asked Questions

How do I modify the behaviour of an out-of-the-box extension in the Self Managed Commerce core platform?

An out-of-the-box Extension Point extension is a class in the Self Managed Commerce core that has the @XPFEmbedded annotation and extends XPFExtensionPointImpl.

Let's use EmptyShoppingCartValidatorImpl as an example, which looks like this:

/**
 * Validates that shopping is not empty.
 */
@SuppressWarnings("checkstyle:magicnumber")
@Extension
@XPFEmbedded
@XPFAssignment(extensionPoint = XPFExtensionPointEnum.VALIDATE_SHOPPING_CART_AT_CHECKOUT, priority = 1010)
public class EmptyShoppingCartValidatorImpl extends XPFExtensionPointImpl implements ShoppingCartValidator {

    private static final String MESSAGE_ID = "cart.empty";

    @Override
    public Collection<XPFStructuredErrorMessage> validate(final XPFShoppingCartValidationContext context) {
        if (context.getShoppingCart().getLineItems().isEmpty()) {
            XPFStructuredErrorMessage errorMessage = new XPFStructuredErrorMessage(XPFStructuredErrorMessageType.NEEDINFO, MESSAGE_ID,
                "Shopping cart is empty.", Collections.emptyMap());
            return Collections.singletonList(errorMessage);
        }
        return Collections.emptyList();
    }
}

The @XPFAssignment annotation in the class automatically assigns this extension to the VALIDATE_SHOPPING_CART_AT_CHECKOUT extension point.

Assume that we want to change the "Shopping cart is empty." message to "Shopping cart contains no items.". First, we create a new extension in ext-core that looks like this:

/**
 * Validates that shopping is not empty.
 */
@SuppressWarnings("checkstyle:magicnumber")
@Extension
@XPFEmbedded
@XPFAssignment(extensionPoint = XPFExtensionPointEnum.VALIDATE_SHOPPING_CART_AT_CHECKOUT, priority = 2000)
public class ExtEmptyShoppingCartValidatorImpl extends XPFExtensionPointImpl implements ShoppingCartValidator {

    private static final String MESSAGE_ID = "cart.empty";

    @Override
    public Collection<XPFStructuredErrorMessage> validate(final XPFShoppingCartValidationContext context) {
        if (context.getShoppingCart().getLineItems().isEmpty()) {
            XPFStructuredErrorMessage errorMessage = new XPFStructuredErrorMessage(XPFStructuredErrorMessageType.NEEDINFO, MESSAGE_ID,
                "Shopping cart contains no items.", Collections.emptyMap());
            return Collections.singletonList(errorMessage);
        }
        return Collections.emptyList();
    }
}

You can also optionally extend the out-of-the-box extension class if that's helpful, but usually these classes are very small and easy to re-implement from scratch.

Now if we start Cortex and check the cart order messages, we'll see two messages appear when the cart is empty. One from the EmptyShoppingCartValidatorImpl and the second from the ExtEmptyShoppingCartValidatorImpl. So we need to disable the first one.

To disable the out-of-the-box extension, add an extensions.json file to extensions/plugins/ext-plugin-config/src/main/resources with the following contents:

{
    "extensions": [
        {
            "identifier": {
                "extensionClass": "com.elasticpath.service.shoppingcart.validation.impl.EmptyShoppingCartValidatorImpl",
                "extensionPointKey": "VALIDATE_SHOPPING_CART_AT_CHECKOUT"
            },
            "enabled": false
        }
    ]
}

This overrides the @XPFAssignment annotation on the EmptyShoppingCartValidatorImpl and removes it from the VALIDATE_SHOPPING_CART_AT_CHECKOUT extension point.

How do I ensure that specific External Plugins are available in both local and deployed environments?

Declare plugins as dependencies in the ext-plugin-config module of your ep-commerce source code repository. Any plugins defined there will automatically be loaded into any services started with the local mvn tomcat8:run-war command and included in the Docker images that are built by CloudOps. For more information, see the deploy topic.

How can I load an External Plugin created by Elastic Path or another vendor?

We recommend that all vendors distribute their plugins through a public Nexus server. Ensure that your Elastic Path Commerce Nexus specifies the vendor’s Nexus as a proxy, and then add the plugin dependencies to your ext-plugin-config module as usual. By default, your Nexus should already contain proxy definitions for the Elastic Path public Nexus. For more information, see Maven Repository Manager.

Can I pass config values to External Plugins?

Yes you can; setting values can be passed to both specific plugins and extensions.

What can I do if an Extension Point entity class doesn’t include fields that my extension needs?

All Extension Point entity classes include a getCustomData map that can be used to pass custom field values. You will need to extend the corresponding converter class that populates the entity class so that the map includes the required field values.

What should I do if my customization requires an Extension Point that doesn’t exist?

We plan to continue to add new Extension Points in future versions of the platform. Open a support case to let us know your use case. In the meantime, use the Extension Modules approach.

Can External Plugins persist data in any way?

Currently they cannot, but we have plans to add support for this in future versions of Elastic Path Commerce.

Does the Payment Plugin mechanism use the Extension Point Framework?

Currently Payment Plugins use a different mechanism that is described here. We plan to convert this to use the Extension Point Framework mechanism in a future version of Elastic Path Commerce.

Do I need to download or build Elastic Path Commerce source code to create an External Plugin?

No, you do not. The archetype generation tooling and the Extension Point Framework Connectivity Library are available as released artifacts from the Elastic Path Public Nexus. This means that you can follow our development instructions to get started building External Plugins right away, without the Elastic Path Commerce source code.

However, the current mechanism for integrating External Plugins into deployments and testing them on locally running Elastic Path Commerce services still requires the Elastic Path Commerce source code.