Document Properties
Kbid2G8924
Last Modified04-Feb-2020
Added to KB09-Nov-2018
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - URL Rewriting (7.8 - 7.10.3)

1 Introduction

This concept focuses on the URLRewriteHandler, that consumes XML and is extensible utilizing the component framework. There are more handy features like the improved testability, live-reloading and availability of configurable/re-usable rules.

Historically seen, the URLs in Intershop have been fairly long ever since. They contain parameters to specify a locale, a currency, an application, sites or service types, like, for example:

http://www.example.com/INTERSHOP/web/WFS/PrimeTech-PrimeTechSpecials-Site/en_US/-/USD/ViewStandardCatalog-Browse?CategoryDomainName=PrimeTech-Computers&CategoryName=Notebooks (Standard Intershop URL)

Modern SEO concepts require to avoid URLs like this. Instead, they recommend the usage of short, structured and readable URLs. In order to fulfill these requirements, Intershop provides four concepts to handle URLs.

1.1 Glossary

Name

Description

URLRewriteHandler

Allows creating short, readable URLs in an Intershop system

Domain-Splitting

In addition to URL rewriting, you can pre-define default parameters for given host names. For example, the store at www.example.com can be told to use the currency USD and the localization en_US automatically. This way, URL rewriting rules can be much shorter as they contain less parameters. The definitions can be set in global domainsplitting.xml file as well.

 Short Links

Landing pages URLs like http://www.example.com/summer-sale-2012/ are definable via the Commerce Management application. This feature allows one-way links directing to the page of interest.

1.2 References

1.3 URL Anatomy

URLs in Intershop start out with protocol, server name and, optionally, a port. The following parameters, "prefix" and "service type", are set using URL configurations.

http[s]://[server name]:[port]/[prefix]/[service type]/[server group]/[site id]/[locale]/[application id]/[currency]/[action]?[parameters]

Example:

https://www.example.com:443/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/de_DE/-/USD/ViewUserAccount-Start?targetPage=Homepage

2 History

A short overview of the URL Rewrite Handler evolution.

VersionNameDescriptionDocumentation
< 7.4RuleRewriteHandlerRegular expression rules and a host specific domainsplitting configured in properties filessee "URL Handling" documents
< 7.8RuleRewriteHandler + advanced DomainsplittingRegular expression rules and a host+shortpath specific domainsplitting configured in properties filessee "URL Handling" documents
7.8New RewriteRuleHandlerImplComplete rework supports custom rewrite-rule types and configuration in XMLsee "URL Rewriting" documents

Note

Beginning with ICM 7.8 the old regular expressions URLRewriteHandler is deprecated. For migration hints check the URL Rewriting Cookbook.

3 Algorithm

The following diagram illustrates the compacting algorithm performed by the new URLRewriteHandler.

url_rewriting_compact_sequence_diagram

The expand process is displayed in the following:

url_rewriting_expand_sequence_diagram

4 Artifacts

4.1 Domain Splitting

Allow host specific settings for server group, locale, currency, application and site. Via shortpathpattern it is also possible to extract this information from the path. The latter can be done for example by placing the locale inside each URL by using shortpathpattern=/${locale}${path}.

  • Compacting: The domain-splittings are matched from top to bottom (see XML file)
  • Expanding: The domain-splittings are matched from bottom to top (see XML file)

You got only a single host and therefore you want the host name to be a wildcard? Simply specify no host for the relevant domain-splitting.

4.2 XML Definition

The XML configuration files of the domain splittings (named domainsplittings.xml) and the rewrite rules (named urlrewriterules.xml) must be placed in <IS_SHARE>system/config/cluster.

4.2.1 domainsplittings.xml

The schema of domain splitting XML can be found in /staticfiles/definition/domainsplittings.xsd of cartridge bc_urlrewrite. The actual domain-splittings are defined in the file domainsplittings.xml, which is deployed to your application server under /share/system/config/cluster/domainsplittings.xml.

Example of domainsplittings.xml
<?xml version="1.0" encoding="utf-8"?> 
<domainsplittings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <domainsplitting name="example-fallback">
        <!-- matching -->
        <hosts>
            <host>localhost</host>
            <host>127.0.0.1</host>
            <host>www.example.com</host>
        </hosts>
        <shortpathpattern>${path}</shortpathpattern>

		<!-- parameters -->
        <site>inSPIRED-inSPIRED-Site</site>
        <server-group>WFS</server-group>
        <currency>EUR</currency>
        <appurlid>web</appurlid>
        <locale>en_US</locale>
 
		<!-- additional replacements for shortpathpattern parameters -->
		<replacements/>
    </domainsplitting>
    <domainsplitting name="example-DE">
        <!-- matching -->
        <hosts>
            <host>localhost</host>
            <host>127.0.0.1</host>
            <host>www.example.com</host>
        </hosts>
		<!-- Use the same replacement string (de and fr) in the compact element of the replacements -->
		<shortpathpattern>/${locale:(de|fr)}${path}</shortpathpattern>
		<!-- parameters -->
        <site>inSPIRED-inSPIRED-Site</site>
        <server-group>WFS</server-group>
        <currency>EUR</currency>
        <appurlid>web</appurlid>
 
		<!-- additional replacements for shortpathpattern parameters -->
        <replacements>
            <replacement type="locale">
                <compact>de</compact>
                <expand>de_DE</expand>
            </replacement>
            <replacement type="locale">
                <compact>fr</compact>
                <expand>fr_FR</expand>
            </replacement>
        </replacements>
    </domainsplitting>
</domainsplittings>

Note

If using replacement parameters (like (de|fr) for the locale in the example above), be sure to use the same string in the <compact> element of the replacements.

4.2.2 urlrewriterules.xml

The schema of rule configuration XML can be found in /staticfiles/definition/urlrewriterules.xsd of cartridge bc_urlrewrite. The actual rewrite rules are defined in the urlrewriterules.xml. This file is deployed to your application server under /share/system/config/cluster/urlrewriterules.xml.

A rewrite rule is configured within urlrewriterules.xml as a rule element. The attributes type and priority of element rule are mandatory, whereas the attribute name is optional. A rule element can contain the optional child elements sites, appurlids, locales, currenciesserver-groups and configurations. When a rewrite rule is checked for applicability, the elements sites, appurlids, locales, currencies, and server-groups are linked via Boolean AND, whereas the child elements of these elements are linked via Boolean OR.

Example
<rule type="Homepage" priority="100"> 
   <sites> 
     <site>inSPIRED-inTRONICS-Site</site> 
     <site>inSPIRED-inTRONICS_Business-Site</site> 
   </sites> 
   <currencies> 
     <currency>USD</currency> 
     <currency>EUR</currency> 
   </currencies> 
   <configurations> 
     <configuration id="shortPath">/startpage</configuration> 
   </configurations> 
 </rule>

The above rewrite rule is applied if the current site is inSPIRED-inTRONICS-Site or inSPIRED-inTRONICS_Business-Site and the current currency is USD or EUR.

Example of urlrewriterules.xml
<?xml version="1.0" encoding="utf-8"?> 
<rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

	<!-- Homepage rule 
		accepts "", "/" or "<shortPath>"
		performs a redirect to "<shortPath>" 
		-->
	<rule name="Homepage rule" type="Homepage" priority="50">
		<!-- make rules "specific" -->
		<sites>
			<site>inSPIRED-inTRONICS-Site</site>
		</sites>
		<appurlids>
			<appurlid>-</appurlid>
		</appurlids>
		<locales>
			<locale>en_US</locale>
		</locales>
		<currencies>
			<currency>USD</currency>
		</currencies>
		<server-groups>
			<server-group>WFS</server-group>
			<server-group>BOS</server-group>
		</server-groups>
		<!-- configuration section -->
		<configurations>
			<configuration id="shortPath">/startpage_en</configuration>
		</configurations>
	</rule>

	<!-- Category Rule 
		/<category-path>/   (contains trailing slash!)
		-->  
	<rule name="Category Rule" type="Category" priority="40">
		<configurations>
			<configuration id="fullCategoryPath">true</configuration>
			<configuration id="localizedCategoryPath">false</configuration>
		</configurations>
	</rule>

	<!-- Product Rule 
		/<category-path>/<product-name>-zid<sku>
		does redirect if product-name doesn't match
		-->  
	<rule name="Product Rule" type="Product" priority="600">
		<configurations>
			<configuration id="fullCategoryPath">true</configuration>
			<configuration id="localizedCategoryPath">false</configuration>
		</configurations>
	</rule>

	<!-- pipeline rule for cart -->
	<rule name="ViewCart /cart" type="Pipeline" priority="800">
		<configurations>
			<configuration id="startNode">ViewCart-View</configuration>
			<configuration id="shortPath">/cart</configuration>
		</configurations>
	</rule>

    <!-- Sitemap products
    /sitemap-products/<category-path>
        -->
    <rule type="SitemapProducts" priority="100" name="sitemap products">
        <configurations>
            <configuration id="fullCategoryPath">true</configuration>
            <configuration id="localizedCategoryPath">true</configuration>
            <configuration id="shortPath">/sitemap-products</configuration>
        </configurations>
    </rule>    
    
	<!-- page rule for terms-and-conditions -->
	<rule name="Page /terms-and-conditions" type="Page" priority="780">
		<configurations>
			<configuration id="pageletId">systempage.termsAndConditions.pagelet2-Page</configuration>
			<configuration id="shortPath">/terms-and-conditions</configuration>
		</configurations>
	</rule>
 
	<!-- type "PageGeneric" creates /{PageletEntryPoint DisplayName}-cms-${p.PageletEntryPointID} -->
	<rule type="PageGeneric" priority="10" name="page fall-back">
		<configurations>
			<configuration id="uniquePrefix">-cms-</configuration>
		</configurations>
	</rule>
</rules>

4.3 Structure

concept_url_rewrite_handler_class_diagram

5 Rewrite Rules

5.1 Overview

There is an existing set of re-usable, configurable RewriteRules available over the configuration framework.

NamePipelineParametersConfiguration ParametersDescription
HomepageViewHomepage-Start shortPath

Define a starting page for a shop by specifying a shortPath (e.g., /start, / or "")

PipelineAny pipeline identified by configuration parameter "startNode"pipeline

startNode

shortPath

Pipeline node (e.g., startNode) is replaced with a given shortPath
PageViewContent-StartPageletEntryPointID

pageletId

shortPath

The "shortPath" is set, when the pageletId matches.
PageGenericViewContent-StartPageletEntryPointIDuniquePrefixCreates CMS links automatically following the pattern
/<PageletEntryPoint:DisplayName><uniquePrefix><PageletEntryPointID>

Product

ViewProduct-StartSKU

fullCategoryPath

localizedCategoryPath

Creates links with the following pattern /GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362
CategoryViewStandardCatalog-Browse

CatalogID

CategoryName

fullCategoryPath

localizedCategoryPath

All incoming parameters are removed.
RegExparameters depend on select/selectMatch statement (see ${pipeline})parameters depend on select/selectMatch statement (see placeholders with ${p.<param-name>})

select

selectMatch

shortPath

shortPathMatch

longRequest

Compact Rule Definition

# select may contain any placeholder e.g., pipeline, site, servergroup, currency, appurlid, locale
select = ${pipeline}/${p.SearchTerm}/
selectMatch = ^ViewParametricSearch-Browse/.+/$
shortPath = /search/${p.SearchTerm}



// example for compacting
select = ${pipeline}/${p.SearchTerm}/
selectMatch = ^ViewParametricSearch-Browse/.+/$
shortPath = /search/${p.SearchTerm}

Expand Rule definition

# shortPathMatch should match the shortPath above
shortPathMatch = <regular expression>
# longpath may use placeholder $1..$99 referencing the regex-findings
longPath = <pipeline-node>?<parameter>
 
# examples for expanding
shortPathMatch = ^/search/(.+)$
longPath = ViewSearch-Browse?query=$1&tracking=true
-or-
shortPathMatch = ^/contact$
longPath = ViewContact-Start
SitemapProductsViewSitemap-ProductList

CatalogID

CategoryName

shortPath (e.g., "/sitemap-products")

fullCategoryPath

localizedCategoryPath

Creates a product sitemap with a prepended short path

/<shortPath>/<categoryPath>$

ViewDataViewData-Start-shortPath (e.g., "/viewdata", "/cart/de_DE")

A short path usually starting with a slash. This parameter is optional. If no short path is configured, the rule will use "/viewdata" as short path per default. This parameter must not end with a "/".

/<shortPath>

 

5.2 Homepage

A simple rule to rewrite the homepage pipeline ViewHomepage-Start with e.g., "/", "/startpage".

Rule configuration parameter:

Name

Value

Description

shortPath

e.g., "/", "/startpage", ..

A short path usually starting with a slash.

Legacy Rule
rule.home.select = ${action} rule.home.selectMatch = ^ViewHomepage-Start$ rule.home.shortPath = / rule.home.shortPathMatch = ^([\\/]?)$ rule.home.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-Start

5.3 Pipeline

A pipeline rule maps a given pipeline startNode to a fixed shortPath (see configuration parameters). E.g., ViewSitemap-Start maps onto /sitemaps and vice-versa.

Rewrite Rule configuration parameter:

Name

Value

Description

startNode

"ViewSitemap-Start"

The related pipeline name startnode name

shortPath

"/sitemaps"

A short path usually starting with a slash.

5.4 RegEx

Classic regular expression based rules.

Name

Value

Description

Compact

select

e.g., "${action}/${p.parameter}"

use parameters "p.*" or the predefined placeholders: ${action}, ${protocol}, ${locale}, ${currency}

selectMatch

e.g., "^ViewSitemap-Start/.+$"

Regular expression to match against the "select"

shortPath

e.g., "/sitemap${d.deletethisparameter}"

The compacted short path.

Expand

shortPathMatch

e.g., "^/sitemap(.*)$"

Match incoming URL paths for this regular expression.

longRequest

e.g., "ViewSitemap-Start?Appendix=$1"

When matching, tell which pipeline is to open. Use $1,$2,.. to reference the wild card placeholders in shortPathMatch.

References to pipeline dictionary entries (e.g., #ProductBO:DisplayName#) are NOT SUPPORTED anymore. These hidden dependencies were hardly testable and caused confusion.

5.5 Page

Creates a link to a CMS page with pipeline start-node ViewContent-Start. Rewrites URLs that link to a page via pipeline start node "ViewContent-Start".

Compact example:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewContent-Start?PageletEntryPointID=systempage.termsAndConditions.pagelet2-Page
to
http://www.example.com/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/terms-and-conditions

Expand example:

http://www.example.com/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD /terms-and-conditions
to
http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewContent-Start?PageletEntryPointID=systempage.termsAndConditions.pagelet2-Page

Rule configuration parameters:

Name

Value

Description

pageletId

e.g., "systempage.termsAndConditions.pagelet2-Page"

The ID of the pagelet used as query parameter in the URL, e.g., http://.../ViewContent-Start? PageletEntryPointID=  systempage.termsAndConditions.pagelet2-Page.

shortPath

e.g., "/terms-and-conditions"

The short path of the page.

5.6 Page Generic

Rewrites URLs that link to a page via pipeline start node ViewContent-Start. It automatically creates a compacted URL for the given pipeline parameter PageletEntryPointID following the pattern:

PageGeneric compacted URL mapping
 /<PageletEntryPoint:DisplayName><uniquePrefix><PageletEntryPointID>

Compact example:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/de_DE/-/EUR/ViewContent-Start?PageletEntryPointID=page.checkout
to
http://www.example.com/WFS/inSPIRED-inTRONICS-Site/de_DE/-/EUR/Kasse-Seiten-cms-page.checkout

Expand example:

http://www.example.com/WFS/inSPIRED-inTRONICS-Site/de_DE/-/EUR /Kasse-Seiten-cms-page.checkout
to
http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/de_DE/-/EUR/ViewContent-Start?PageletEntryPointID=page.checkout


This rewrite rule will use the pagelet entry point's display name, if it is defined for the given locale, or the pagelet entry point ID for.

The configuration parameter uniquePrefix is used to separate the readable name and the pagelet ID.

Name

Value

Description

uniquePrefix

e.g., "-cms-"

A string used as a separator of the CMS pagelet entry point's name and its ID.

5.7 Product

This rewrite rule rewrites URLs for product detail page with the pipeline start-node ViewProduct-Start.

The only context parameter needed for compacting is the "SKU". The following legacy parameters CategoryName, CatalogID, CategoryID and CategoryDomainName are removed from compacted URLs.

The rewrite rule creates short paths following the pattern: /<ProductBO:Name>-zid<SKU>. The string -zid marks the beginning of the SKU.

Compact example:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewProduct-Start?SKU=M8182790134362
to
http://www.example.com/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362

The rule expands a URL by looking for SKU marker -zid within the URL. It then creates a URL path part of the form /ViewProduct-Start?SKU=<SKU>.

Expand example:

http://www.example.com/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362
to
http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewProduct-Start?SKU=M8182790134362

Rule configuration parameters:

NameValueDescription
fullCategoryPath true

The complete category path will be used in the rewritten URL:
/RootCatalog/SubCategory/SubSubCategory/SubSubSubCategory/

e.g., /computers/servers/fileservers-raidarrays/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362

false

Only CatalogID and the leaf category of the category path will be shown/RootCatalog/SubSubSubCategory/

e.g., /Computers/fileservers-raidarrays/GoPro%20HERO4%20Silver%20Bundle -zidM8182790134362

(warning) When localized (configuration parameter localizedCategoryPath = true), the localized names must be unique! Otherwise the correct category cannot be determined: Is it category with ID 4353 and name "fileservers-raidarrays" or category with ID 7675 and name "fileservers-raidarrays"?

localizedCategoryPath true

Localized DisplayNames are used, e.g.,

/Computers/servers/fileservers-raidarrays/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362

false

The plain CategoryIDs and product SKU are used, e.g.

/Computers/523/949/922/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362

5.8 Category

Creates a link to a category.

Rewrites URLs that link to a category with the pipeline start-node ViewStandardCatalog-Browse. URL input parameters for identifying the category are CategoryName and CatalogID.

Example for compacting/expanding:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewStandardCatalog-Browse?CatalogID=Computers&CategoryName=922
to
http://www.example.com/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD /Computers/922

Category URLs use a trailing "/" in short URLs as unique identifier.

Rule configuration parameters:

NameValueDescription
fullCategoryPath true

The complete category path will be used in the rewritten URL:
/RootCatalog/SubCategory/SubSubCategory/SubSubSubCategory/

e.g., /computers/servers/fileservers-raidarrays/

false

Only CatalogID and the leaf category of the category path will be shown/RootCatalog/SubSubSubCategory/

e.g., /computers/fileservers-raidarrays/

(warning) When localized (configuration parameter localizedCategoryPath = true), the localized names must be unique! Otherwise the correct category cannot be determined: Is it category with ID 4353 and name "fileservers-raidarrays" or category with ID 7675 and name "fileservers-raidarrays"?

localizedCategoryPath true

Localized DisplayNames are used, e.g.,

/computers/servers/fileservers-raidarrays/

false

The plain CategoryIDs are used, e.g.

/Computers/523/949/922/

5.9 SitemapProducts

Creates rewritten URLs for a sitemap referencing a category containing with links to all products of a given catalog or category.

Rewrites URLs that link to a sitemap via pipeline start node "ViewSitemap-ProductList". URL input parameters are CategoryName and CatalogID.

Example:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewSitemap-ProductList?CatalogID=Computers&CategoryName=922
to
http://www.example.com/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD /sitemap-products/Computers/922/

Category URLs use a trailing "/" in short URLs as unique identifier.

Rule configuration parameters:

NameValueDescription
fullCategoryPath true

The complete category path will be used in the rewritten URL:
/RootCatalog/SubCategory/SubSubCategory/SubSubSubCategory/

e.g., /computers/servers/fileservers-raidarrays/

false

Only CatalogID and the leaf category of the category path will be shown/RootCatalog/SubSubSubCategory/

e.g., /computers/fileservers-raidarrays/

(warning) When localized (configuration parameter localizedCategoryPath = true), the localized names must be unique! Otherwise the correct category cannot be determined: Is it category with ID 4353 and name "fileservers-raidarrays" or category with ID 7675 and name "fileservers-raidarrays"?

localizedCategoryPath true

Localized DisplayNames are used, e.g.,

/computers/servers/fileservers-raidarrays/

false

The plain CategoryIDs are used, e.g.

/Computers/523/949/922/

shortPath

e.g., "/sitemap-products"A short path usually starting with a slash.

5.10 ViewData

Rewrites URLs which call pipeline ViewData-Start.

Example for compacting/expanding:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewData-Start/2035272761?JumpTarget=ViewCart-View 
to
https://www.example.com/WFS/inTRONICS/en_US/-/USD/viewdata/2035272761?JumpTarget=ViewCart-View

NameValueDescription

shortPath

Examples:

"/viewdata"
"/cart/de_DE"

A short path usually starting with a slash. This parameter is optional.
If no short path is configured, the rule will use "/viewdata" as short path per default.
This parameter must not end with a "/".

6 White-listed Parameters

6.1 Description

Some marketing agencies (like price search engines) or malicious users infect Intershop URLs with unnecessary parameters. This may lead to a massive downgrade of the cache hit ratio for the page cache, to an increased page cache size and finally leads to bad application server performance due to unnecessary requests. Blacklisting for named bad parameters would not help in such situations as the parameters are changed dynamically. The Pipeline-Whitelist-Parameter feature makes the ICM more robust against such requests. This functionality is achieved by white-listing allowed parameters in invoked URLs. Unknown parameters will be removed from the URL before a page is looked up from the cache. White-listing uses either the declared input parameters of strict pipelines or alternately the parameters from the pipelinewhitelistparameters.properties.

6.2 Configuration

Since the feature is part of the urlewrite expand functionality, it can be enabled in the share/system/config/cluster/urlrewiterules.xml. Each rule can set an optional parameter: restrictToWhitelistedParameters which enables the Whitelisted Parameters feature for a particular Rewrite Rule. The feature is disabled by default and in contrary to the old implementation it can not be enabled globally.

For manually white-listing parameters check the configuration properties file under /share/system/config/cluster/pipelinewhitelistparameters.properties.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets