E-commerce module
Connector Pack | Commerce Connector Pack |
---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
1.2.3 |
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 |
---|---|
|
Parent reactor. |
|
Provides the API for the e-commerce add-on. |
|
Provides a default implementation to connect to the commercetools e-commerce solution. |
|
Provides a default implementation to connect to the Magento e-commerce solution. |
|
Provides a default implementation to connect to the Salesforce Commerce Cloud e-commerce solution. |
|
Provides a default implementation to connect to the SAP Commerce Cloud e-commerce solution (formerly Hybris) |
|
Provides the
|
|
Provides the E-commerce app. |
|
Provides app actions and enables text classification and image recognition through decoration. |
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.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-ui</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-commercetools-connector</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-magento-connector</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-sap-connector</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-salesforce-connector</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-templating</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>info.magnolia.ecommerce</groupId>
<artifactId>magnolia-ecommerce-decoration</artifactId>
<version>1.2.3</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
-
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, Magento, 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. |
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
Property | Description |
---|---|
|
required
|
|
required Your e-commerce solution: |
|
required
|
|
|
|
|
|
required Authentication URL. |
|
required Base URL. |
|
required Shows if the connection is enabled or not: |
|
|
|
required User name for commercetools. |
|
required Client secret for commercetools or the path to the Magnolia password manager. |
|
required API URL. |
|
required The |
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
-
-
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
-
Copy the Access Token provided by Magento.
-
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 |
---|---|
|
required
|
|
required Your e-commerce solution: |
|
required
|
|
|
|
|
|
required Authentication URL. |
|
required Base URL. |
|
required Shows if the connection is enabled or not: |
|
|
|
required (unless using Access Token) User name for Magento. |
|
required Password for Magento or the path to the Magnolia password manager where the password is stored. |
|
|
|
required An access token provided by Magento. |
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
Property | Description | ||
---|---|---|---|
|
required
|
||
|
required Your e-commerce solution: |
||
|
required
|
||
|
|||
|
|||
|
required Authentication URL. |
||
|
required Base URL. |
||
|
required Shows if the connection is enabled or not: |
||
|
|||
|
required User name for Salesforce Commerce Cloud. |
||
|
required Password for Salesforce Commerce Cloud or the path to the Magnolia password manager where the password is stored. |
||
|
|||
|
required User name for Salesforce Commerce Cloud. |
||
|
required URL used for cart and checkout functionality for Salesforce. |
||
|
required The
|
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
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 |
---|---|
|
required
|
|
required Your e-commerce solution: |
|
required
|
|
|
|
|
|
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: The
|
|
required Authentication URL. |
|
required Base URL. |
|
required Shows if the connection is enabled or not: |
|
|
|
required Administrator user name for SAP Commerce Cloud. |
|
required Password for SAP Commerce Cloud or the path to the Magnolia password manager where the password is stored. |
|
|
|
required User name for SAP Commerce Cloud. |
|
required Client secret for SAP Commerce Cloud or the path to the Magnolia password manager. |
|
required The first part of the URL needed to compose the complete URL of images when using the API.
|
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.
-
Open the E-commerce app Configuration tab.
-
Select a connection.
-
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
Property | Description |
---|---|
|
required |
|
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 |
|
required Field type:
|
|
required
|
|
optional Defines the ratio of displayed images to the original images in
percentage. In the example above, the value 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
Property | Description | ||
---|---|---|---|
|
required, default is Enables image recognition functionality for e-commerce content. Disable this functionality by setting the property to |
||
|
required, default is Enables text classification functionality for e-commerce content. Disable this functionality by setting the property to |
||
|
required, default is Enables automatic tagging. You can enable automatic tagging by setting the autoRecognitionEnabled
property to
|
Release history
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.
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.
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}")
Note that the documentation for the new User REST endpoint will be available shortly.
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.
Note that the documentation for both v2 endpoints will be updated shortly.
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:
-
[ECOMMERCE-304] - SAP Cloud Commerce connector
-
[ECOMMERCE-310] - Improvements required for SAP (new User endpoint API)
-
[ECOMMERCE-305] - Cart method (v2)
-
[ECOMMERCE-307] - Checkout method (v2)
-
[ECOMMERCE-258] - Create Link field to select products from E-commerce app
-
[ECOMMERCE-318] - Update
ecommerce-rest-role
to allow v2 endpoints
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 version | Magnolia CMS version |
---|---|
1.2.3 |
6.2.5 |
1.2.2 |
6.2.4 |
1.2.1 |
6.2.3 |
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 |
---|---|
1.0 |
Tested against 1.48.0 |
Module version | Magento API |
---|---|
1.0 |
Tested against V1 |
Module version | Salesforce Commerce API |
---|---|
1.0 |
Tested against 20.4 |