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

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.

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 in the domainsplittings.xml section).

• Expanding: The domain-splittings are matched from bottom to top (see XML file in the domainsplittings.xml section).

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

urlrewriterules.xml

The schema of the 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 rewrite rule above 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>
			<configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
			<configuration id="replacementForExcludedCharacters">-</configuration>
			<!-- default is false=off / if true - prevents SOLR index filter stored in query-parameter 'SearchParameter' from being doubly encoded -->
            <!-- <configuration id="filterSearchParameterMapping">true</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>
			<configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
			<configuration id="replacementForExcludedCharacters">-</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>
			<configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
			<configuration id="replacementForExcludedCharacters">-</configuration>
        </configurations>
	</rule>
    <!-- type "Search" creates /search/<search term value>/ (default) or /search?SearchTerm=<search term value>  -->
    <rule type="Search" priority="70" name="SimpleSearch"></rule>

<!-- prevents SOLR index filter stored in query-parameter 'SearchParameter' from being doubly encoded for pipelines: 'ViewParametricSearch-Browse' and 'ViewParametricSearch-ProductPageing' -->
<!-- 
    <rule type="SearchFilter" priority="95" name="Search Filter by rule">
    <!-- if this three configurations are commented out, the product paging throught a search results falls-back to ProductRaging RexEx rule configuration -->
 		<configurations>
			<configuration id="startNode">ViewParametricSearch-</configuration>
			<configuration id="startNodePaging">ProductPaging</configuration>
			<configuration id="startNodeBrowse">Browse</configuration>
		</configurations>
	</rule>
 -->    
</rules>

Structure

Rewrite Rules

Overview

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

# 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}

# 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

Homepage

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

Rule configuration parameter:

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. For instance, ViewSitemap-Start maps onto /sitemaps and vice-versa.

Rewrite Rule configuration parameter:

RegEx

Classic rules based on regular expressions.

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:

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. Otherwise, the rewrite rule uses the ID of the pagelet entry point.

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

Product

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

The only context parameter needed for compacting is the SKU. The 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:

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

Rule configuration parameters:

SitemapProducts

Creates rewritten URLs for a sitemap referencing a category containing 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/

Rule configuration parameters:

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

now also customizable to

https://www.example.com/WFS/inTRONICS/en_US/-/USD/checkoutViewCart/2035272761 or with properly setup domainsplittings https://www.example.com/checkoutViewCart/2035272761

 Rule configuration parameter

Custom configuration example

Here is a example configuration to the replace the entire basket checkout process with custom configurations. This works for the registered and an anonymous user.

The path and query parameter like: /viewdata/12345678?JumpTarget=ViewCheckoutReview-Start - gets to look like: /checkoutReview/12345678 instead.

<rule type="ViewData" priority="10" name="Pipeline ViewData-Start - with custom configuration"> 
  <configurations>
    <configuration id="customShortPath1">/checkoutViewCart</configuration>
    <configuration id="customJumpTarget1">ViewCart-View</configuration>
    <configuration id="customShortPath2">/checkoutPaymentReview</configuration>
    <configuration id="customJumpTarget2">ViewCheckoutPayment-Review</configuration>
    <configuration id="customShortPath3">/checkoutPaymentStart</configuration>
    <configuration id="customJumpTarget3">ViewCheckoutPayment-Start</configuration>
    <configuration id="customShortPath4">/checkoutReview</configuration>
    <configuration id="customJumpTarget4">ViewCheckoutReview-Start</configuration>
    <configuration id="customShortPath5">/checkoutSummary</configuration>
    <configuration id="customJumpTarget5">ViewCheckoutConfirmation-Start</configuration>
    <configuration id="customShortPath6">/checkoutLogin</configuration>
    <configuration id="customJumpTarget6">ViewCheckoutAddresses-Review</configuration>
    <configuration id="customShortPath7">/checkoutShipping</configuration>
    <configuration id="customJumpTarget7">ViewCheckoutShipping-Review</configuration>
    <!-- this will remove the OrderID from the URL in the final checkout step -->
	<!-- <configuration id="deleteShortPathParameter">OrderID</configuration> -->
  </configurations>
  
  <!-- optional pipeline rules to rewrite basket checkout 'breadcrumb' URLs -->
  <!-- their priority is lower than the one from the 'ViewData' rule; ViewData rule must be checked first -->
  <!-- 
	<rule type="Pipeline" priority="5" name="checkoutPaymentReview ViewCheckoutPayment-Review 2">
		<configurations>
			<configuration id="startNode">ViewCheckoutPayment-Review</configuration>
			<configuration id="shortPath">/checkoutPaymentReview</configuration>
		</configurations>
	</rule>
	<rule type="Pipeline" priority="5" name="checkoutPaymentStart ViewCheckoutPayment-Start 3">
		<configurations>
			<configuration id="startNode">ViewCheckoutPayment-Start</configuration>
			<configuration id="shortPath">/checkoutPaymentStart</configuration>
		</configurations>
	</rule>
	<rule type="Pipeline" priority="5" name="checkoutReview ViewCheckoutReview-Start 4">
		<configurations>
			<configuration id="startNode">ViewCheckoutReview-Start</configuration>
			<configuration id="shortPath">/checkoutReview</configuration>
		</configurations>
	</rule>
	<rule type="Pipeline" priority="5" name="checkoutSummary ViewCheckoutConfirmation-Start 5">
		<configurations>
			<configuration id="startNode">ViewCheckoutConfirmation-Start</configuration>
			<configuration id="shortPath">/checkoutSummary</configuration>
		</configurations>
	</rule>
	<rule type="Pipeline" priority="5" name="checkoutLogin ViewCheckoutAddresses-Review 6">
		<configurations>
			<configuration id="startNode">ViewCheckoutAddresses-Review</configuration>
			<configuration id="shortPath">/checkoutLogin</configuration>
		</configurations>
	</rule>
	<rule type="Pipeline" priority="5" name="checkoutShipping ViewCheckoutShipping-Review 7">
		<configurations>
			<configuration id="startNode">ViewCheckoutShipping-Review</configuration>
			<configuration id="shortPath">/checkoutShipping</configuration>
		</configurations>
	</rule>  
	-->
</rule> 

Search

Rewrites URLs that call the pipeline ViewParametricSearch-SimpleOfferSearch.

Example for compacting/expanding:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewParametricSearch-SimpleOfferSearch?SearchTerm=Sony

to - if configuration searchTermLocation=path (=default):
https://www.example.com/WFS/inTRONICS/en_US/-/USD/search/Sony/

or to - if configuration searchTermLocation=parameter:

https://www.example.com/WFS/inTRONICS/en_US/-/USD/search?SearchTerm=Sony

Rule configuration parameter:

Example SearchRewriteRule configuration with custom parameters instead of default values - urlrewriterules.xml - custom search rule section:

<rule type="Search" priority="70" name="SimpleSearch">
  <configurations>
    <configuration id="startNode">ViewParametricSearch-CustomSimpleOfferSearch</configuration>
    <configuration id="shortPath">/searchCustom</configuration>
    <configuration id="shortPathMatch">^/searchCustom/(.+)/$</configuration>
    <configuration id="searchTerm">SearchTermCustom</configuration>
    <configuration id="searchTermLocation">parameter</configuration>
    <!-- <configuration id="searchTermLocation">path</configuration> -->
  </configurations>
</rule>

SearchFilter

This rule exists to avoid double-encoded characters in the URL when a user selects a search filter in the storefront navigation. This is better for both SEO and Google Analytics.

Example:
SearchParameter=%26%40QueryTerm%3DAc* will be converted to Filter_QueryTerm=Ac* and back when it gets processed in ICM.

It rewrites URLs that call the ViewParametricSearch-Browse pipeline. With the right configuration, the ViewParametricSearch-ProductPaging pipeline is called as well.

This rule handles the Solr search filter parameter for ViewParametricSearch-Browse and the ViewParametricSearch-ProductPaging.
The SearchParameter URL query parameter contains multiple search result filter configurations. They are dependent on the SOLR configuration. They are double-encoded, because the processes handling SearchParameter values expect multiple key/values inside. Otherwise, they are treated as a separate parameter and are not recognized as a SearchParameter filter condition.

Example for compacting/expanding:

http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewParametricSearch-Browse?CatalogCategoryID=VAoKAP83fEsAAAGOZU1KTKtd&SearchParameter=%26%40QueryTerm%3DAc*%26ContextCategoryUUID%3DVAoKAP83fEsAAAGOZU1KTKtd%26OnlineFlag%3D1&PageSize=12&SortingAttribute=&SearchTerm=Ac*

to - default and without paging:

https://www.example.com/searchFilter?PageSize=12&SortingAttribute=&SearchTerm=Ac*&CatalogID=Computers&Filter_QueryTerm=Ac*&Filter_CategoryID=Computers&Filter_ManufacturerName=A-DATA&Filter_OnlineFlag=1

to - if configuration default - ProductPaging is ignored in this rule and falls back to the RegEx product paging rule, which does not prevent URL query parameter ‘SearchParameter’ values from being double-encoded:

https://www.example.com/filter/ 5 ?PageSize=12&ViewType=&SearchTerm=Ac*&SearchParameter=%26%40QueryTerm%3DAc*%26ContextCategoryUUID%3DVAoKAP83fEsAAAGOZU1KTKtd%26ManufacturerName%3DA-DATA%26OnlineFlag%3D1

or to - if configuration handles both Browse and ProductPaging:

https://www.example.com/searchFilter?PageNumber=5&PageSize=12&ViewType=&SearchTerm=Ac*&CatalogID=Computers&Filter_QueryTerm=Ac*&Filter_CategoryID=Computers&Filter_ManufacturerName=A-DATA&Filter_OnlineFlag=1

Rule configuration parameter:

Example SearchFilterRewriteRule configuration with custom parameters instead of default values - urlrewriterules.xml - custom search rule section:

<rule type="SearchFilter" priority="95" name="Search Filter by rule">
  <configurations>
    <!-- overwrites default startNode or in combination with the 'startNodePaging' and 'startNodeBrowse' acts as peipeline name prefix so do NOT forget '-' after 'ViewParametricSearch' -->
    <configuration id="startNode">ViewParametricSearch-</configuration>
    <!-- if 'startNode' is configured for two pipeline names, it holds the pipeline-start-node-name for the paging through product pages -->
    <configuration id="startNodePaging">ProductPaging</configuration>
<!-- if 'startNode' is configured for two pipeline names, it holds the pipeline-start-node-name for the browsing through the SOLR search result by selecting filter (sub-categories, price-range, color, etc.)  -->
    <configuration id="startNodeBrowse">Browse</configuration>
  </configurations>
</rule>

Rewrite Rules for PWA

There are four new rewrite rules which create sitemap URLs. These URLs only work for the Intershop Progressive Web App (PWA), not for the inSPIRED Demo store! Thus, only the compact code is implemented, not the code for expanding URLs.

There are a few optionalconfigurations which might compensate some PWA route modifications.

These rules are closely linked to Concept - XML Sitemaps | XML Sitemaps and Intershop PWA and its configurations in syndication-targets.properties (cluster configuration directory).

The pipeline names configured for sitemapPipeline and viewingPipeline: ViewSiteMapXMLforPWA-Start, ViewProductPWA-Start, ViewStandardCatalogPWA-Browse, and ViewContentPWA-Start do not exist. They are simply used as a unique identifier for the rewrite rules described here in this chapter of this document.

For all PWA rewrite rules the protocol is fixed on https as configured in syndication-targets.properties:

intershop.syndication.target.Sitemaps-PWA.protocol=https

SitemapRangePWA

Description

This rule generates the links for the initial sitemap_pwa.xml file.

This file contains URLs to the location of zipped xml file(s) located in the ICM Shared-File-System (SFS), which contain the actual sitemap content for products, categories, and pages.

The filename and its extension meet the following requirements:

• syndication-id=sitemap_pwa

• objectType=product

• catalogcategory

• staticpage and extension=.xml.gz

Example URLs

sitemap_pwa

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
	<sitemap>
		<loc>https://intershoppwa.azurewebsites.net/sitemap_pwa-product-0.xml.gz</loc>
		<lastmod>2020-10-16T18:20:15+02:00</lastmod>
	</sitemap>
	<sitemap>
		<loc>https://intershoppwa.azurewebsites.net/sitemap_pwa-catalogcategory-0.xml.gz</loc>
		<lastmod>2020-10-16T18:20:41+02:00</lastmod>
	</sitemap>
	<sitemap>
		<loc>https://intershoppwa.azurewebsites.net/sitemap_pwa-staticpage-0.xml.gz</loc>
		<lastmod>2020-10-16T18:20:41+02:00</lastmod>
	</sitemap>
</sitemapindex>

Default Rewrite Rule Configuration

This urlrewriterules.xml configuration gets the default URLs for the XML sitemap for PWA.

urlrewriterules.xml - default SitemapRangePWA rule section

<rule type="SitemapRangePWA" priority="100" name="sitemap range pwa links"></rule>

Optional Rewrite Rule Configurations

These optional configurations replace the default configurations:

• shortPath - default value is '/'

• syndicationID - default is the Syndication-ID configured in Concept - XML Sitemaps | Syndications.

  • Configuring the syndicationID rewrite rules does not change its actual location in the Shared File System (SFS)

  • The SFS location is defined in syndication-targets.properties with property-key: intershop.syndication.target.Sitemaps-PWA.exportDirectory, see Concept - XML Sitemaps | Configuration Files.

• pwaHost - default value is described in OptionalPWARuleConfigurations.

urlrewriterules.xml - custom SitemapRangePWA rule section

<rule type="SitemapRangePWA" priority="100" name="sitemap range pwa links">
  <configurations>
    <!-- below are optional parameters to customize the default behavior of the SitemapRangePWA rewrite rule -->
    <configuration id="shortPath">/syndication-</configuration>
    <configuration id="syndicationID">sitemap_for_pwa</configuration>
    <configuration id="pwaHost">www.intershop.com</configuration>
  </configurations>
</rule>

This configuration would result in URLs like: <loc>https://www.intershop.com/syndication-sitemap_for_pwa-staticpage-0.xml.gz</loc>

Removal of optional Rewrite Rule Configuration Parameter sitemapFileExtension - from ICM 7.10.38.

SitemapProductPWA

Description

This rule is based on the Category rewrite rule and inherits some of its configuration options (see Category rule details), because the biggest part of the sitemap product URLs for the PWA is the category where the product is assigned to.

It is used when the pipeline name is: ViewProductPWA-Start.

Default Rewrite Rule Configuration

This urlrewriterules.xml configuration gets the default product URLs for the XML sitemap for PWA.

Rule configuration parameters:

Example configuration for SitemapProductPWA - urlrewriterules.xml - default SitemapProductPWA rule section:

<rule type="SitemapProductPWA" priority="100" name="sitemap product pwa links">
	<configurations>
		<configuration id="slugifyPwaDefault">true</configuration>
		<configuration id="excludedCharacters">( ) &amp;</configuration>
	<!--	<configuration id="excludedCharacters">( )</configuration> before 7.10.40 release -->
	</configurations>
</rule>

Optional Rewrite Rule Configurations

See OptionalPWARuleConfigurations.

Example URLs

sitemap_product

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<url>
	<loc>https://intershoppwa.azurewebsites.net/Digital-Cameras/Pentax-Optio-RZ10-sku5920586-catCameras-Camcorders.575</loc>
	<lastmod>2020-09-30T19:57:14+02:00</lastmod>
	<changefreq>weekly</changefreq>
	<priority>0.8</priority>
	<image:image>
		<image:loc>https://intershoppwa.azurewebsites.net:443/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/rest/inSPIRED/en_US/L/5920586-7387.jpg</image:loc>
		<image:title>Pentax Optio RZ10</image:title>
		<image:caption>Pentax Optio RZ10</image:caption>
	</image:image>
	<image:image>
		<image:loc>https://intershoppwa.azurewebsites.net:443/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/rest/inSPIRED/en_US/S/5920586-7387.jpg</image:loc>
		<image:title>Pentax Optio RZ10</image:title>
		<image:caption>Pentax Optio RZ10</image:caption>
	</image:image>
</url>
...
</urlset>

SitemapCategoryPWA

Description

This rule is based on the Category rewrite rule and inherits some of its configuration options (see Category rule details).
It is used when the pipeline name is: ViewStandardCatalogPWA-Browse.

Default Rewrite Rule Configuration

This urlrewriterules.xml configuration gets the default category URLs for the XML sitemap for PWA.

See the explanations of the rule configuration parameters slugifyPwaDefault and excludedCharacters in SitemapProductPWA | Default Rewrite Rule Configuration.

Example configuration for SitemapCategoryPWA - urlrewriterules.xml - default SitemapCategoryPWA rule section:

<rule type="SitemapCategoryPWA" priority="100" name="sitemap category pwa links">
	<configurations>
		<configuration id="slugifyPwaDefault">true</configuration>
		<configuration id="excludedCharacters">( ) &amp;</configuration>
	<!--	<configuration id="excludedCharacters">( )</configuration> before 7.10.40 release -->
	</configurations>
</rule>

Optional Rewrite Rule Configurations

See OptionalPWARuleConfigurations.

Example URLs

sitemap_category

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<url>
	<loc>https://intershoppwa.azurewebsites.net/Backpacks,-Notebook-Bags-&amp;-Cases-catComputers.1835.3003</loc>
	<lastmod>2020-09-30T19:55:03+02:00</lastmod>
	<changefreq>monthly</changefreq>
	<priority>0.4</priority>
</url>
<url>
	<loc>https://intershoppwa.azurewebsites.net/Remote-Controls-catHome-Entertainment.1058.857</loc>
	<lastmod>2020-09-30T19:55:09+02:00</lastmod>
	<changefreq>monthly</changefreq>
	<priority>0.4</priority>
</url>
<url>
	<loc>https://intershoppwa.azurewebsites.net/Firewire-Cables-catComputers.106.830.1306</loc>
	<lastmod>2020-09-30T19:55:03+02:00</lastmod>
	<changefreq>monthly</changefreq>
	<priority>0.4</priority>
</url>
...
</urlset>

SitemapContentPagePWA

Description

This rule is based on the Page rewrite rule and inherits some of its configuration options, see Page rule details.
It is used when the pipeline name is: ViewContentPWA-Start.

Default Rewrite Rule Configuration

This urlrewriterules.xml configuration gets the static pages' URLs for the XML sitemap for PWA.

There are two ways to configure the SitemapContentPagePWA rule:

• The default behavior simply places the pageletId found behind a default shortPath of '/page', e.g.: /page/page.helpdesk.faq

• For an individual configuration use the pageletId found to set a configured unique shortPath. The host-name can be set as an optional configuration.

  • The mode changes if the pageletId configuration for a SitemapContentPagePWA rule is set or not.

  • The specific rule (privacy-policy) has to have a higher priority (105) than the common rule (100).

• The optional parameter pwaHost can be used for local setups or debugging purposes.

  • It basically forces the host name to be the rule configured Host, instead of the one in the Application configuration for 'rest' applications.

urlrewriterules.xml - SitemapContentPagePWA rule section

<!-- individual configuration -->
<rule type="SitemapContentPagePWA" priority="105" name="sitemap content page pwa privacy-policy">
  <configurations>
	<configuration id="pageletId">systempage.privacyPolicy.pagelet2-Page</configuration>
	<configuration id="shortPath">/en/privacy-policy</configuration>
	<!-- <configuration id="pwaHost">www.intershop.com</configuration> -->
  </configurations>
</rule>
<!-- default -->
<rule type="SitemapContentPagePWA" priority="100" name="sitemap content page pwa links"></rule>

Example URLs

sitemap_static-page

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<url>
	<loc>https://intershoppwa.azurewebsites.net/page/page.helpdesk.faq</loc>
	<lastmod>2020-09-30T20:00:09+02:00</lastmod>
	<changefreq>yearly</changefreq>
	<priority>0.3</priority>
</url>
<url>
	<loc>https://www.intershop.com/en/privacy-policy</loc>
	<lastmod>2020-10-05T12:34:00+02:00</lastmod>
	<changefreq>yearly</changefreq>
	<priority>0.3</priority>
</url>
<url>
	<loc>https://intershoppwa.azurewebsites.net/page/systempage.termsAndConditions.pagelet2-Page</loc>
	<lastmod>2020-10-05T12:34:00+02:00</lastmod>
	<changefreq>yearly</changefreq>
	<priority>0.3</priority>
</url>
...
</urlset>

Optional PWA Rule Configurations

Description

There are some configurations which work for all PWA rewrite rules. These optional configurations are described here.

• The default pipeline name which has to match for the rule to be applied can be modified with configuration of startNode.

  • It has to match the configuration in syndication-targets.properties, see Concept - XML Sitemaps | XML Sitemaps and Intershop PWA.

  • In case a customized syndication target or customized rules are required, the startNode can be used to differentiate.

• For all PWA rewrite rules, the host-name is either extracted from the assigned application configured external base URL, from the rewrite rule configuration pwaHost, or from intershop.WebServerSecureURL.

  • With the configuration pwaHost each rule can set its own host-name for its generated sitemap URLs.

  • Except for image URLs, the URLs always depend on intershop.WebServerSecureURL.

• Individual control of the behavior of the slugify method. This method prevents URL issues, see SitemapProductPWA | Default Rewrite Rule Configuration.

  • For the PWA the default behavior is set with: slugifyPwaDefault=true which results in URLs as described in section SitemapProductPWA | Default Rewrite Rule Configuration.

  • In case some character usually handled by the slugify method causes trouble as part of the URL, a more selective configuration is possible:

    • slugifyPreventToLowerCase=true prevents the slugify method from converting all characters to lower case.

    • slugifyPreventReplaceUmlauts=true prevents the slugify method from converting German umlauts from ä to ae and ö to oe and so on.

    • slugifyPreventStripAccents=true prevents the slugify method from removing apostrophes from French or Czech characters.

    • slugifyPwaDefault=true is all of the above set to true, so the URLs contain upper case characters, German umlauts, and characters with apostrophe.

• The configuration charactersToEncode was introduced to encode special characters in case they cause problems.

  • It allows to configure characters which need to be encoded (java.net.URLEncoder.encode(...)) - e.g: converts '-6GB-(2GB-x-3)-sku' to -6GB-%282GB-x-3%29-sku

  • The charactersToEncode configuration takes a list of characters to be encoded. No separation character! See example below.

• The configuration categoryPathPrefix allows to replace the default -cat with a customized version - only valid for SitemapProductPWA and SitemapCategoryPWA rule

  • from: https://intershoppwa.azurewebsites.net/Remote-Controls-catHome-Entertainment.1058.857

  • to: https://intershoppwa.azurewebsites.net/Remote-Controls-category-Home-Entertainment.1058.857

Example - urlrewriterules.xml

urlrewrite.xml - configuration

<rule type="SitemapProductPWA" priority="105" name="sitemap product pwa links customized">
  ...
  <configurations>
	<configuration id="startNode">ViewProductPWACustom-Start</configuration>
	<configuration id="pwaHost">www.customized.intershop.pwa.azurewebsites.net:449</configuration>

    <!-- both 'slugifyPwaDefault' and 'slugifyPrevent...'do not make sense at the same time -->
    <!-- <configuration id="slugifyPwaDefault">true</configuration> -->
    <configuration id="slugifyPreventToLowerCase">true</configuration>
	<configuration id="slugifyPreventReplaceUmlauts">true</configuration>
	<configuration id="slugifyPreventStripAccents">true</configuration>

	<configuration id="charactersToEncode">( ) &amp</configuration>
	<configuration id="categoryPathPrefix">-category-</configuration>
    ...
  </configurations>
</rule>

Rewrite Rules for PWA3

There are three new rewrite rules that create sitemap URLs. These URLs only work for the Intershop Progressive Web App (PWA) version 3, not for the PWA before version 3 or the inSPIRED Demo store!

Since the release of PWA3 its URLs have changed, which makes the 'old' PWA SiteMaps links incompatible. The rules described in these chapters are designed to create PWA3 compatible URLs for the SiteMap.

There are a few optional configurations which might compensate some PWA route modifications.

These rules are closely linked to Concept - XML Sitemaps | XML Sitemaps and Intershop PWA and its configurations in syndication-targets.properties (cluster configuration directory).

The pipeline names configured for sitemapPipeline and viewingPipeline: ViewSiteMapXMLforPWA-Start, ViewProductPWA3-Start, ViewStandardCatalogPWA3-Browse and ViewContentPWA3-Start do not exist. They are simply used as a unique identifier for the rewrite rules described in this chapter of this document.

For all PWA3 rewrite rules, the protocol is set to https as configured in syndication-targets.properties:

intershop.syndication.target.Sitemaps-PWA3.protocol=https

SitemapRangePWA3

Description

This rule generates the links for the initial sitemap_pwa.xml file.

No new PWA3 version has been developed for this rule, because nothing has changed between the PWA version before 3 and the current PWA version 3.

For details, see SiteRangePWA.

SitemapProductPWA3

Description

This rule is based on the Category rewrite rule and uses some of its configuration options (see Category rule details), because the first and the last part of the sitemap product URLs for the PWA3 is the category where the product is assigned to.

It is used when the pipeline name is: ViewProductPWA3-Start. Which is configured in the syndication-targets.properties file section Sitemaps-PWA3.

Default Rewrite Rule Configuration

This urlrewriterules.xml configuration gets the default product URLs for the XML sitemap for PWA.

Rule configuration parameters:

Example configuration for SitemapProductPWA3:

urlrewriterules.xml - default SitemapProductPWA rule section

<rule type="SitemapProductPWA3" priority="100" name="sitemap product pwa links for PWA3">
	<configurations>
		<configuration id="slugifyPwa3Default">true</configuration>
		<configuration id="excludedCharactersRule">[ &\(\)=]</configuration>
    <!-- <configuration id="excludedCharactersRule">[^a-zA-Z0-9äöüÄÖÜé]</configuration> white listed characters example -->
		<configuration id="urlCharactersNotToEncode">/,'</configuration>
	</configurations>
</rule>

Optional Rewrite Rule Configurations

See Optional PWA Rule Configurations.

Example URLs

sitemap_product

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<url>
	<loc>https://intershoppwa.azurewebsites.net/computer/datenspeicher/festk%C3%B6rperdrives/a-data-s511-240gb-prd9013198-ctgComputers.206.1563</loc>
	<lastmod>2020-09-30T19:57:14+02:00</lastmod>
	<changefreq>weekly</changefreq>
	<priority>0.8</priority>
	<image:image>
		<image:loc>https://intershoppwa.azurewebsites.net:443/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/rest/inSPIRED/en_US/L/9013198-7387.jpg</image:loc>
		<image:title>A Data S511</image:title>
		<image:caption>A Data S511</image:caption>
	</image:image>
	<image:image>
		<image:loc>https://intershoppwa.azurewebsites.net:443/INTERSHOP/static/WFS/inSPIRED-inTRONICS-Site/rest/inSPIRED/en_US/S/9013198-7387.jpg</image:loc>
		<image:title>A Data S511</image:title>
		<image:caption>A Data S511</image:caption>
	</image:image>
</url>
...
</urlset>

SitemapCategoryPWA3

Description

This rule is based on the Category rewrite rule and inherits some of its configuration options, see Category rule details.

It is used when the pipeline name is: ViewStandardCatalogPWA3-Browse.

Default Rewrite Rule Configuration

This urlrewriterules.xml configuration gets the default category URLs for the XML sitemap for PWA.

See the explanations of the rule configuration parameters slugifyPwa3Default, excludedCharactersRule and urlCharactersNotToEncode in SitemapProductPWA3 | Default Rewrite Rule Configuration.

Example configuration for SitemapCategoryPWA3:

urlrewriterules.xml - default SitemapCategoryPWA rule section

<rule type="SitemapCategoryPWA3" priority="100" name="sitemap category pwa links for pwa3">
	<configurations>
		<configuration id="slugifyPwa3Default">true</configuration>
		<configuration id="excludedCharactersRule">[ &\(\)=]</configuration>
		<configuration id="urlCharactersNotToEncode">/,'</configuration>
	</configurations>
</rule>

Optional Rewrite Rule Configurations

See Optional PWA Rule Configurations.

Example URLs

sitemap_category

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<url>
	<loc>https://intershoppwa.azurewebsites.net/computer/hardware-komponenten/geh%C3%A4use-komponenten/pc-k%C3%BChlventilatoren-ctgComputers.106.236.921</loc>
	<lastmod>2020-09-30T19:55:03+02:00</lastmod>
	<changefreq>monthly</changefreq>
	<priority>0.4</priority>
</url>
<url>
	<loc>https://intershoppwa.azurewebsites.net/computer/notebooks-und-pcs/backpacks,-notebook-bags-cases-ctgComputers.1835.3003</loc>
	<lastmod>2020-09-30T19:55:09+02:00</lastmod>
	<changefreq>monthly</changefreq>
	<priority>0.4</priority>
</url>
<url>
	<loc>https://intershoppwa.azurewebsites.net/konferenzausstattung/beamer-ctgpresentation-conferencing.data-projectors</loc>
	<lastmod>2020-09-30T19:55:03+02:00</lastmod>
	<changefreq>monthly</changefreq>
	<priority>0.4</priority>
</url>
...
</urlset>

SitemapContentPagePWA3

Description

This rule is based on the Page rewrite rule and inherits some of its configuration options, see Page rule details.

It is used when the pipeline name is ViewContentPWA3-Start.

It is currently a copy of the SitemapContentPagePWA rule implementation, because the URLs have not changed from the previous PWA versions to PWA3.

Custom Link Rewriting

There is a need to have storefront links that reference categories, products, pagelet entry points (CMS pages), pipelines, or just external links. Therefore, an easy-to-use syntax has been defined that is recognized within content created with the TinyMCE text editor.

Custom link rewriting uses the syntax of standard URLs, with each link having a specific protocol set. This way, the following can be achieved:

Text written with the TinyMCE: "... visit our <a href="pipeline://ViewContact-Start?ref=homepage">Contact page</a> for directions."

will convert links with a custom protocol (e.g., pipeline, product, category, page,..) into:

URL Rewriting disabled: "... visit our <a href="http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewContact-Start?ref=homepage">Contact page</a> for directions."

URL Rewriting enabled: "... visit our <a href="http://www.example.com/contact?ref=homepage">Contact page</a> for directions."

To give a short overview, the currently available custom links are described in the table below:

To perform proper URL rewriting, a custom link will enrich the dictionary with objects like CategoryBO , ProductBO or PageletEntryPoint (see table above). These dictionary entries can be referenced in rewriting rules, see excerpts from the urlrewriterules.xml below.

<rule type="Category" priority="40" name="in-350">
	<configurations>
		<configuration id="fullCategoryPath">true</configuration>
		<configuration id="localizedCategoryPath">true</configuration>
		<configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
		<configuration id="replacementForExcludedCharacters">-</configuration>					
	</configurations>
</rule>

<rule type="Product" priority="50" name="in-200">
	<configurations>
		<configuration id="fullCategoryPath">true</configuration>
		<configuration id="localizedCategoryPath">true</configuration>
		<configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
		<configuration id="replacementForExcludedCharacters">-</configuration>					
	</configurations>
</rule>

<rule type="Page" priority="100" name="helpdesk/contact-us">
	<configurations>
		<configuration id="parameterName">PageletEntryPointID</configuration>
		<configuration id="pageletId">systempage.helpdesk.contactUs.pagelet2-Page</configuration>
		<configuration id="shortPath">/helpdesk/contact-us</configuration>
	</configurations>
</rule>
<rule type="PageGeneric" priority="10" name="page fall-back">
	<configurations>
		<configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
		<configuration id="replacementForExcludedCharacters">-</configuration>					
	</configurations>
</rule>

<rule type="RegEx" priority="90" name="custom category example with a flexible RegEx rule">
	<configurations>
		<!-- compact -->
		<configuration id="select">${action}/${p.CategoryBO}/</configuration>
		<configuration id="selectMatch">^ViewStandardCatalog-Browse/([\w\-\.]+)/$</configuration>
		<configuration id="shortPath">/category/${p.CategoryBO:Name}${delete.CategoryBO}</configuration>
		<!-- expand -->
		<configuration id="shortPathMatch">^/category/([\w\-\.]+)/$</configuration>
		<configuration id="longPath">ViewStandardCatalog-Browse?CatalogCategoryBOName=$1</configuration>
	</configurations>
</rule>

At ISML level, the feature can be utilized with the IS modules ISLink and ISHtmlPrint as stated below:

<ISSet name="mylink" value="category://153@inSPIRED-Computers">
 
<!--- ISLink prints out a single link --->
<ISLink link="#mylink#">
 
<!--- ISHtmlPrint prints out a texts with replaced links inside --->
<ISHtmlPrint value="#'My custom link: '+mylink+' was just shown'#">

Since a custom link represents a standard URL, you are able to append parameters and anchor tags (e.g., category://153@inSPIRED-Computers?ref=summersale#specialconditions).

The protocol of the generated URLs of a custom link can be forced to https/http by adding the parameter ?ssl=true/false (e.g., product://12345678?ssl=true).

Since Intershop 7.7 - The localization of the URLs of a custom link can be achieved by appending the parameter ?localeId=<localization-id> (e.g., product://12345678?localeId=de_DE ).

The custom link rewriting is configurable via the Component Framework and must implement the StorefrontLinkRenderer interface.

Since Intershop 7.9 - To define the URLs destination locale, site and currency, add one or more of the following parameters:
?x-locale=<localization-id>&x-site=<site-name>&x-currency=<currency-mnemonic> (e.g., product://12345678?x-locale=de_DE&x-site=inSPIRED-inTRONICS-Site&x-currency=USD).

Whitelisted Parameters

Description

Some marketing agencies (such as price search engines) or malicious users infect Intershop URLs with unnecessary parameters. This can lead to a massive decrease in the cache hit ratio for the page cache, an increased page cache size, and ultimately poor application server performance due to unnecessary requests. Blacklisting for named bad parameters would not help in such situations because the parameters change dynamically. The pipeline whitelist parameter feature makes the ICM more robust against such requests. This functionality is achieved by whitelisting allowed parameters in invoked URLs. Unknown parameters are removed from the URL before a page is fetched from the cache. Whitelisting uses either the declared input parameters of strict pipelines, or alternatively the parameters from the pipelinewhitelistparameters.properties.

Configuration

Since this feature is part of the URL rewrite 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. This feature is disabled by default and, unlike the old implementation, cannot be enabled globally.

To manually whitelist parameters, check the configuration properties file at /share/system/config/cluster/pipelinewhitelistparameters.properties.

Redirect Status Code

Description

Redirecting URLs is sometimes necessary when an old shop system with its URLs is replaced by a new one, or a product is simply moved to a new category. To maintain the SEO ranking for these URLs, redirecting the request to the new URL is a common approach. When a URL is redirected, an appropriate redirect status code should be used to inform the requester of the redirect. The default redirect status code is 302, which means 'Moved tembut there are several other redirect status codes (3xx). Therefore, it is possible to set the status code of the redirecting links using the redirectStatusCode configuration.

Configuration

Since this feature is part of the URL rewrite expand functionality, it can be configured in the share/system/config/cluster/urlrewriterules.xml. Each rule can set an optional parameter redirectStatusCode, which allows to define a specific redirect status code for a particular rewrite rule that already uses redirect (HomepageRewriteRule, PageGenericRewriteRule, ProductRewriteRule). Without this parameter, the default behavior redirect status code 302 is used. For details, see Cookbook - URL Rewriting | Recipe: Redirect Status Code 301.

urlrewrite.xml - example configuration for a new rule type

...
<!-- type "PageGeneric" creates /{PageletEntryPoint DisplayName}-cms-${p.PageletEntryPointID} -->
    <rule type="PageGeneric" priority="10" name="page fall-back">
        <configurations>
            <configuration id="uniquePrefix">-cms-</configuration>
            <configuration id="excludedCharactersRule">[^a-zA-Z0-9]</configuration>
            <configuration id="replacementForExcludedCharacters">-</configuration>
            <configuration id="redirectStatusCode">301</configuration>
        </configurations>
    </rule>
...
    <rule type="LegacyRedirect" priority="100" name="lr-100">
        <configurations>
            <!-- replaces the default redirect status code of 302 with a 301 -->
            <configuration id="redirectStatusCode">301</configuration>
        </configurations>
    </rule>
 ...

Form Parameters

Description

Rewrite rules implement the abstract BaseRewriteRule class. This class contains two methods that allow you to retrieve the values of form parameters sent in a POST request.

These methods are called:

• String getServletFormParameter(String <form-parameter-name>)

• String[] getServletFormParameters(String <form-parameter-name>)

The first getServletFormParameter method simply reruns the first element of the array (String[]) retrieved by the second getServletFormParameters method.

The SearchRewriteRule rewrite rule uses this method.

• The form post parameter is only available in the initial request.

• If a redirect is required, the parameter should be stored as a RewriteContext.QueryParameters entry.

• That way, it is available to the redirecting request as well.

Remove URL Parameter(s)

This configuration allows you to remove one or more URL parameters from the compacted short URL, by adding the deleteShortPathParameter to its rule configuration in the urlrewrite.xml file.
This applies to all currently available rewrite rules, except for the RegEx rule. The RegEx rule handles removing a URL parameter differently, by adding {d.parameterName} (see RegEx rule details).

Description

Sometimes it is necessary to remove one or more URL parameters that are not needed in the link navigation logic. For SEO purposes, it is nice to have them removed.

Configuration

• There is now an easy way to remove an unnecessary URL parameter from the compacted short URL.

• Configure the parameter deleteShortPathParameter with a comma-separated list of URL parameter names to be removed.

• The parameter names are case sensitive.

• Configured parameter names which could not be found are ignored.

urlrewrite.xml - example configuration to remove a url parameter

...
<rule type="ViewData" priority="10" name="Pipeline ViewData-Start">
    <configurations>
		<configuration id="deleteShortPathParameter">JumpTarget</configuration>
	</configurations>
</rule>
<rule type="Search" priority="70" name="SimpleSearch">
    <configurations>
		<configuration id="deleteShortPathParameter">firstUnwantedSearchParameterName,anotherUnwantedParameterName</configuration>
	</configurations>
</rule>
 ...

Individual Rules - App-, Site-, Locale-, Currency- and Server Group-Specific

Most rewrite rules use their type, priority, name, and configuration. However, there are also parameters that define whether a rule is applicable or not.

The application, site, locale, currency, and server group rewrite rule parameters allow you to define custom configurations that apply to a particular rule configuration of a rule type. They act like a filter. Only if there is a match, the rule is applied.

Make sure that the more specific rules have a higher priority (higher number), because the priority defines the order in which the rules are applied. Otherwise, a more general rule may be applied when a more specific rule is wanted.

It is recommended to always have a general rule as a fallback, otherwise an invalid URL error may occur.

isApplicable Section in Rewrite Rule Configuration

For more information about the isApplicable method, see Cookbook - URL Rewriting | Create a New Rewrite Rule.

Example of urlrewriterules.xml - all available (rule is applicable) parameters

<!-- some rule -->
<rule type="some-available-type" priority="125" name="name of the rule for some-available-type">
  <locales>
    <locale>de_DE</locale>
    <locale>fr_FR</locale>
  </locales>
  <appurlids>
    <appurlid>appID1<appurlid>
    <appurlid>appID2<appurlid>
  </appurlids>
  <currencies>
    <currency>EUR</currency>
    <currency>GBP</currency>
  <currencies>
  <sites>
    <site>some-Site</site>
  <sites>
  <server-groups>
    <server-group>WFS<server-group>
  </server-groups>
  <configurations>
    ...
  </configurations>
</rule>

For examples, see the Cookbook - URL Rewriting | Recipe: App-, Site-, Locale-, Currency-Specific Rewrite Rules.