E-commerce module

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

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.0</version>
</dependency>

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

<dependency>
  <groupId>info.magnolia.ecommerce</groupId>
  <artifactId>magnolia-ecommerce-commercetools-connector</artifactId>
  <version>1.0</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-templating</artifactId>
  <version>1.0</version>
</dependency>

• magnolia-ecommerce-ui.jar
• magnolia-ecommerce.jar
• magnolia-ecommerce-magento-connector.jar
• magnolia-ecommerce-commercetools-connector.jar

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
• The relevant URLs to connect to your e-commerce solution.  
• Connection credentials for your e-commerce solution.

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.

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.

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: user_name
      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:

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

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

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). To configure this setting:

1. Open the Configuration app.
2. Go to /modules/ecommerce/config/cachingDefinition.
3. Add the property invalidateInSeconds.
4. Set the value of the property to the number of seconds you require.  

Alternatively, you can configure the cache setting via YAML:

cachingDefinition:
  enabled: true
  invalidateInSeconds: 300