IBM WebSphere Commerce Integration module

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

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

• websphere-commerce-integration.jar
• websphere-commerce-theme.jar
• websphere-commerce-demo.jar

You can also download the modules as a war file.

• websphere-commerce-webapp.war

Uninstalling

Before uninstalling the module, remove the /server/filters/cms/loginlogout 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 and extras 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:

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.

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

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

Resources

• WebSphere Smarter Commerce Home Page

• WebSphere Smarter Commerce Virtual Tour
• WebSphere CommerceI GIT Repository
• WebSphere CommerceI JIRA