Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This module is deprecated. See Deprecations.
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.
Installing
<version/>
in the dependency.<dependency> <groupId>info.magnolia.wcs</groupId> <artifactId>websphere-commerce-integration</artifactId> </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> </dependency>
<dependency> <groupId>info.magnolia.wcs</groupId> <artifactId>websphere-commerce-demo</artifactId> </dependency>
Uninstalling
Before uninstalling the module, remove the /server/filters/cms/wcsLoginLogout
filter node.
Configuring connections
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:
- 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
REST API
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.
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
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.
Pages
- 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
storeId
is 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.
Teasers
Stage
Shows selected product in premium space and size on a page. Available in main
area in STK templates.
Configurable parameters:
- Store and product ID
- Currency
- Highlight
- Teaser overwrite is available for Title, Description and Image
Product Teasers
Teaser to individual products. Available in main area in home, section and article templates.
- Wide view spans
main
andextras
area.
- Narrow view displays in multiple columns.
Configurable parameters:
- Store and product ID
- Target detail page
- Highlight
- Teaser overwrite is available for Title, Description and Image
Promos
Individual product teaser designed for promos
area. Available on all STK templates.
Configurable parameters:
- Store Id and product Id of promoted product
- Highlight
- Inheritance of promo component
Category teasers
Category carousel displays teasers to all products in a category. Available in base
and main
areas of STK templates.
Configurable parameters:
- Shop and category ID
- Headline
- Highlight
- Type of Carousel (slider or switcher)
Forms
Registration form
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 extras
area.
Configurable parameters:
- 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.
Configurable parameters:
- Currency formatting
Checkout form
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
Model classes
To create custom templates extend the following model classes:
Model class | Description |
---|---|
| 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 Asset .See examples below |
| 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:
[#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 fromAbstractWCSModel
model by callingmodel.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.
ID Syntax
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
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.