Redirecting legacy URLs to SEO friendly URLs in WebSphere Commerce


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

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

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