E-commerce module

Connector Pack Commerce Connector Pack

License

MLA

Issues

ECOMMERCE

Maven site

ECOMMERCE

Latest

1.3.4

Available on SPA/Headless

Yes

The Magnolia Commerce Connector Pack modules allow you to connect your external e-commerce solution to Magnolia. You can use e-commerce content within Magnolia as if it were native Magnolia content. The modules provide access to shopping cart management and checkout functionality that directly interacts with your e-commerce solution via REST.

Module structure

artifactID Description

magnolia-ecommerce-parent

Parent reactor.

     magnolia-ecommerce

Provides the API for the e-commerce add-on.

     magnolia-ecommerce-commercetools-connector

Provides a default implementation to connect to the commercetools e-commerce solution.

     magnolia-ecommerce-magento-connector

Provides a default implementation to connect to the Adobe Commerce (formerly Magento) e-commerce solution.

     magnolia-ecommerce-salesforce-connector

Provides a default implementation to connect to the Salesforce Commerce Cloud e-commerce solution.

     magnolia-ecommerce-sap-connector

Provides a default implementation to connect to the SAP Commerce Cloud e-commerce solution (formerly Hybris)

     magnolia-ecommerce-templating

Provides the ecomfn templating functions.

     magnolia-ecommerce-ui

Provides the E-commerce app.

     magnolia-ecommerce-decoration

Provides app actions and enables text classification and image recognition through decoration.

Installing

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-ui</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-commercetools-connector</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-magento-connector</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-sap-connector</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-salesforce-connector</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-templating</artifactId>
  <version>1.3.4</version>
</dependency>
<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-decoration</artifactId>
  <version>1.3.4</version>
</dependency>

Configuration

This section explains how to configure the connection between the E-commerce module and your external e-commerce solution.

You can create or edit the configuration in the JCR or the File System (YAML) under <module-name>/ecommerces/<definition-name>.

Before you configure the connection, make sure you know:

  • Which solution you want to connect to. Default implementations are provided for:

    • commercetools

    • Adobe Commerce (formerly Magento)

    • Salesforce Commerce Cloud

    • SAP Commerce Cloud (formerly Hybris)

  • The relevant URLs to connect to your e-commerce solution.

  • Connection credentials for your e-commerce solution.

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

Connection configuration and implementation

You can add your connection configuration to the connections list (see YAML example line 15) or in the JCR under <ecommerce-<your-third-party-solution>-connector>/ecommerces/<definition-name>/connections/<connection-name>.

If you do not want the connection definition to appear in any of the subapps, set the enabled property (YAML line 3) to false.

Note that you can write your own implementation (YAML lines 4-14) or in the JCR under <module-name>/ecommerces/<definition-name>/implementation to suit your requirements, for example, to use additional features such as cross- and up-selling or custom features such as your own checkout solution.

Select the tab for your third-party e-commerce solution below. The connection properties vary.

  • commercetools

  • Adobe Commerce

  • Salesforce Commerce Cloud

  • SAP Commerce Cloud

/ecommerce-commercetools-connector/ecommerces/commercetools.yaml
class: info.magnolia.ecommerce.common.EcommerceDefinition
type: commercetools
enabled: true
implementation:
  products:
    all: info.magnolia.ecommerce.commercetools.products.All
    byId: info.magnolia.ecommerce.commercetools.products.ById
    byCategoryId: info.magnolia.ecommerce.commercetools.products.ByCategoryId
    searchByText: info.magnolia.ecommerce.commercetools.products.SearchByText
  categories:
    all: info.magnolia.ecommerce.commercetools.categories.All
    byId: info.magnolia.ecommerce.commercetools.categories.ById
    byParentCategoryId: info.magnolia.ecommerce.commercetools.categories.ByParentCategoryId
    byProductId: info.magnolia.ecommerce.commercetools.categories.ByProductId
  connectionValidator: info.magnolia.ecommerce.commercetools.common.CommercetoolsConnectionValidator
connections:
  connectionName:
    enabled: false
    authUrl: https://auth.europe-west1.gcp.commercetools.com
    parameters:
      clientId: client_id
      clientSecret: client_secret_or_path_to_password_manager
      apiUrl: https://auth.europe-west1.gcp.commercetools.com
      projectKey: project_key
      locale: en
See the commercetools documentation for instructions about how to create the commercetools API client. For the scopes, we suggest you use View: Categories, Products (all) and Manage: Orders.
Property Description

class

required

info.magnolia.ecommerce.common.EcommerceDefinition

type

required

Your e-commerce solution: commercetools

enabled

required

true or false

connections

     connectionName

         authUrl

required

Authentication URL.

         baseUrl

required

Base URL.

         enabled

required

Shows if the connection is enabled or not: true or false

         parameters

             clientId

required

Username for commercetools.

             clientSecret

required

Client secret for commercetools or the path to the Magnolia password manager.

             apiUrl

required

API URL.

             projectKey

required

The project_key from commercetools.

             locale

optional

The locale used for product/category names or descriptions. Examples:

  • en: ENGLISH

  • fr: FRENCH

  • de: GERMAN

  • it: ITALIAN

  • ja: JAPANESE

  • ko: KOREAN

  • zh: CHINESE

If the locale parameter is configured, then the parameter value is used if it exists in the list of locales from the API. If the value does not exist in the API list, then the first available alternative is returned instead.

If the locale parameter is not configured, then the en locale is used. If the en locale does not exist in the API list, then the first available alternative is returned instead.
/ecommerce-magento-connector/ecommerces/magento.yaml
class: info.magnolia.ecommerce.common.EcommerceDefinition
type: Magento
enabled: true
implementation:
  products:
    all: info.magnolia.ecommerce.magento.products.All
    byId: info.magnolia.ecommerce.magento.products.ById
    byCategoryId: info.magnolia.ecommerce.magento.products.ByCategoryId
    searchByText: info.magnolia.ecommerce.magento.products.SearchByText
  categories:
    all: info.magnolia.ecommerce.magento.categories.All
    byId: info.magnolia.ecommerce.magento.categories.ById
    byParentCategoryId: info.magnolia.ecommerce.magento.categories.ByParentCategoryId
    byProductId: info.magnolia.ecommerce.magento.categories.ByProductId
  connectionValidator: info.magnolia.ecommerce.magento.common.MagentoConnectionValidator
connections:
  connectionName:
    authUrl: http://demo.magento.com
    baseUrl: http://demo.magento.com
    enabled: false
    credentials:
      username: your_username
      password: password_or_path_to_password_manager
Using an Integration access token for Adobe Commerce (formerly Magento)

  1. Request your Integration Access Token from Adobe Commerce as described in the Magento documentation: https://devdocs.magento.com/guides/v2.3/get-started/authentication/gs-authentication-token.html

  2. Copy the Access Token provided by Adobe Commerce.

  3. Configure your connection as follows using your newly-acquired accessToken:

    connections:
  connectionName:
    authUrl: http://demo.magento.com
    baseUrl: http://demo.magento.com
    enabled: true
    parameters:
      accessToken: <your-magento-access-token>
    Property Description

    class

    required

    info.magnolia.ecommerce.common.EcommerceDefinition

    type

    required

    Your e-commerce solution: magento

    enabled

    required

    true or false

    connections

         connectionName

             authUrl

    required

    Authentication URL.

             baseUrl

    required

    Base URL.

             enabled

    required

    Shows if the connection is enabled or not: true or false

             credentials

                 username

    required (unless using Access Token)

    Username for Adobe Commerce (formerly Magento).

                 password (unless using Access Token)

    required

    Password for Adobe Commerce (formerly Magento) or the path to the Magnolia password manager where the password is stored.

             parameters

                 accessToken (unless a username and password is used)

    required

    An access token provided by Adobe Commerce (formerly Magento).
/ecommerce-salesforce-connector/ecommerces/salesforce-commerce.yaml
class: info.magnolia.ecommerce.common.EcommerceDefinition
type: salesforce-commerce
enabled: true
implementation:
  products:
    all: info.magnolia.ecommerce.salesforce.products.All
    byId: info.magnolia.ecommerce.salesforce.products.ById
    byCategoryId: info.magnolia.ecommerce.salesforce.products.ByCategoryId
    searchByText: info.magnolia.ecommerce.salesforce.products.SearchByText
  categories:
    all: info.magnolia.ecommerce.salesforce.categories.All
    byId: info.magnolia.ecommerce.salesforce.categories.ById
    byParentCategoryId: info.magnolia.ecommerce.salesforce.categories.ByParentCategoryId
    byProductId: info.magnolia.ecommerce.salesforce.categories.ByProductId
  connectionValidator: info.magnolia.ecommerce.salesforce.common.SalesforceConnectionValidator
connections:
  connection:
    authUrl: https://account.demandware.com/dw/oauth2/access_token
    baseUrl: https://zzxz-003.sandbox.us01.dx.commercecloud.salesforce.com/s/-/dw/data/v20_10
    enabled: true
    credentials:
      username: client_id
      password: password_or_path_to_password_manager
    parameters:
      shopUrl: /s/RefArchGlobal/dw/shop/v20_10
      siteId: site_id
Property Description

class

required

info.magnolia.ecommerce.common.EcommerceDefinition

type

required

Your e-commerce solution: salesforce-commerce

enabled

required

true or false

connections

     connectionName

         authUrl

required

Authentication URL.

         baseUrl

required

Base URL.

         enabled

required

Shows if the connection is enabled or not: true or false

         credentials

             username

required

Salesforce Commerce Cloud client_id.

The username and password (see below) parameter values are the Salesforce API client_id and password you retrieve from the Salesforce Commerce Cloud Account Manager: https://account.demandware.com/.

First, log into your Salesforce Account Manager (https://account.demandware.com) and go to the API Client tab to create a new API client.

When creating the API client, note that:

  • The password you create for the new API client is used as the password parameter value (see next cell).

  • We recommend you use the Salesforce Commerce API role, client_secret_post Token Endpoint Auth method and JWT Access Token Format.

See Add an API Client in the Salesforce documentation for more information.

Next, log into the Salesforce Business Manager to configure Open Commerce API (OCAPI) client permissions for the API client you created:

  1. Select Administration > Site Development > Open Commerce API Settings. Salesforce Business Manager

  2. Add the API client for both the Shop and Data APIs.

    Shop API configuration example:

    Shop API

    Basic sample sandbox configuration: shop_api.xml

    Data API configuration example:

    Data API

    Basic sample sandbox configuration: data_api.xml

  3. Use the client_id from Salesforce as the username in the Magnolia salesforce-commerce.yaml file.

See "Client Permissions" in the Salesforce documentation for more information.

             password

required

Password entered when creating the Salesforce Commerce Cloud API client (or the path to the Magnolia password manager where the password is stored).

See details in the cell above.

         parameters

             shopUrl

required

URL used for cart and checkout functionality for Salesforce.

             siteId

required

The site_id from Salesforce.

You must enter a valid site_id value for product pricing information to be displayed correctly.

You can set this property to no-site to create a connection to all unassigned Salesforce catalogs.

However, if you do so, note that no price information is displayed in the product detail component for the selected product.
/sap-commerce/ecommerces/sap-commerce.yaml
class: info.magnolia.ecommerce.common.EcommerceDefinition
type: sap-commerce
enabled: true
implementation:
  products:
    all: info.magnolia.ecommerce.sap.products.All
    byId: info.magnolia.ecommerce.sap.products.ById
    byCategoryId: info.magnolia.ecommerce.sap.products.ByCategoryId
    searchByText: info.magnolia.ecommerce.sap.products.SearchByText
  categories:
    all: info.magnolia.ecommerce.sap.categories.All
    byId: info.magnolia.ecommerce.sap.categories.ById
    byParentCategoryId: info.magnolia.ecommerce.sap.categories.ByParentCategoryId
    byProductId: info.magnolia.ecommerce.sap.categories.ByProductId
  connectionValidator: info.magnolia.ecommerce.sap.common.SapConnectionValidator
connections:
  connection:
    name: electronics
    authUrl: https://00.111.222.333:9002/authorizationserver/oauth/token
    baseUrl: https://00.111.222.333:9002/occ/v2
    credentials:
      username: administrator_username
      password: password_or_path_to_password_manager
    parameters:
      clientId: client_id
      clientSecret: client_secret_or_path_to_password_manager
      imagePrefix: https://00.111.222.333:9002
Property Description

class

required

info.magnolia.ecommerce.common.EcommerceDefinition

type

required

Your e-commerce solution: sap-commerce

enabled

required

true or false

connections

     connectionName

         name

required

The name of the connection must match the SAP baseSiteId as described in the SAP documentation.

With the configuration in the example above, we use this URL to get catalogs:

https://00.111.222.333:9002/occ/v2/electronics/catalogs

The baseUrl (see below) is https://00.111.222.333:9002/occ/v2/

electronics is the name of the connection that corresponds to the SAP baseSiteId.

         authUrl

required

Authentication URL.

         baseUrl

required

Base URL.

         enabled

required

Shows if the connection is enabled or not: true or false

         credentials

             username

required

Administrator username for SAP Commerce Cloud.

             password

required

Password for SAP Commerce Cloud or the path to the Magnolia password manager where the password is stored.

         parameters

             clientId

required

Username for SAP Commerce Cloud.

             clientSecret

required

Client secret for SAP Commerce Cloud or the path to the Magnolia password manager.

             imagePrefix

required

The first part of the URL needed to compose the complete URL of images when using the API.

For example

https://00.111.222.333:9002

Viewing and testing connections

This section explains how to view and test the connection between the Magnolia E-commerce add-on module and your external commerce solution using the E-commerce app.

  1. Open the E-commerce app Configuration tab.

  2. Select a connection.

  3. Click View to see the details of your connection to an external e-commerce solution.

    View connection dialog

Depending on your external e-commerce solution, the connection information displayed may be:

  • Definition name – The unique definition name. This name appears in the Catalogs subapp.

  • Connection name – The unique name for the connection configured.

  • E-commerce type – The type of external e-commerce solution you are connected to.

  • Authentication URL – Authentication URL for the solution you are connected to.

  • Base URL – Base URL for the solution you are connected to.

  • Username and Password – Credentials to access the external solution. Passwords or client secrets can be managed in the Passwords app.

  • Connection enabled – Shows if the connection is enabled or not. You may choose to disable the configuration, for example, to improve performance times or to test a connection in one environment before enabling it in another.

Click Test connection to check the connection configuration is correct. A message appears indicating if the test is successful or not.

Once you’ve tested your connection, go to the E-commerce tab. You can see the connections you have configured listed with the catalogs they contain.

Connection configuration validator

The info.magnolia.ecommerce.common.ConnectionValidator interface and its implementations check if a connection configuration is valid.

The connection validation check is executed when you click Test connection.

If the connectionValidator property is not configured, the default info.magnolia.ecommerce.common.DefaultConnectionValidator implementation is used. The default connection validator fallback only checks if the categories are returned by the service. This could give a false negative in some cases where the connection works but no categories exist.

The implementations of info.magnolia.ecommerce.common.ConnectionValidator are configured under: <module-name>/ecommerces/<definition-name>.yaml:

  • Default implementation: info.magnolia.ecommerce.common.DefaultConnectionValidator

    Evaluates the connection configuration as valid if it returns a non-empty list of categories.

  • commercetools: info.magnolia.ecommerce.commercetools.common.CommercetoolsConnectionValidator

    Evaluates the connection configuration as valid if no exceptions are thrown when getting the project.

  • Adobe Commerce (formerly Magento): info.magnolia.ecommerce.magento.common.MagentoConnectionValidator

    Evaluates the connection configuration as valid when a not empty token is returned.

  • Salesforce: info.magnolia.ecommerce.salesforce.common.SalesforceConnectionValidator

    Evaluates the connection configuration as valid when getting catalogs does not throw an exception when connection parameter siteId equals no-site. In other cases, a site with a configured `siteId must be returned.

  • SAP commerce: info.magnolia.ecommerce.sap.common.SapConnectionValidator

    Evaluates the connection configuration as valid when the returned list of BaseSites contains the configured connection name.

For example, this is a snippet of the connection configuration and implementation with the connectionValidator set to the Commercetools implementation:

class: info.magnolia.ecommerce.common.EcommerceDefinition
type: commercetools
enabled: true
implementation:
  products:
    all: info.magnolia.ecommerce.commercetools.products.All
    byId: info.magnolia.ecommerce.commercetools.products.ById
    byCategoryId: info.magnolia.ecommerce.commercetools.products.ByCategoryId
    searchByText: info.magnolia.ecommerce.commercetools.products.SearchByText
  categories:
    all: info.magnolia.ecommerce.commercetools.categories.All
    byId: info.magnolia.ecommerce.commercetools.categories.ById
    byParentCategoryId: info.magnolia.ecommerce.commercetools.categories.ByParentCategoryId
    byProductId: info.magnolia.ecommerce.commercetools.categories.ByProductId
  connectionValidator: info.magnolia.ecommerce.commercetools.common.CommercetoolsConnectionValidator

Configuring the cache

By default, the content pulled from your external e-commerce solution is updated every 300 seconds (5 minutes). You can configure the cache setting via YAML:

resources/ecommerce/config.yaml
cachingDefinition:
  enabled: true
  invalidateInSeconds: 300

Configuring the images displayed in the E-commerce app

Images stored in your third-party e-commerce solution are displayed in the product detail view of the app.

You can configure:

  • If a single image or multiple images are displayed

  • The size of image(s) displayed.

For example:

ecommerce-ui/apps/ecommerce.yaml
    form:
      properties:
        images:
          label: Product image(s)
          $type: multipleImageField
          converterClass: info.magnolia.ecommerce.app.productdetail.field.URLsToStrings
          imageRatio: 60
Property Description

images

required

     label

optional

Field label displayed to editors. The value can be literal or a key of a message bundle.

If you do not provide the property, Magnolia will fall back to a generated i18n key.

If you do not want a label at all, define the property and set its value to a blank space such as label: " " in YAML.

     $type

required

Field type:

  • multipleImageField displays all images for the product (use with URLsToStrings converter).

  • URLImageField displays only the first image for the product (use with ListOfURLsToString converter).

     converterClass

required

info.magnolia.ecommerce.app.productdetail.field.URLsToStrings converts all images for the product. info.magnolia.ecommerce.app.productdetail.field.ListOfURLsToString converts only the first image for the product.

     imageRatio

optional

Defines the ratio of displayed images to the original images in percentage. In the example above, the value 60 is 60% of the original image size.

If the property isn’t set, the images are displayed in their original size.

Configuring chooser dialogs (v1.3+)

You can configure the component definition chooser dialogs introduced in v1.3.

You can find the component configuration under /ecommerce-templating/dialogs/components. There is also a section on chooser dialogs on the Category & Product use cases page.

The components introduced in v1.3 are suffixed with -v3. Those with no suffix are provided for backwards compatibility with E-commerce v1.2.x.

Product chooser dialog

By default, the chooser dialogs have four columns: connector, category, product and preview.

The Connector column is displayed when you have more than one connector correctly configured and enabled.

If you only have one connection enabled or correctly configured with a definitionName and connectionName in /<my-connector>/ecommerces/<my-connector>.yaml then the Connector column is disabled by default, unless you set enableCategorySelection to false.

The Category and Product columns are displayed by default. You can disable them using the enableCategorySelection and enableProductSelection properties under /ecommerce-templating/dialogs/components/<any-v3-component>.yaml.

By default, the system remembers the last selected item in a given chooser dialog. You can use the rememberLastSelectedLocation property to change this.

Property Description

$type

You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.field.FieldType. The proper value is defined by the annotation.

Example class annotation
@FieldType("ecommerceProductLinkField")
public class EcommerceProductLinkFieldDefinition extends EcommerceLinkFieldDefinition {
...
}

See Field types for general values and the ecommercechooser directory for specific e-commerce field types (some examples are given at the end of this section).

enableCategorySelection

optional, default is `true`

Set to false to disable the category, product and preview columns.

The product column depends on the category column, so if enableCategorySelection is false, then any value set for enableProductSelection is overridden.

enableProductSelection

optional, default is `true`

Set to false to disable the product and preview columns.

rememberLastSelectedLocation

optional, default is `true`

When set to true, the system remembers the last item selected and positions a returning user on it when they reopen the same chooser dialog.

When set to false, nothing is preselected in the chooser dialogs.

Each type of e-commerce chooser dialog has its own last selected location. For example, the Product Detail component dialog does not share its last selected location with the Product Teaser component dialog and vice versa.

When the Pages app is closed, all remembered locations are removed.

Configuring text classification and image recognition for e-commerce content

If you have configured them, both Image Recognition and Text Classification are enabled for your e-commerce content.

To trigger the tagging operation, select a product and click Tag product in the E-commerce app action bar. You can view the tags generated in the ecommerce workspace in JCR Browser app (system properties view) or in the Tags app. You can search for products based on the tags in the Find Bar.

Default configuration:

ecommerce-decoration/config.yaml
imageRecogniserEnabled: true
textClassifierEnabled: true
autoRecognitionEnabled: false
Property Description

imageRecogniserEnabled

required, default is true

Enables image recognition functionality for e-commerce content.

Disable this functionality by setting the property to false.

textClassifierEnabled

required, default is true

Enables text classification functionality for e-commerce content.

Disable this functionality by setting the property to false.

autoRecognitionEnabled

required, default is false

Enables automatic tagging.

You can enable automatic tagging by setting the autoRecognitionEnabled property to true.

This action starts when the user opens a product list and may take a long time to execute.

Release history

E-commerce module 1.3.4

Released on March 21, 2023.

This release brings some important bug fixes.

E-commerce module 1.3.3

Released on May 2, 2022.

This release significantly improves seeing which products are selected when adding e-commerce content to a page and introduces two new fields for product choosers.

This release is only compatible with Magnolia 6.2.18.

Improvements

  • ECOMMERCE-477

    • Display JSON in text fields of e-commerce meaningfully. The new implementation displays a product’s name and SKU or the category path for categories.

      See for yourself!

      Adding e-commerce content

    • Two new fields ecommerceProductLinkField and ecommerceProductListLinkField extend ecommerceLinkField. See here for a full list of choosers and the E-commerce module documentation for more information on configuring chooser dialogs.

      • product-detail-v3.yaml

        form:
  properties:
    productDetail:
      $type: ecommerceProductLinkField

        See what it looks like…​

        E-commerce product detail

      • product-teaser-v3.yaml

        form:
  properties:
    productTeaser:
      $type: ecommerceProductLinkField

      • product-list-v3.yaml

        form:
  properties:
    productList:
      $type: ecommerceProductListLinkField

        See what it looks like…​

        E-commerce product detail

E-commerce module 1.3.2

Released on March 28, 2022.

This release brings a number of improvements as well as bug and security fixes.

Endpoint/API updates and improvements

Where can I update the endpoint?

In the Resource Files app, you can find the endpoint in the commercetools.yaml file.

commercetools YAML file

In particular, you need to update authUrl and apiUrl to the endpoint given below.

/ecommerce-commercetools-connector/ecommerces/commercetools.yaml
class: info.magnolia.ecommerce.common.EcommerceDefinition
type: commercetools
enabled: true
implementation:
  products:
    all: info.magnolia.ecommerce.commercetools.products.All
    byId: info.magnolia.ecommerce.commercetools.products.ById
    byCategoryId: info.magnolia.ecommerce.commercetools.products.ByCategoryId
    searchByText: info.magnolia.ecommerce.commercetools.products.SearchByText
  categories:
    all: info.magnolia.ecommerce.commercetools.categories.All
    byId: info.magnolia.ecommerce.commercetools.categories.ById
    byParentCategoryId: info.magnolia.ecommerce.commercetools.categories.ByParentCategoryId
    byProductId: info.magnolia.ecommerce.commercetools.categories.ByProductId
  connectionValidator: info.magnolia.ecommerce.commercetools.common.CommercetoolsConnectionValidator
connections:
  connectionName:
    enabled: false
    authUrl: https://auth.europe-west1.gcp.commercetools.com
    parameters:
      clientId: client_id
      clientSecret: client_secret_or_path_to_password_manager
      apiUrl: https://auth.europe-west1.gcp.commercetools.com
      projectKey: project_key
      locale: en

New SAP security and timeouts

  • ECOMMERCE-492 You must use the SAP Application Interface Key (AIR) for any API call to an SAP system since the end of 2021.

  • ECOMMERCE-495 You can adjust the connection timeout if required using the variables connectionTimeoutInSeconds and readTimeoutInSeconds.

Product selection enhancements

  • ECOMMERCE-476 Product chooser default width widened to show all columns optimally.

  • ECOMMERCE-508 Error when selecting a product.

Other fixes and improvements

  • ECOMMERCE-464 Salesforce seems to lose connection from time to time.

  • ECOMMERCE-488 Manage netty version in core BOMs.

  • ECOMMERCE-502 Should not see trace logs from the commercetools client.

  • ECOMMERCE-510 Commercetools: getShippingMethods throws RestExceptionMapper error.

E-commerce module 1.3.1

Released on October 6, 2021.

This release brings a number of improvements.

New ecommerceLinkField field

A new ecommerceLinkField field (extends Link field) has been introduced.

The ecommerceLinkField replaces the ecommerceChooserField, which is deprecated.

Here are the default configurations for the different e-commerce components provided:

/ecommerce-templating/dialogs/components/category-list-v3.yaml
form:
  properties:
    categoryList:
      $type: ecommerceLinkField
      enableCategorySelection: false
/ecommerce-templating/dialogs/components/product-detail-v3.yaml
form:
  properties:
    productDetail:
      $type: ecommerceLinkField
/ecommerce-templating/dialogs/components/product-list-v3.yaml
form:
  properties:
    productList:
      $type: ecommerceLinkField
      enableProductSelection: false
/ecommerce-templating/dialogs/components/product-teaser-v3.yaml
form:
  properties:
    productTeaser:
      $type: ecommerceLinkField

ECOMMERCE-461

New validators

New EcommerceChooserValidator classes have been added to ensure the connection, category and product selected are valid when adding e-commerce content to a page.

(ECOMMERCE-472)

Connection status message display improved

When you test a connection, the result message is now displayed for longer to make it easier to read.

(ECOMMERCE-465)

E-commerce module 1.2.6

Released on October 6, 2021.

This maintenance release:

  • Improves the connection status message: when you test a connection, the result message is now displayed for longer to make it easier to read. (ECOMMERCE-465)

  • Fixes an exception that occurred when selecting a product detail component from the list of previously added products in the dialog. (ECOMMERCE-447)

E-commerce module 1.3

Released on July 21, 2021.

This Magnolia CMS 6.2.9+ compatible release brings improvements and bug fixes:

Intuitive product chooser

A user-friendly product chooser makes finding and selecting categories and products faster and simpler for end users.

Product chooser dialog

Each column provides a filter at the top.

The chooser dialog can also be configured to enable or disable certain columns.

Updated component definitions and template files

You can find component definitions and template files configured under /ecommerce-templating/templates/components.

The components introduced in v1.3 are suffixed with -v3.

Those with no suffix are provided for backwards compatibility with E-commerce v1.2.x.

You can still view and edit the 1.2.x version components but we recommend you recreate your e-commerce pages using the new component definitions to benefit from the new product chooser dialog and other improvements.

E-commerce module 1.2.5

Released on July 21, 2021.

This Magnolia CMS 6.2.2+ compatible maintenance release brings improvements and bug fixes:

Category list and Product list components updated

The sample components Category list and Product list have been aligned with the other e-commerce page components and now provide chooser dialogs for selecting the e-commerce content to be displayed.

The chooser dialogs only store the connectionId property, which consists of {definitionName}/{connectionName} in JCR instead of the previously stored properties definition and connection.

The related template files category-list.ftl and product-list.ftl were adapted accordingly.

To ensure backward compatibility with the previous template files, an ecommerce-freemarker renderer was introduced and configured for the renderType property in the component configuration yaml files:

  • ecommerce-templating/dialogs/components/category-list.yaml

  • ecommerce-templating/dialogs/components/product-list.yaml

The ecommerce-freemarker renderer parses the definition and connection names from the connectionId property and wraps the component content with the definition and connection properties with the parsed values.

(ECOMMERCE-389, ECOMMERCE-389)

commercetools locale configuration in YAML file

A new locale parameter used for product/category names or descriptions can be set in the commercetools configuration.

See the parameter description in the tab for commercetools.

ECOMMERCE-389

See the 1.2.5 changelog for all the changes.

E-commerce module 1.2.4

Released on April 13, 2021.

This release brings full compatibility with Magnolia 6.2.7 as well as some bug and security fixes.

Notable fixes:

See the 1.2.4 changelog for all the changes.

E-commerce module 1.2.3

Released on December 1, 2020.

E-commerce module 1.2.3 is a bug-fixing release.

See the 1.2.3 changelog for all the changes.

E-commerce module 1.2.2

Released on November 30, 2020.

This release brings full compatibility with Magnolia 6.2.5 as well as some bug fixes.

See the 1.2.2 changelog for all the changes.

E-commerce module 1.2.1

Released on September 16, 2020.

This release brings full compatibility with Magnolia 6.2.3 as well as some bug fixes.

See the 1.2.1 changelog for all the changes.

E-commerce module 1.2

Released on August 20, 2020.

SAP Commerce Cloud Connector

This release delivers a new connector for SAP Commerce Cloud (formerly Hybris).

The connector includes a new User endpoint for SAP:

  • /users/{userId}/accessToken — To log in a user and obtain the user’s access token.

  • /users/{userId}/addresses — To handle stored addresses of users.

  • /users/{userId}/paymentMethods — To handle stored payment methods of users.

accessToken
@POST
@Path("/v2/users/{userId}/accessToken")

getUserAddresses
@GET
@Path("/v2/users/{userId}/addresses")

createUserAddress
@POST
@Path("/v2/users/{userId}/addresses")

deleteUserAddress
@DELETE
@Path("/v2/users/{userId}/addresses/{addressId}")

updateUserAddress
@PUT
@Path("/v2/users/{userId}/addresses/{addressId}")

getUserPaymentMethods
@GET
@Path("/v2/users/{userId}/paymentMethods")

updateUserPaymentMethod
@PUT
@Path("/v2/users/{userId}/paymentMethods/{paymentMethodId}")

deleteUserPaymentMethod
@DELETE
@Path("/v2/users/{userId}/paymentMethods/{paymentMethodId}")

See the User REST endpoint page.

Cart and Checkout endpoint updates

This release provides a V2 of two endpoints:

  • Checkout endpoint — In v2, the checkout endpoint sets the address of a cartId to ensure the correct resource is consistently identified. For example, the v1 /checkouts/address/{cartId} becomes in v2 /checkouts/carts/{cartId}/address.

    setAddress
@PUT
@Path("/checkouts/cart/{cartId}/address")

setShippingMethod
@PUT
@Path("/checkouts/cart/{cartId}/shippingmethod")

createOrder
@POST
@Path("/checkouts/cart/{cartId}/order")

getShippingMethods
@POST
@Path("/checkouts/cart/{cartId}/shippingmethods")

  • Cart endpoint — In v2, cartId is a path parameter instead of form parameter in the REST calls. For example the v1 /carts/items becomes in v2 /carts/{cartId}/items. The other parts of the call are unchanged.

    addItem
@POST
@Path("/v2/carts/{cartId}/items")

removeItem
@DELETE
@Path("/v2/carts/{cartId}/items/{itemId}")

updateItemQuantity
@POST
@Path("/v2/carts/{cartId}/items/{itemId}")

The ecommerce-rest-role has been updated to allow the v2 endpoints.

See the V2 endpoint pages.

V1 of the Cart and Checkout endpoints are deprecated from this release on. They will be removed in the next major version of the Commerce Connector Pack.

Product chooser

This release also improves the sample template provided in the Pages app. Magnolia provides a dialog to select the connection, category and product instead of requiring you to manually enter the connection name, definition name and a product ID. If you only have one connection configured, you choose the category and product directly.

List of changes:

See the 1.2.2 changelog for all the changes.

E-commerce module 1.1.1

Released on July 7, 2020.

This release introduces compatibility with Magnolia 6.2.2 and an improvement that means images are displayed instead of the URL now in the E-commerce app (see Configuring the images displayed in the E-commerce app). List of changes:

  • [ECOMMERCE-226] - Prod detail sub-app - image field displays image instead of path

  • [ECOMMERCE-295] - Use i18n keys instead of literals for labels in product detail view

  • [ECOMMERCE-254] - Manual tagging action should tag a product even if the product has a tag already

See the 1.2.1 changelog for all the changes.

E-commerce module 1.1

Released on April 6, 2020.

This release delivers a new connector for Salesforce Commerce.

See the 1.1 changelog for all the changes.

E-commerce module 1.0

Released on July 9, 2019.

Initial release of the Commerce Connector Pack for connecting to e-commerce systems such as Magento and commercetools.

See Commerce Connector Pack for an overview of the functionality provided.

Commerce Connector Pack compatibility

Module version Magnolia CMS version

1.3.3

6.2.18

1.3+

6.2.9+

1.2+

6.2.2+

1.1.1

6.2.2

1.1

6.2

1.0

6.1

A note about connector compatibilty

The third-party versions listed below are the versions Magnolia has developed and tested against. If you don’t see a particular version listed, it simply means that we do not routinely test on it. If you are using another version of the third-party tool and run into compatibility issues, please contact our Support team.
Module version commercetools SDK

7.6.0

Tested against 2.0. The API of version 7.6.0 was adapted for commercetools SDK v2 following the deprecation of SDK v1.

1.0

Tested against 1.51.0
Module version Adobe Commerce (formerly Magento) API

1.0

Tested against V1
Module version Salesforce Commerce API

1.2.4

Tested against v20_10

1.0

Tested against 20.4
Feedback