Redirecting legacy URLs to SEO friendly URLs in WebSphere Commerce

Learn how to extend WebSphere® Commerce to automatically redirect legacy URLs to the new SEO friendly URLs that were introduced in WebSphere Commerce Version 7 Feature Pack 3.


Shawn Haywood (, Software Developer, IBM

Photo of Shawn HaywoodShawn Haywood is a Software Developer with the WebSphere Commerce Development team at the IBM Toronto Lab, Canada. He has a wide range of development experience, including storefront, SEO, Management Center, and web services.

Karson Ng (, Software Architect, IBM

Photo of Karson NgKarson Ng is an Architect with the WebSphere Commerce Development team at the IBM Toronto Lab, Canada. His current focus is the development of the Page Composer solution for WebSphere Commerce. He is a subject matter expert on starter stores and search engine optimization features. He has been with IBM for 11 years, most of that time in the Web UI development area. He obtained his Bachelor's Degree in Computer Engineering from the University of Toronto, Canada.

17 October 2012


Search Engine Optimization (SEO) is all about getting increased traffic to your site by ensuring that key product information is easily accessible by search engines. A good SEO strategy improves product and category URLs by removing query parameters and making the URL more human readable. However, changing URLs can lead to broken links or file not found exceptions. To prevent these issues, a 301 redirect is created between your old and new URLs. A 301 redirect occurs when a shopper tries to access a product by using the old URL. The shopper is automatically forwarded to the new URL. When a search engine tries to re-index an old URL, the 301 status alerts the search engine to index the new URL instead.

You can create a 301 redirect between legacy URLs and SEO URLs in different ways. A common method is to set up web server mod rewrite rules in the web server configuration file. This method might require a large number of redirect rules - a rule for each category and product on the site. Usually, it is impossible to create a single redirect rule to handle every redirect to SEO URLs. Another method, demonstrated in this article, is to customize the web application layer to automatically redirect the URLs.

In this article, you learn how to customize WebSphere Commerce to automatically redirect between legacy URLs and SEO friendly URLs while preserving the search engine rankings.

The web application layer is customized to perform additional logic required to find mappings between legacy and SEO URLs.

After completing this article, the system will automatically forward URLs, such as:


To a WebSphere Commerce V7 Feature Pack 3 SEO friendly URLs, such as:


Note the following limitations:

  • Legacy URLs redirect to canonical SEO URLs in a format that does not contain the full hierarchical path.
  • This article does not demonstrate how to simplify the context root. For instructions, see the Shortening the context root of a store URL topic in the WebSphere Commerce Information Center.
  • This article demonstrates how to redirect product and category pages. It does not show how to redirect other content, such as static pages or pages in the checkout flow.


  • WebSphere Commerce V7 Developer is installed.
  • WebSphere Commerce V7 Feature Pack 3 or later is installed.
  • A starter store, which uses the new SEO URLs (Madisons-FEP, or Elite-FEP) for WebSphere Commerce V7 Feature Pack 3, has been published.

Overview of steps

The high-level steps described in this article are:

  • Create a custom SEOURLMapper class to handle additional redirects between legacy and new URLs.
  • Create a query in a query template file that is used by your extended SEOURLMapperclass.
  • Modify the wc-server.xml file to use the custom SEOURLMapper class.

Create a custom SEOURLMapper class

  1. Open your WebSphere Commerce Development environment.
  2. In the Enterprise Explorer view, expand the WebSphereCommerceServerExtensionLogic project.
  3. Right-click src, then click New > Package,
  4. In the Name field, type com.mycompany.commerce.seo.url.helpers, where mycompany is your company prefix.
  5. Click Finish.
  6. Right-click the new package and then click New > Class.
  7. In the Name field, type ExtendedSEOURLMapperImpl, and then click Finish.
  8. Download the code sample file that is provided with this article,, for the extended SEO URL Mapper class.

You have extended the SEO URL Mapper class to redirect the legacy URLs to the canonical form of your new SEO URLs. Look at the javadoc and inline comments in the provided code sample file.

Create a query template file to hold SQL queries

  1. Go to the WC/xml/config directory.
  2. If it does not exist, create a directory named
    1. Right-click config.
    2. Click New > Folder.
    3. In the New Folder dialog, enter the name of
    4. Click Finish.
  3. Right-click the directory you created, then click New > File. The New File dialog opens.
  4. In the Name field, type wc-query-utilties.tpl and click Finish.
  5. Enter the code snippet shown in Listing 1 into the file, then click File > Save.
    Listing 1. Extended Query Template file
    <!-- =======================================================-->
    <!-- This SQL will return the active SEO URL keyword record -->
    <!-- of a catalog entry or catalog group in a specified     -->
    <!-- language and store.                                    -->
    <!-- @param objectId The ID of the catalog entry or catalog -->
    <!-- group.                                                 -->
    <!-- @param langId	The language ID of the keyword.     -->
    <!-- @param storeId	The store ID of the keyword.        -->
    <!-- ====================================================== -->
    			SEOURL.TOKENVALUE = ?objectId?
    			LANGUAGE_ID = ?langId?
    			 STOREENT_ID= ?storeId?
                   STORE_ID = ?storeId? AND STRELTYP_ID = -4)
            	SEOURL.TOKENNAME = ?tokenName?
    			STATUS = 1

You have now created a query file to hold all the SQL statements that the extended SEOURLMapper requires to get information from the database.

Update the server configuration file to use the custom SEOURLMapper class

  1. In WebSphere Commerce Developer, go to the WC\xml\config directory.
  2. Open the wc-server.xml file for editing.
  3. Find the node named SEOConfiguration. Add the following code as a child node under the SEOConfiguration node:
    <mapper-class-name value="com.mycompany.commerce.seo.url.helpers.

    Where mycompany is your company prefix. For example:
    <SEOConfiguration defaultUrl="" dynamicUrl="true" 
        <mapper-class-name value="com.mycompany.commerce.seo.url.helpers.
  4. Save and close the file.
  5. Restart your WebSphere Commerce server.

You have modified the web application to perform additional logic to check for full URL redirects on the storefront.

Test your customization

In this section, you can test that your customization works as expected:

  1. Find a legacy URL to a product or category page. The legacy URL has a format similar to the following example (also see the example shown in Figure 1):

    Figure 1. Store page with the legacy URL
    Store page with the legacy URL
  2. In a web browser, enter the legacy URL.
  3. Observe that the URL is reformatted into the new SEO friendly URL structure, as shown in Figure 2.
    Figure 2. Store page with the redirected SEO URL
    Store page with the redirected SEO URL


In this article, you learned how to create a custom SEOURLMapper class that handles legacy URLs and redirects them to SEO friendly URLs. This way, you can ensure users who have bookmarked your legacy URLs are still be able to link to your products using the new SEO URLs. Also, search engines who have indexed their search results against your legacy URLs will now forward to your new SEO URLs and receive a 301 redirect informing them to re-index.


Code samplecode_sample.zip8KB





developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Commerce on developerWorks

Zone=Commerce, WebSphere
ArticleTitle=Redirecting legacy URLs to SEO friendly URLs in WebSphere Commerce