How to configure a custom e-commerce connector

The Commerce integration framework provides out-of-the-box connectors to commercetools, Adobe Commerce (formerly Magento), Salesforce Commerce Cloud and SAP Commerce Cloud. If you use another third-party e-commerce solution, you can configure your own connector.

Prerequisites

We assume you are familiar with Magnolia, Maven and Java.

Before configuring the connector, make sure you have:

A running instance of Magnolia with the Commerce integration framework.
Access to your e-commerce solution documentation (including the API documentation).
Administrator access to your external e-commerce solution for testing.

Configuration

Complete the steps below to configure your connector.

Create your Maven module

Create your Maven module.

Your Maven module must depend on:

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce</artifactId>
  <version>2.0.1</version> (1)
</dependency>

1	Should you need to specify the module version, do it using `<version>`.

Your module class should implement ModuleLifecycle and close all client providers upon stopping the module. For reference see info.magnolia.ecommerce.magento.EcommerceMagentoModule

Implement the data suppliers and required cart and checkout functionality

Implement DataSuppliers for products and categories:
- info.magnolia.ecommerce.common.Products – check for the required list of suppliers for products.
- info.magnolia.ecommerce.common.Categories – check for the required list of suppliers for categories.
  See info.magnolia.ecommerce.magento.common.MagentoCategory for an example of how to map the JSON received.
Optionally, implement the required functions for the cart: info.magnolia.ecommerce.cart.CartProvider
Optionally, implement the required functions for the checkout process: info.magnolia.ecommerce.checkout.CheckoutProvider
Cart and checkout providers use multi-binding so they must be annotated by @Multibinding and added to the module descriptor as components for injection. For an example, see ecommerce-magento-connector.xml

Implement the provider

Implement the EcommerceClientProvider according to the connection type you want to use to connect to your external e-commerce solution:

RestClientProvider – REST-based client provider. For an example, see info.magnolia.ecommerce.magento.MagentoRestClientProvider and the info.magnolia.ecommerce.magento.client.MagentoHttpClient client implementation based on the org.apache.http package.
3rdPartyClientProvider – External e-commerce SDK-based client provider. This provider differs for each external e-commerce solution.

For an example, see info.magnolia.ecommerce.commercetools.SphereClientProvider.

Define your connector

Using info.magnolia.ecommerce.common.DefaultEcommerceDefinition, create your connector definition configuration file under: <your-module-name>/ecommerces/<definition-name>.yaml.

For an example, see ecommerce-magento-connector/ecommerces/magento.yaml.

Conclusion

To finish:

Install your connector in the Magnolia instance that contains the ecommerce, ecommerce-templating and ecommerce-ui modules.
Set the connection parameters to your external e-commerce solution.

You can then use the default E-commerce app, ecomfn templating functions and E-commerce REST endpoints.