Page tree
Skip to end of metadata
Go to start of metadata

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

artifactIDDescription

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 Magento e-commerce solution.

magnolia-ecommerce-salesforce-connector

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

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

Maven is the easiest way to install the modules. Add the following dependencies to your webapp. All the other necessary dependencies will be brought in automatically:

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce</artifactId>
  <version>1.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-ui</artifactId>
  <version>1.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-commercetools-connector</artifactId>
  <version>1.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-magento-connector</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-salesforce-connector</artifactId>
  <version>1.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-templating</artifactId>
  <version>1.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-decoration</artifactId>
  <version>1.1.1</version>
</dependency>

Configuration

Connecting to an e-commerce solution

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
    • Magento
    • Salesforce Commerce Cloud
  • 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, Magento and Salesforce Commerce Cloud. If you use another third-party e-commerce solution, you can configure your own connector.

commercetools 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-commercetools-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 commercetools 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.

/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
connections:
  connectionName:
    enabled: false
    authUrl: https://demo.commercetools.com
    parameters:
      clientId: client_id
      clientSecret: client_secret_or_path_to_password_manager
      apiUrl: https://demo.commercetools.com
      projectKey: project_key

Magento 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-magento-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 commercetools 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.

resources/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
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 Magento

You can use an Integration Access Token instead of a username and password to connect to Magento.

To do so:

  1. Request your Integration Access Token from Magento 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 Magento.
  3. Configure your connection as follows using your token:
resources/ecommerce-magento-connector/ecommerces/magento.yaml
connections:
  connectionName:
    authUrl: http://demo.magento.com
    baseUrl: http://demo.magento.com
    enabled: true
    parameters:
      accessToken: <your-magento-access-token>

Salesforce Commerce Cloud 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-salesforce-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 Salesforce 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.

resources/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
connections:
  connection2:
    authUrl: https://account.demandware.com/dw/oauth2/access_token
    baseUrl: https://magnolia1-tech-prtnr-eu02-dw.demandware.net/s/-/dw/data/v20_4
    enabled: true
    credentials:
      username: your_username
      password: password_or_path_to_password_manager
    parameters:
      clientId: client_id
      shopUrl: /s/RefArchGlobal/dw/shop/v20_4
      siteId: site_id

Connection configuration properties

These are the properties used to configure a connection to your external e-commerce solution. The properties required vary depending on your external solution (see Required for column in the table below).

PropertyDescriptionRequired for

class

required

info.magnolia.ecommerce.common.EcommerceDefinition

All

type

required

Your e-commerce solution: magento, commercetools or salesforce-commerce

All

enabled

required

true or false

All
connections
All

connectionName


All

authUrl

required

Authentication URL.

All

baseUrl

required

Base URL.

All

enabled

required

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

All

credentials


Magento & Salesforce Commerce Cloud

username

required, unless an access token is used (for Magento)

User name for Magento or Salesforce Commerce Cloud.

Magento & Salesforce Commerce Cloud

password

required, unless an access token is used (for Magento)

Password for Magento or Salesforce Commerce Cloud, or the path to the Magnolia password manager where the password is stored.

Magento & Salesforce Commerce Cloud

parameters


All
clientId

required

User name for commercetools or Salesforce Commerce Cloud.

commercetools & Salesforce Commerce Cloud
clientSecret

required

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

commercetools

apiUrl

required

API URL.

commercetools

projectKey

required

The project_key from commercetools.

commercetools

accessToken

required, unless a username and password is used (for Magento)

An access token provided by Magento.

Magento

shopUrl

required

URL used for cart and checkout functionality for Salesforce.

Salesforce

siteId

required

The site_id from Salesforce.

Set this property to no-site to create a connection to all unassigned Salesforce catalogs.

Salesforce

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.

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 the Test connection button 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.

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 from E-commerce module v1.1.1+.

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
PropertyDescription

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 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
PropertyDescription
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.

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

Release history

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

E-commerce module 1.1

Released on April 6, 2020.

This release delivers a new connector for Salesforce Commerce. 

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 versionMagnolia CMS version
1.1.16.2.2

1.1 

6.2
1.06.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 versioncommercetools SDK
1.0Tested against 1.48.0
Module versionMagento API
1.0Tested against V1
Module versionSalesforce Commerce API
1.0Tested against 20.4