WebSphere Commerce Version

Optimizing your site for search engine optimization (SEO) for WebSphere Commerce Version 7 to Feature Pack 2

You can optimize your site for search engines, using techniques to make your site easier to index by a search engine.

Before you begin

  • Ensure that your JSP pages can use search engine optimization. To facilitate optimization of web page locations that are given more weight by search engines when ranking search results, use the tools described in Updating page content.
  • If you will use the provided Perl scripts to convert dynamic URLs in JSP pages to static URLs, ensure that your target system has Perl version 5.6 or later installed, along with the following Perl modules:
    • HTML::Parser
    • URI::URL
    • XML::XPath
    • File::Find
    • File::Path
    • Cwd


  1. Enable URL mapping.
    1. Open the WebSphere Commerce configuration file.
    2. Ensure that the UrlMapperConfig component is enabled, as shown in the following example:
      <component compClassName="com.ibm.commerce.datatype.UrlMapperConfig" 
           <property UrlMapperFile="mapper/SEOUrlMapper.xml" display="false" />
  2. Deploy the updated WebSphere Commerce configuration file.
  3. Identify the JSP pages that you want the search engine to index. Usually, these are catalog-related pages such as ProductDisplay and CategoryDisplay.
  4. Optional: Create a site map.
    1. Create a subdirectory for the site map pages; for example: workspace_dir\Stores\Web Content\store
    2. Copy each of the JSP pages that you identified in step 4, including any pages contained in them, into the SiteMap subdirectory.
    You can now perform any further optimization, including conversion to static URLs in step 7, on the site map pages in place of the original pages.
  5. Add URL mappings to the URL mapping file.
    1. Open the SEOUrlMapper.xml file. Its location is specified in the WebSphere Commerce configuration file and defaults to the WC_eardir/xml/mapper directory.

    2. If you are using a site map, specify the location of the SiteMapsubdirectory with the subDirectory attribute of the pathInfo_mappings element. For example:
      <pathInfo_mappings separator="_" subDirectory="SiteMap">
      WebSphere Commerce adds the subDir=SiteMap name-value pair, which indicates that the site map JSP pages are located in the SiteMap directory, to the set of properties associated with the current request.
    3. Create or modify a pathInfo_mapping element for each command associated with the JSP pages that you identified in step 4. Typically, these commands are:
      • ProductDisplay
      • CategoryDisplay
      • TopCategoriesDisplay
      • StoreCatalogDisplay
      For example, the ProductDisplay command:
      should map to
      <pathInfo_mappings separator="_" ... >
      <pathInfo_mapping name="product" requestName="ProductDisplay">
              <parameter name="storeId" />
              <parameter name="catalogId" />
              <parameter name="productId" />
              <parameter name="langId" />
    • Use the underscore (_) as a separator. If all your JSP pages use absolute paths when referencing URLs and images, you can use forward slash (/) as a separator. Examples of absolute and relative path are as follows:
      absolute path
      <a href="/webapp/wcs/stores/servlet/CategoryDisplay?storeId=10001 ... >
      relative path
      <a href="CategoryDisplay?storeId=10001 ... >
    • Avoid using reserved URL characters such as &, +, :, ?, and ; when setting your separator. These reserved characters have special meanings and can result in the web server and application server improperly processing these characters.

      While the hexadecimal values of such characters (such as using %3a to represent the : character, etc.) can appear to yield satisfactory initial results, unexpected errors can still occur over additional applications of its same usage. Use the previously mentioned separators when setting your separator.

  6. If you are using a site map, set up separate caching for the site map pages. For each command associated with the JSP pages that you identified in step 4, add a component element with the ID of subDir to the cachespec.xml file of your site. As an example, the portion of the cachespec.xml file that pertains to the TopCategoriesDisplay command should now look as follows:
    <!-- TopCategoriesDisplay?storeId=<storeId>&catalogId=<catalogId> -->
    <component id="" type="pathinfo">
    <component id="storeId" type="parameter">
    <component id="catalogId" type="parameter">
    <component id="subDir" type="parameter">
    <component id="DC_lang" type="attribute">
    <component id="DC_curr" type="attribute">
  7. Convert JSP pages with dynamic URLs to JSP pages with static URLs by using any of the following methods:
    1. URL Mapping Perl Script for standard JSP (urlmapping.pl)

      Prerequisite: Perl application is installed and executable on your machine

      Command syntax
      • perl WC_installdir/samples/urlmapping/bin/urlmapping.pl URL_Mapping_File target_directory starting_directory
      • or
      • perl WC_installdir/samples/urlmapping/bin/urlmapping.pl URL_Mapping_File target_directory file
      The name of the URL Mapping file.
      The directory where the JSP files will be output.
      The name of the directory containing the dynamic JSP files.
      The name of a specific file to convert.

      Command line example:

      URL mapping example:

      Original a:href URL syntax:


      Converted a:href URL syntax:


      Limitations: This script does not handle JSTL or tags generated dynamically by either Java or other scripts such as out.println("<a href=\"AugInterest?aucItemId=<%=aucId%>\">")

    2. URL Mapping Java Application for JSTL (URLMappingConvertor)

      Prerequisite: Java executable is allowed to run in the command prompt window or Unix terminal

      Command syntax:
      java com.ibm.commerce.util.URLMappingConvertor URL_Mapping_File target_directory 
      The name of the URL Mapping file.
      The directory where the JSP files will be output. The JSP files in all subdirectories under this target_directory will also be updated.
      Important: Ensure that the classpath parameter is set. If the classpath parameter is not set, you will get ClassNotFound exceptions. For example:
      java -classpath Enablement-BaseComponentsLogic.jar com.ibm.commerce.util.URLMappingConvertor URL_Mapping_File target_directory

      Command line example:

      java com.ibm.commerce.util.URLMappingConvertor WC_eardir/xml/mapper/SEOUrlMapper.xml SiteMap
      URL mapping example:

      Original <c:url> tag syntax:

           <c:url var="TopCategoriesDisplayURL" value="TopCategoriesDisplay">
              <c:param name="storeId" value="${WCParam.storeId}" />
              <c:param name="catalogId" value="${WCParam.catalogId}" />
              <c:param name="langId" value="${langId}" />
      Converted <c:url> tag syntax:
           <c:url var="TopCategoriesDisplayURL" 
                value="TopCategoriesDisplay_${WCParam.storeId}_${WCParam.catalogId}_${langId}" />


      • Any tags other than <c:param> within <c:url> are ignored. For example:
               <c:url var="ProductDisplayURL" value="ProductDisplay">
                  <c:param name="productId" value="${product.productID}" />
                  <c:param name="langId" value="${langId}" />
                  <c:param name="storeId" value="${WCParam.storeId}" />
                  <c:param name="catalogId" value="${WCParam.catalogId}" />
                  <c:if test="${ !empty WCParam.parent_category_rn }" >
                    <c:param name="parent_category_rn" value="${WCParam.parent_category_rn}" />
                    <c:param name="view" value="imageView" />


                <c:url var="ProductDisplayURL" value="ProductDisplay_${product.productID}_${langId}_${WCParam.storeId}_${WCParam.catalogId}_
                  <c:param name="view" value="imageView" />
      • This script does not handle standard JSP tags or tags generated dynamically by either Java or other scripts. For example:
        out.println("<a href=\"AugInterest?aucItemId=<%=aucId%>\">").
    3. Manually, change the dynamic URLs in JSP pages to static URLs.
  8. If you are using a site map, include a link to the site map starting page from the header, footer, or sidebar.