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.
Maven is the easiest way to install the module. Add the following dependency to your bundle:.
<dependency> <groupId>info.magnolia.wcs</groupId> <artifactId>websphere-commerce-integration</artifactId> <version>1.2</version> </dependency>
There are two supplementary modules, WebSphere Commerce Theme and WebSphere Commerce Demo, that you can also include. These modules contain reference examples.
<dependency> <groupId>info.magnolia.wcs</groupId> <artifactId>websphere-commerce-theme</artifactId> <version>1.2</version> </dependency>
<dependency> <groupId>info.magnolia.wcs</groupId> <artifactId>websphere-commerce-demo</artifactId> <version>1.2</version> </dependency>
Pre-built jars are also available for download. See Installing a module for help.
You can also download the modules as a war file.
Before uninstalling the module, remove the
/server/filters/cms/loginlogout filter node.
To uninstall a module, remove the module JAR file from the
/WEB-INF/lib folder and restart Magnolia.
However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.
To test a module, use the embedded Derby database and take a backup of your
repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the
repositories folder from the backup. This way you can go back to square one.
We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.
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:
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:
- Adding certificates to the WebSphere trust store (IBM) for details on how to configure and register your certificate on IBM WebSphere Application Server
- Key and Certificate Management Tool (Oracle) for details on how to configure and register your certificates with Oracle JVM used, for example with Tomcat (default Magnolia EE bundle) on Windows, Linux or Mac
Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.
To install a module:
- Stop the application server.
- Copy the module JAR files into the
WEB-INF/libdirectory. The location of this directory depends on the application server.
- Restart the server.
- Go to the AdminCentral URL.
- Start the Web update process.
- Click Start up Magnolia.
Repeat the steps for each author and public instance.
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:
To extend the range of provided REST calls, add new annotated calls using one of the two configured clients (
https). Have a look at the code for more call examples.
WebSphere Commerce Integration app
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.
WebSphere Commerce Integration templates
- WebSphere Commerce Home template is the default store home page template for WebSphere Commerce Integration. The template makes extra page and component templates for the WebSphere Commerce available in appropriate locations. The
storeIdis set in the page properties dialog. This property is used by Product Category/WebSphere Commerce Categories and Product Detail sub templates.
- WebSphere Commerce Categories template is available to enable browsing of all products in selected shop by category.
- Product Detail template inherits all shop details from the parent page. Requires no configuration.
Shows selected product in premium space and size on a page. Available in
main area in STK templates.
- Store and product ID
- Teaser overwrite is available for Title, Description and Image
Teaser to individual products. Available in main area in home, section and article templates.
- Wide view spans
- Narrow view displays in multiple columns.
- Store and product ID
- Target detail page
- Teaser overwrite is available for Title, Description and Image
Individual product teaser designed for
promos area. Available on all STK templates.
- Store Id and product Id of promoted product
- Inheritance of promo component
Category carousel displays teasers to all products in a category. Available in
main areas of STK templates.
- Shop and category ID
- Type of Carousel (slider or switcher)
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
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.
Login Logout form
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.
Shopping cart and checkout
Small Shopping Cart
Displays a summary of the shopping cart with item price and total price in
- Currency formatting
Detailed Shopping Cart
Displays full content of the shopping cart, including taxes and discounts. Allows for full manipulation of the shopping cart content. Starts the checkout process.
- Currency formatting
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.
Creating custom templates
To create custom templates extend the following model classes:
|Provides extending classes access to client service, rest client, authentication handling, store id of connected store and asset provider.|
|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.|
|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 |
|Available for creating components for browsing full or partial content of the shop and traversing the category structure.|
|Encapsulates all operations necessary to display and manipulate the shopping cart.|
Provides the connection between form data and the server during checkout process.
|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:
To obtain product as an
Asset to be used for example to render image of the product, use
providerIdis id obtained from
AbstractWCSModelmodel by calling
assetIdis 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.
Caching and performance
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 Segmentation
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.