Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
This documentation is based on the IBM WebSphere Commerce Integration module 1.0. that is compatible with Magnolia 5.3+. This module is available only for users of Magnolia Enterprise Pro edition.
IBM WebSphere Commerce Integration module allows users to connect a WebSphere Commerce store to Magnolia. WebSphere Commerce is popular, enterprise-grade e-commerce platform that offers many back-end integrations, including payment gateways, warehouse management, call center management and more. Visit IBM's WebSphere Commerce site to learn more. Their documentation provides for both for beginners and advanced users of the platform.
You can use store content within a Magnolia website in a manner that resembles working with native Magnolia content. In addition to exposing store content to Magnolia websites, the module provides access to shopping cart management, checkout and payment processing powered by WebSphere Commerce functionality.
There are two supplementary modules, WebSphere Commerce Theme and WebSphere Commerce Demo, that you can also include. These modules contain reference examples.
You can also download the modules as a war file.
Before uninstalling the module, remove the /server/filters/cms/loginlogout
filter node.
WebSphere Commerce Integration is an Enterprise Pro edition module. Once you have installed the module (following the standard instructions referenced below), you need to configure connection details for your WebSphere Commerce installation. Add the location of the server in:
/modules/websphere-commerce-integration/rest-client/wcsHttpsClient/baseUrl
, and/modules/websphere-commerce-integration/config/storeMappings
.To enable HTTPS REST calls you also need to import the WebSphere Commerce server certificate in your ca_cert store and make sure that JVM can access it. Most likely you just need to run keytool -import -alias your-alias -keystore cacerts -file certificate.der
For more details about certificates see:
All communication between Magnolia and WebSphere Commerce is made strictly over the REST API provided by WebSphere Commerce.
Some calls are made over http
, for example retrieval of product categories or product details. All calls dealing with customer data, including the shopping cart content, are made over https
to ensure transport security of the data. Magnolia does notaccess any non-public or deprecated API calls of WebSphere Commerce.
The following calls are utilized by the module:
/store/{storeId}/cart @POST /store/{storeId}/cart/@self @GET /store/{storeId}/cart/@self @PUT /store/{storeId}/cart/@self/applyCheckoutProfile @PUT /store/{storeId}/cart/@self/checkout @POST /store/{storeId}/cart/@self/payment_instruction/ @DELETE /store/{storeId}/cart/@self/payment_instruction/ @GET /store/{storeId}/cart/@self/payment_instruction/ @POST /store/{storeId}/cart/@self/precheckout @PUT /store/{storeId}/cart/@self/shipping_info/ @GET /store/{storeId}/cart/@self/shipping_info/ @GET /store/{storeId}/cart/@self/shipping_info/ @PUT /store/{storeId}/cart/@self/usable_payment_info @GET /store/{storeId}/cart/@self/usable_shipping_info/ @GET /store/{storeId}/cart/shipping_modes @GET /store/{storeId}/cart/{orderId}/lock @POST /store/{storeId}/cart/{orderId}/unlock @POST /store/{storeId}/categoryview/@top @GET /store/{storeId}/categoryview/byId/{categoryId} @GET /store/{storeId}/categoryview/byParentCategory/{parentCategoryId} @GET /store/{storeId}/categoryview/{categoryIdentifier} @GET /store/{storeId}/guestidentity @POST /store/{storeId}/inventoryavailability/{productIds} @GET /store/{storeId}/loginidentity @POST /store/{storeId}/loginidentity/@self @DELETE /store/{storeId}/loginidentity/@self @DELETE /store/{storeId}/person @POST /store/{storeId}/person/@self @GET /store/{storeId}/person/@self @PUT /store/{storeId}/person/@self/checkoutProfile/ @GET /store/{storeId}/person/@self/contact @POST /store/{storeId}/person/@self/contact/ @GET /store/{storeId}/person/@self/contact/{nickName} @DELETE /store/{storeId}/person/@self/contact/{nickName} @PUT /store/{storeId}/price/ @POST /store/{storeId}/productview/byCategory/{categoryId} @GET /store/{storeId}/productview/byId/{productId} @GET /store/{storeId}/productview/byIds @GET
To extend the range of provided REST calls, add new annotated calls using one of the two configured clients (http
or https
). Have a look at the code for more call examples.
The WebSphere Commerce Integration module installs the WebSphere Commerce Integration app that allows users to browse all shops, categories and products. The product information is read-only, since the product-update API is not exposed by WebSphere Commerce. Products cannot be updated within Magnolia.
The module bootstraps a number of templates that integrate seamlessly with existing STK templates. The templates are available in the STK > Template Definitions. The necessary CSS and JavaScript is included in the custom theme.
storeId
is set in the page properties dialog. This property is used by Product Category/WebSphere Commerce Categories and Product Detail sub templates. Shows selected product in premium space and size on a page. Available in main
area in STK templates.
Configurable parameters:
Teaser to individual products. Available in main area in home, section and article templates.
main
and extras
area. Configurable parameters:
Individual product teaser designed for promos
area. Available on all STK templates.
Configurable parameters:
Category carousel displays teasers to all products in a category. Available in base
and main
areas of STK templates.
Configurable parameters:
Registration form page template allows users to register new profile within WebSphere Commerce. All fields in the form are configurable. Fields can be removed, added and reordered as necessary as long as they correspond to fields in WebSphere Commerce.
Profile update form page template allows registered users to update their profile details and includes additional shipping or billing address management. All fields can be configured or reordered as necessary.
This component allows user to log in and out of their profiles within WebSphere Commerce. The form, including labels and target action after clicking Login is fully configurable.
Displays a summary of the shopping cart with item price and total price in extras
area.
Configurable parameters:
Displays full content of the shopping cart, including taxes and discounts. Allows for full manipulation of the shopping cart content. Starts the checkout process.
Configurable parameters:
Set of page templates for guiding users through checkout process as configured in the WebSphere Commerce store. Checkout form is fully configurable and can be customized as necessary, provided mandatory WebSphere Commerce fields (required by WebSphere Commerce store configuration) are not removed.
To create custom templates extend the following model classes:
Model class | Description |
---|---|
info.magnolia.wcs.integration.model.AbstractWCSModel (GIT) | Provides extending classes access to client service, rest client, authentication handling, store id of connected store and asset provider. |
info.magnolia.wcs.integration.model.AbstractProductWCSModel (GIT) | For custom model classes that display product-related information. Provides basic functionality for handing the products, for example to generate links to product detail view, add product to shopping cart etc. |
info.magnolia.wcs.integration.model.ProductDetailModel (GIT) | In addition to the abstract class, this model class provides direct access to various JSON properties of the product and exposes the product itself as a Magnolia Asset .See examples below |
info.magnolia.wcs.integration.model.NavigationModel (GIT) | Available for creating components for browsing full or partial content of the shop and traversing the category structure. |
info.magnolia.wcs.integration.model.ShoppingCartModel (GIT) | Encapsulates all operations necessary to display and manipulate the shopping cart. |
info.magnolia.wcs.integration.model.CheckoutModel (GIT) | Provides the connection between form data and the server during checkout process. |
info.magnolia.wcs.integration.model.AuthenticationModel (GIT) | For all templates manipulating user data. Exposes WebSphere Commerce user data to templates. |
ProductDetailModel
. When communicating with WebSphere Commerce, all data is obtained via REST and made available to templates in JSON format. However, there are few cases for common objects where this integration provides added benefits.
To use an Asset
in the template include following declaration in your template:
[#assign product = model.getProduct()!]
To obtain product as an Asset
to be used for example to render image of the product, use
[#assign target = damfn.getAsset(providerId, assetId)]
providerId
is id obtained from AbstractWCSModel
model by calling model.assetProviderId
.assetId
is id of the product that can be obtained from a previously created product object or is provided from configured instance of the component being rendered.Common properties necessary to render a product in various situations can be assigned and made available to templates by simply including product.inc.ftl
in your template.
The ID syntax supports referencing products, categories and stores, and multiple stores from a singe site. Products in the Chooser dialog are in <product>:<storeId>:<product-or-categoryId>
format, for example, product:10152:10001
. This is the ID that is supplied by all component instances that have a configured product or category chooser dialog. The ID need to be understood and parsed by custom templates and model classes.
Out-of-the-box, Magnolia automatically caches all REST calls made to WebSphere Commerce, provided the response calls contain a cache-expire header with an appropriate time interval describing response as cacheable. All responses without cache headers are assumed to be non-cacheable. Where necessary, a custom cache policy can be configured, in addition to the code provided by the module, by simply including and extra cache filter in the REST client configuration. In multiple Magnolia public instance environments that perform a large number of calls, a custom cache configuration that stores details of calls in distributed memory shared by all public nodes, is one way to improve performance.
The content of shopping cart, user profile details and any completed registration or checkout steps, do not require sticky sessions and clients (end users) are fully transferable between different Magnolia instances during a shopping session. In order to transfer shopping sessions of logged in users, session replication between public instances needs to be enabled.
Websphere-commerce-segments module is available in WebSphere Commerce 1.1. You can download it from our Nexus repository as a jar file or include it in your custom web app by adding following maven dependency to your pom.
<dependency> <groupId>info.magnolia.wcs</groupId> <artifactId>websphere-commerce-segments</artifactId> <version>1.1</version> </dependency>
This module allows you to use customer segments defined in WebSphere Commerce for Magnolia personalization module. You need to provide WebSphere Commerce administrator username/password to be able retrieve segments from WebSphere Commerce. Those have to be added to config:/modules/websphere-commerce-integration/config. You can provide these informations as part of your custom module installation or add them later manually. Use WebSphere Commerce segmentation app to see imported segments. The "Synchronise with WCS" action can be used for getting the new segments from WebSphere Commerce. Normally, the segments are retrieved on module start and added to segment registry. This is not possible if you added the administrator credentials later and you have to use this action manually.
Now you can use segments from WebSphere Commerce and also combine them with JCR segments from segments workspace.