Concept - URL Rewriting (7.8 - 7.10.3)

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.

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.

References

Cookbook - URL Rewriting

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

History

A short overview of the URL Rewrite Handler evolution.

Version	Name	Description	Documentation
< 7.4	RuleRewriteHandler	Regular expression rules and a host specific domainsplitting configured in properties files	see "URL Handling" documents
< 7.8	RuleRewriteHandler + advanced Domainsplitting	Regular expression rules and a host+shortpath specific domainsplitting configured in properties files	see "URL Handling" documents
7.8	New RewriteRuleHandlerImpl	Complete rework supports custom rewrite-rule types and configuration in XML	see "URL Rewriting" documents

Note

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

Algorithm

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

The expand process is displayed in the following:

Artifacts

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.

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.

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.

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, currencies, server-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>

Structure

Rewrite Rules

Overview

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

Name	Pipeline	Parameters	Configuration Parameters	Description
Homepage	ViewHomepage-Start		shortPath	Define a starting page for a shop by specifying a shortPath (e.g., /start, / or "")
Pipeline	Any pipeline identified by configuration parameter "startNode"	pipeline	startNode shortPath	Pipeline node (e.g., startNode) is replaced with a given shortPath
Page	ViewContent-Start	PageletEntryPointID	pageletId shortPath	The "shortPath" is set, when the pageletId matches.
PageGeneric	ViewContent-Start	PageletEntryPointID	uniquePrefix	Creates CMS links automatically following the pattern /<PageletEntryPoint:DisplayName><uniquePrefix><PageletEntryPointID>
Product	ViewProduct-Start	SKU	fullCategoryPath localizedCategoryPath	Creates links with the following pattern`/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362`
Category	ViewStandardCatalog-Browse	CatalogID CategoryName	fullCategoryPath localizedCategoryPath	All incoming parameters are removed.
RegEx	parameters 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
SitemapProducts	ViewSitemap-ProductList	CatalogID CategoryName	shortPath (e.g., "/sitemap-products") fullCategoryPath localizedCategoryPath	Creates a product sitemap with a prepended short path /<shortPath>/<categoryPath>$
ViewData	ViewData-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>

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

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.

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.

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.

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.

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:

Name	Value	Description
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
fullCategoryPath	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 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
localizedCategoryPath	false	The plain CategoryIDs and product SKU are used, e.g. /Computers/523/949/922/GoPro%20HERO4%20Silver%20Bundle-zidM8182790134362

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:

Name	Value	Description
fullCategoryPath	true	The complete category path will be used in the rewritten URL: /RootCatalog/SubCategory/SubSubCategory/SubSubSubCategory/ e.g., /computers/servers/fileservers-raidarrays/
fullCategoryPath	false	Only CatalogID and the leaf category of the category path will be shown/RootCatalog/SubSubSubCategory/ e.g., /computers/fileservers-raidarrays/ 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/
localizedCategoryPath	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.

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

Rule configuration parameter:

Name	Value	Description
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 "/".

White-listed Parameters

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.

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.

Table of Contents

Introduction

Glossary

References

URL Anatomy

History

Algorithm

Artifacts

Domain Splitting

XML Definition

domainsplittings.xml

urlrewriterules.xml

Structure

Rewrite Rules

Overview

Homepage

Pipeline

RegEx

Page

Page Generic

Product

Category

SitemapProducts

ViewData

White-listed Parameters

Description

Configuration