ShowTable of Contents
Introduction
While the e-Commerce benefits are well understood by customers and businesses, there are several market trends influencing customer expectations and the web experiences that companies need to deliver to meet their customers’ demands online.
In a complex business environment, an enterprise needs to have multiple strategies to make its products available to customers. To ensure business success, an enterprise must present many faces to the market, and each face is perceived by customers as a unique site.
Benefits of using WebSphere Portal and WebSphere Commerce together include:
-
Composite presentation of Commerce and non-Commerce services.
-
Personalization of the UI experience using Portal’s personalization engine.
-
Inter Portlet communication to integrate with other vendors’ portlets to deliver a rich user experience.
-
Multi-channel and multi-device enablement by reusing Commerce services rendered through Portlets in other sites and devices.
In this article, you’ll gain an understanding of how you can integrate IBM WebSphere Commerce with IBM WebSphere Portal.
Prerequisites
Before you start, you must have following software installed:
-
WebSphere Portal Server V8.0
-
WebSphere Commerce Server V7.0
-
IBM Rational Application Developer
You should also be familiar with Portlet and Web services development.
IBM WebSphere Commerce can be integrated with IBM WebSphere Portal by using following techniques:
1. Stand alone using Web application integrator (WAI)
2. Integrated through a Portlet container using IBM WebSphere Portal
The appropriate presentation layer should be selected based on the business requirements. For example, if the business processes are represented by WebSphere Commerce business logic and data, then a stand alone, web container based presentation layer might be the appropriate choice. However, if the use case scenarios, for example, require composite presentation of Commerce and non-Commerce services, then it may be appropriate to use WebSphere Portal for the presentation layer.
Stand alone using Web Application Integrator (WAI)
Web Application Integrator for IBM WebSphere Portal is a solution that enables external web applications to be easily integrated with WebSphere Portal. It enables Portal customers to further leverage their investment in Portal by using it to centralize access to external web applications within the enterprise.
Typically, when an external web application is integrated with Portal, two approaches are considered: either write a set of portlets that expose the web application's UI/functionality, or use Portal's web clipper portlet (an iFrame based portlet). WebAppIntegrator (WAI) offers a third approach, and is particularly attractive because:
1. No portlet development is required to implement this integration since it does not use portlets at runtime. Portal administrators, in concert with the internal web application owner, can do this integration.
2. It does not use an iFrame. Consequently, the viewing area of the web application is not constrained in any way (i.e. no iFrame scroll bars). Also, all JavaScript and links within the integrated web application continue to function as expected.
3. Integration is achieved in three simple steps.
WAI integration is achieved by "injecting" Portal navigation markup into the external web application when the web application is rendered. The solution implementation leverages the existing Portal URL page feature and makes use of a new Portal entry point, the WAI theme template, which returns JavaScript that generates Portal page navigation markup (e.g. page tabs, the banner and bread crumbs). This markup is "injected" into an external web application by adding an HTML
The user experience suggests that the user is still within the Portal environment even though they are, in reality, natively browsing the external web application.
To achieve this integration you have to do the following:
Step 1: Download and install WAI Portlet on WebSphere Portal
Determine and download the correct version of the WAI Portlet that should be used with the installed WebSphere Portal. Follow the installation instructions provided with the WAI Portlet to provision it on WebSphere Portal.
Step 2: Create a standard Portal URL page
Figure 1.1 shows how you can create it.

Figure 1.1
Step 3: Use the new Web Application Integrator Portlet to generate an HTML script tag
Figure 1.2 shows how you can create it.
Figure 1.2

Figure 1.3
Step 4: Add the script tag to the WebSphere Commerce store
You will find the Header.jsp file in the following location of your Commerce development environment:
\workspace\Stores\WebContent\\Widgets\Header\Header.jsp
Comment the existing header UI for your store and add script tag generated by the WAI Portlet as shown in Figure 1.4:

Figure 1.4
Make changes in the WebSphere Commerce store to match the color scheme of the portal.
Step 5: Testing the integration
Figure 1.5 shows the resulting integration page
Figure 1.5
In this approach we have successfully integrated WebSphere Commerce with WebSphere Portal but WAI Portlet does not provide a SSO implementation. SSO is required to make user experience more seamless between WebSphere Commerce and WebSphere Portal by challenging user to login only once across the servers.
Integrated through a Portlet container using IBM WebSphere Portal
There are three approaches available for customizing WebSphere Commerce integration through a Portlet container using IBM WebSphere Portal.
1. Using Client Library Style leveraging Commerce MVCPortlets
2. Using Direct Web Services Style leveraging Portal programming techniques
3. Using REST API’s exposed by WebSphere Commerce
Using Client Library Style levaginging Commerce MVCPortlets
The WebSphere Commerce Portlet (MVCPortlet) is a generic implementation of the MVC (Model-View-Control) pattern. MVCPortlets provide out of the box integration via customizable Commerce Portlets. These Portlets can be individually configured to call various web services exposed by WebSphere Commerce.
To achieve this integration you have to do the following:
a. Install MVCPortlet.war on IBM WebSphere Portal, MVCPortlet.war can be found on Commerce development environment in the following location
\portal\MVCPortlet.war as shown in Figure 1.6.

Figure 1.6
b. To create the sample pages locate the CreateSamplePages.xml XMLaccess template script in
\portal\scripts\ folder and update storeId and catalogId parameters to match your store ID and catalog ID respectively.
c. Import the CreateSamplePages.xml XMLAccess script using WebSphere Portal admin console.
d. If you wish to create your own pages you can skip the steps (b), (c) and create the pages yourself. Make sure you add the following two preferences to all the commerce Portlets as depicted in the figure 1.7.
i. .ContextDefault-storeId with the value matching your store ID
ii. .ContextDefault-catalogId with the value matching your catalog ID

Figure 1.7
e. Run WebServiceClientBinding.jacl located in the \portal\scripts\ folder using the command in the following format to update client bindings for the MVCPortlet application.
wp_profile/bin/wsadmin options -f DefineWebServiceClientBinding.jacl parameters
Where its command line options are:
-
conntype SOAP.
-
host hostname where hostname is the fully qualified hostname of the deployment manager.
-
port port where port is the SOAP port of the deployment manager configuration service.
-
user username where username is the WebSphere Application Server administrative user of the deployment manager.
-
password pwd where pwd is the password of this WebSphere Application Server administrative user.
-
Its parameters are:
applicationName
The name of the portlet application EAR.
moduleName
The name of the portlet Web application.
CommerceHostname
The fully qualified hostname of the WebSphere Commerce server.
CommercePort
The port number for the WebSphere Commerce service end points.
Example:
wsadmin.bat -conntype SOAP -host localhost -port 10025 -user wpadmin -password wpassword -f DefineWebServiceClientBinding.jacl MVCPortlet_war MVCPortlet.war localhost 80
Figure 1.8 shows the deployed MVCPortlets Search Portlet on WebSphere Portal page.

Figure 1.8
The list below shows the out of the box WebSphere Commerce Portlet samples:
-
Catalog portlet JSP: The Catalog portlet displays a list of all active sales catalogs.
-
Product portlet JSP: The Product portlet displays product details to customers. From this portlet customers can select items to add to the shopping cart. For each product, the offer price is shown.
-
Search portlet JSP: The search portlet provides customers with the ability to search on a product name and description. The result is shown in the Product portlet.
-
My Order portlet JSP: The My Order (order history) portlet provides customers with the ability to view Order history and Order history details.
-
My Account portlet JSP: The My Account portlet provides customers with the ability to create, change, remove account information
-
My Cart portlet JSP: The My Cart portlet displays the shopping cart details to the user and allows the shopper to check out the order and specify shipping and payment information.
Using Direct Web Services Style leveraging Portal programming techniques
In this approach a portlet can invoke the back-end WebSphere Commerce web services directly.
WebSphere Commerce WSDL files
WebSphere Commerce provides WSDL files to describe its Web services. The WebSphere Commerce WSDL files are located in the following directories:
-
<WC_eardir>/WebServicesRouter.war/component-services/wsdl on Server setup
-
<Toolkit-install-location>/workspace/WebServicesRouter/WebContent/component-services/wsdl on development environment
Figure 1.9 shows WSDL file location on development environment.

Figure 1.9
You can also access the WSDL files through the following URL:
http://host_name:port/webapp/wcs/component/component_name/services/component_nameServices?wsdl
For example, to access the WSDL for Catalog services URL will be http://host_name:port/webapp/wcs/component/catalog/services/CatalogServices?wsdl
You can copy the WSDL and required XSD files to your Portlet project and generate web services client code using Rational Application Developer tools.
Below is the sample SOAP request you need to send to Commerce server to fetch top level categories:

Below is the sample SOAP response you will receive from Commerce server for the above SOAP request.

For further request/response samples for other services you can refer to Infocenter link here.
Using REST API’s exposed by WebSphere Commerce
In this approach a portlet can invoke the back-end WebSphere Commerce REST services directly. WebSphere Commerce REST services are JAX-RS REST services that are built on top of Apache Wink. The implementation classes contain JAX-RS annotations such as @Path, @Produces, @Consumes, @QueryParam, and @PathParam.
Authentication using REST services
Some REST services require authentication. To use these REST services, you must first get authentication data by using one of the three identity services:
-
loginidentity - Uses a user name and password to authenticate a registered user.
-
guestidentity - Creates an identity for a guest user.
-
ltpaidentity - Uses an LTPA token to authenticate a user.
You must send a POST request to one of the REST resources, where the response contains the following data:
{
"WCToken": "xxxxxxxxxxxxxxxxxxx",
"WCTrustedToken": "xxxxxxxxxxxxx",
"personalizationID": "1321550980363-1",
"userId": "2"
}
After successfully obtaining the authentication data, you must pass the WCToken and WCTustedToken in the HTTP header for every request that requires authentication. If a request is sent over HTTP, pass the WCToken in the HTTP header. That is, do not pass the WCTrustedToken in HTTP requests, as it might be shown. However, both WCToken and WCTrustedToken must be sent if a request is sent over HTTPS.
The following snippet is an example for setting the WCToken and WCTrustedToken in the HTTP header:
HttpPost request = new HttpPost(secureUrl);
request.addHeader("Content-Type", "application/json");
request.addHeader("WCToken", wcToken);
request.addHeader("WCTrustedToken", wcTrustedToken);
Get all the top level categories Example:
The following example shows the request / response to get top level categories.
The snippet below shows the sample request to get top level categories
GET /wcs/resources/store/10151/categoryview/@top HTTP/1.1
Host: wcsportal.in.ibm.com
Content-Type: application/json
The snippet below shows the sample response to the above request
HTTP/1.1 200 OK
Content-Type: application/json
{
"CatalogGroupView": [
{
"identifier": "Apparel",
"name": "Apparel",
"productsURL": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/productview\/byCategory\/10001",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/byId\/10001",
"shortDescription": "The latest styles for the entire family.",
"thumbnail": "images\/catalog\/apparel\/Kids_clothing_sm.jpg",
"uniqueID": "10001"
},
{
"identifier": "Electronics",
"name": "Electronics",
"productsURL": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/productview\/byCategory\/10027",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/byId\/10027",
"shortDescription": "Electronics",
"thumbnail": "images\/catalog\/electronics\/tablets.png",
"uniqueID": "10027"
},
{
"identifier": "Grocery",
"name": "Grocery",
"productsURL": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/productview\/byCategory\/10033",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/byId\/10033",
"shortDescription": "Grocery",
"thumbnail": "images\/catalog\/grocery\/dairy.png",
"uniqueID": "10033"
},
{
"identifier": "Health",
"name": "Health",
"productsURL": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/productview\/byCategory\/10038",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/byId\/10038",
"shortDescription": "Health",
"thumbnail": "images\/catalog\/health\/medicine.png",
"uniqueID": "10038"
},
{
"identifier": "Home Furnishings",
"name": "Home & Furnishing",
"productsURL": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/productview\/byCategory\/10041",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/byId\/10041",
"shortDescription": "Home & Furnishing",
"thumbnail": "images\/catalog\/homefurnishings\/appliances.png",
"uniqueID": "10041"
},
{
"identifier": "NewslettersAndMagazines",
"name": "Newsletters & Magazines",
"productsURL": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/productview\/byCategory\/10048",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/byId\/10048",
"shortDescription": "Newsletters & Magazines",
"thumbnail": "images\/catalog\/newslettersmagazines\/magazines.png",
"uniqueID": "10048"
}
],
"MetaData": [
{
"metaData": "1",
"metaKey": "price"
}
],
"recordSetComplete": "true",
"recordSetCount": "6",
"recordSetStartNumber": "0",
"recordSetTotal": "6",
"resourceId": "http:\/\/localhost:80\/wcs\/resources\/store\/10151\/categoryview\/@top",
"resourceName": "categoryview"
}
The code snippet below provides a method to get all the top categories from WebSphere Commerce store with store ID 10151.
private void getCategories(){
DefaultHttpClient httpclient = new DefaultHttpClient();
// REST URL to access top categories from commerce server's store 10151
String url="http://localhost/wcs/resources/store/10151/categoryview/@top";
try {
HttpGet httpget=new HttpGet(url);
HttpResponse clientResponse = httpclient.execute(httpget);
String responseAsString = EntityUtils.toString(clientResponse.getEntity());
JSONObject jsonResponse = new JSONObject(responseAsString);
JSONArray array = jsonResponse.getJSONArray("CatalogGroupView");
int size = array.length();
for(int i=0; i<size; i++){
String message = array.getJSONObject(i).getString("shortDescription");
categories.add(message);
}
} catch (Exception e) {
e.printStackTrace();
}
}
igure 1.10 shows the sample output displayed in a Portlet view.

Figure 1.10
For the list of available REST Services refer Infocenter here.
Limitations when working with the WebSphere Commerce REST API
-
Review the available REST services to ensure the functionality you are implementing is available. For example, promotion codes are not supported by default when using REST services in the CartHandler pre-checkout and checkout flows.
-
REST services are primarily designed to work with the Madisons starter store. REST services are not supported in starter stores that support the B2B direct business model, for example the Elite starter store.
-
REST API handlers rely on WebSphere Commerce search to function correctly. For example, the ProductViewHandler and CategoryViewHandler use search-based catalog navigation. You must enable WebSphere Commerce search, or customize REST services to suit your business requirements when working with these handlers.
-
With FEP 6, Rest services are now supported under store preview if you Enable BOD and REST service preview.
About authors
Neha Bhardwaj works with Global Business Services division of IBM on WebSphere Commerce as an IT Specialist. She has worked for various WCS based solutions for retail industry sector. She involves in Design and Development of the Commerce Solutions. You can reach Neha at nehabhar@in.ibm.com
Sushant Naik is an IBM Master certified IT specialist (Portal and Collaboration) working with Lab services division of India Software Labs. His skills and interests include WebSphere Portal, Web Experience Factory, Lotus® Forms, Lotus® Connections, Lotus Sametime®, Java / JEE and Eclipse development. You can reach him at sushnaik@in.ibm.com