1 Introduction

Seen from a historical perspective, 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 using short, structured and readable URLs. In order to fulfill these requirements, Intershop provides four concepts to handle URLs.

1.1 Changelog

Intershop 7.4 introduces the following new features:

• Multiple host names in domainsplitting separated by spaces
• Defining abstract URL patterns (shortpathpattern) for local rules, domainsplitting or globally
• Configurations for alternative names for locale, currency and appurlid via domainsplitting configuration

Migration hints:

• Definition of a global parameter rules.shortpathpattern is necessary to enable the feature improved domain splitting, like

  urlrewrite.properties

  rules.shortpathpattern = /${group}/${domain}/${locale}/${appurlid}/${currency}${path}

• The parameters .hideDefaultApplicationID and .domainsplitExpandPattern are not supported anymore.
  Use rules.shortpathpattern instead.
• The use of domainsplitting.rule.<name>. is deprecated.
  Use rule.<name>. instead.

1.2 References

• Cookbook - URL Handling (valid to 7.7)
• Cookbook - URL Rewriting

2 URL Handling - Overview

The concept is divided into five parts covering: URL configuration, short links, URL rewriting, domain splitting and special link rewriting.

• Concept - URL Handling (valid to 7.7)#Short Links - Landing pages URLs like http:// www.example.com/summer-sale-2012/ are definable via the Commerce Management. This feature allows one-way links directing to the page of interest.
  
• Concept - URL Handling (valid to 7.7)#URL Configuration (formerly known as URL renaming) - Allows renaming the /INTERSHOP/<Service Type>/ part of a URL and is done via appserver.properties. From the customer's point of view, the renaming to /example/images/ (ServiceType = "static") is recommended. This feature can be configured in the appserver.properties.
• Concept - URL Handling (valid to 7.7)#URL Rewriting - With regard to readable and precise URLs, this feature can be used to create URLs like https:// www.example.com/Computers/Notebooks, replacing the large standard URLs like
  http:// www.example.com/INTERSHOP/web/WFS/PrimeTech-PrimeTechSpecials-Site/en_US/-/USD/ViewStandardCatalog-Browse?CategoryDomainName=PrimeTech-Computers&CategoryName=Notebooks.
  The rewriting defines two-way mapping rules that transform short URLs into the internally used long Intershop URLs and vice versa. The configuration is done using one or more urlrewriting.properties file(s).
• Concept - URL Handling (valid to 7.7)#Domain Splitting - In addition to URL rewriting, you can predefine 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. This way, URL rewriting rules can be much shorter as they contain less parameters. The definitions can be set in urlrewriting.properties files as well.
• Custom Link Rewriting - A short notation for creating storefront links to categories, products or other CMS pages.

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

Example:

2.2 Application-Wide URL Wrapping

In order to apply rules to every single URL in the application, there must be wrappers for each used link throughout the application. It is strongly recommended to use these functions at any place. Do not try to hard-code URLs. Whenever URL rewriting is enabled, these wrappers perform the URL transformation. The functionality is available for ISML templates, pipelets and through Java code.

2.2.1 ISML Templates

In ISML templates, the following ISML functions can be used to render links:

url(<Action>,<Parameters>) creates a link with the default port and protocol.

<a href="#url(action('ViewBasketHistory-Start'))#">View Basket History</a>

urlex(<protocol>, <port>, <Action>, <Parameters>) can be used to specify a specific protocol (http/https) or a specific port.

<a href="#urlex('https', '443', action('ViewProduct-Start'))#">View Product</a>

2.2.2 Pipelets

The CreateURL pipelet is used for creating rewritten links at pipeline level.

2.2.3 Java Code

For Java, there is a URLComposition implementation that can be instantiated to create a URL using the following code snippet:

Parameters params = new Parameters();
params.add("sku", "prod_1234");
Action action = new Action("ViewProduct-Start");
URLParameterSet urlParameters = new URLParameterSet();

URLComposer composer = getTemplateExecutionConfig().getURLComposer(); // recommended
String compactedURL = composer.createURL(true, "https", null, "443", action, urlParameters);

2.2.4 Storefront

Beginning with Intershop 7.3.1, there are two different components for displaying rewritten links on the storefront, without knowing the URL rewriting rules. A specific syntax is used that helps rendering links - "Navigation - Simple Link" (since 7.x) and "Common - Freestyle HTML Text" (since 7.3.1).

Within these components, the following code can be used to render different URLs. The parameters and the anchor are optional.

http://<url>?<parameters>#<anchor>
https://<url>?<parameters>#<anchor>
pipeline://<action>?<parameters>#<anchor>
page://<page_id>?<parameters>#<anchor>
product://<sku>?<parameters>#<anchor>
category://<category_id>@<domain>?<parameters>#<anchor>
image://<site-name/subfolder/file-name.extension>  // "image" introduced in IS 7.7

In the "Freestyle HTML Text", these links can be used as follows:

<ul>
  <li><a href="http://www.google.de">http | www.google.de</a></li>
  <li><a href="https://mail.google.com">https | mail.google.com</a></li>
  <li><a href="page://page.returnpolicy">page | return policy</a></li>
  <li><a href="product://10666805@PrimeTech-MasterRepository">product | A-DATA 750GB SH14</a></li>
  <li><a href="category://897@PrimeTech-PrimeTechSpecials-Telecommunication">category | Tablet PCs</a></li>
  <li><img href="image://inSPIRED-inTRONICS-b2c-responsive/teaser/home_teaser_1.jpg" alt="teaser"></li>  <!-- "image" introduced in IS 7.7 -->
</ul>

These links are converted to valid storefront URLs.

3 URL Configuration

URL configuration concerns the naming of prefix and service type in a standard URL.

3.1 Default URL Configuration Setting

The default URL prefix is INTERSHOP. The specified service type determines how different requests are handled. The (default) URL prefix and the service types are listed in the following table, together with their corresponding configuration parameter names.

Checking statistics on the Web Adapter uses the following URL: /INTERSHOP/wastatistics.

The URL configuration has no side effects. Hence, renaming in an SEO compliant manner is possible at any time.

3.2 Configuration Details

All configurations for URL configuration are done in the appserver.properties, which is read once during the application server start.

The appserver.properties include the following required parameters:

• intershop.urlmapping.urlPrefix is the basic parameter that defines the first adjustable part of the URL.
• Parameters following the schema intershop.urlmapping.<Service Type>.webadapter specify the names for the different service types.
• intershop.urlmapping.<Service Type>.appserver should not be changed. They allow merging this feature into different projects. Also, Intershop Studio uses these parameters to read the configuration.
• The parameters intershop.template.WebRootURL and intershop.template.HttpsWebRootURL are the parameters for accessing static content.

3.3 Debugging with Intershop Studio

Before debugging pipelines with Intershop Studio, please update to the latest version of Intershop Studio.

1. Open Debug Configurations | [your Pipeline debugging entry] | Server Configuration | Select/Edit.
2. In the field Servlet Path, specify the corresponding value of the appserver.properties key intershop.urlmapping.static.webadapter, which should be set to /is-bin/INTERSHOP.servlet by default.

4 Short Links

The purpose of short links is to shorten URLs by providing a pair of URLs. When a URL is called on the Web Adapter, it will try to resolve a short link source URL (comparing the called URL with the short link's source URL) and then propagate the call to its target URL. The target URL is actually set by replacing the matching "source URL" part with the target URL.

For marketing purposes, short URLs to a specific page are used, for example, providing a very catchy URL to a promoted product. Another scenario is to have a more convenient access to certain URLs.

Example:

The user may also provide just relative URLs, keeping them independent from the server.

As parts of the URL may depend on the server configuration, it is recommended to store short links in relation to their host names (bold marked).

This way you can enter the target links via the Commerce Management application as they appear upon browsing. The system will ensure that it is saved in a server-independent manner. Technically spoken, a relative representation is used with placeholders.

As a third way, target URLs can point to rewritten URLs (see Concept - URL Handling (valid to 7.7)#URL Rewriting).

As short links are typically marketing-driven, they also provide the ability of setting a validity period (i.e., start date and end date) during which the short link is valid. This can be coupled closely to the marketing period of a product (e.g., a promotion) providing a short link during this period. An additional feature is that the short link manager can decide how the source URL is routed to the target URL:

5 URL Rewriting

From the SEO perspective, a qualified URL is short and readable, as well as contains enough semantic information to describe the content of the address. Since the standard Intershop URLs do not match these criteria, they have to be rewritten.

5.1 Enabling URL Rewriting

URL rewriting can be activated for a storefront site using three different ways: the Central Administration Frontend (since 7.6 Organization Management), the SMC (since 7.6 System Management) or using site-specific preferences.

5.1.1 SMC or Central Administration Frontend

Logging into the SMC or OMA (formerly known as CAFE) - the interfaces are similar - enables the user to change the URL rewriting status as well as the "URL Rewrite Site Name".

To do so, navigate to Site Management | inSPIRED-inTRONICS-Site.

5.1.2 Site Preferences

Using the site preferences, the following parameters can be set: URLRewriting, URLRewriteHandler, URLRewriteSiteName. Developers and administrators can configure these settings using the Intershop Studio Site Explorer.
To do so:

1. Open the Site Explorer.
2. Select the site inSPIRED-inTRONICS-Site.
3. Choose Advanced Properties.
   

Changing the handler class or site name shortcut requires the server to be restarted, whereas toggling the URL rewriting status can be performed at run-time.

5.2 URL Rewrite Rules and Configuration

An initial set of rewrite rules is already deployed in the cartridge sld_ch_b2c_app, targeting the URLs for the demo storefront inTRONICS. This set of rules serves for demonstration purposes and can be reused as a starting point for defining project-specific rewrite rules.

Configuring

The fine tuning of URL rewrite rules can be done using the urlrewrite.properties files. These files are located in the following places:

<SERVER>\share\system\config\cluster\
<CARTRIDGE>\release\urlrewrite\

5.3 URL Rewrite Handler

Intershop provides a default URL Rewrite Handler implementation. This implementation defines URL rewriting via predefined pattern-matching and text processing rules (rule-based URL rewriting). Using this handler, existing storefronts can easily be optimized by simply defining URL rewrite rules in urlrewrite.properties files instead of providing Java rewrite code.

Projects in the past showed that all customer needs were met when using the default rewrite handler. Unless there are extraordinary requirements on URL definitions, a custom URL rewrite handler is not required. The assignment of a rewrite handler to a site is done by preferences that can be set in Intershop Studio.

5.3.1 Configuration Files

The default URL rewrite handler can use (multiple) urlrewrite.properties file(s) as input. These files can be located at different locations:

• Application server directory or
• Inside cartridges.

5.3.2 Settings Scopes

The urlrewrite.properties files contain settings at different levels (or scopes):

# Global settings: Slashes are replaced in all rules
rules.replaceSlashes = true
# Local rule "home" setting: Overrides the global setting of "replaceSlashes"
rule.home.replaceSlashes = false
# Global domainsplitting settings: verwriting the global settings for all domainsplitting rules
domainsplitting.host_de.replaceSlashes = false
# Local domainsplitting rule "home" overwrites the global domainsplitting setting
rule.domainsplitting.home.replaceSlashes = true

The following list describes the different scopes.

5.3.3 Global Settings

The following parameters can be used globally and locally as stated in the example. The settings hideDefaultApplicationID and domainsplitExpandPattern have been removed. The following has been newly introduced: shortpathpattern. Scopes can be rules. or rule.<name>..

5.3.4 Rule Configuration Parameters

Rules are defined by using the rule.<name>.<parameter> pattern.

# compact parameter
rule.<name>.select                  = ${action}
rule.<name>.selectMatch             = ^ViewHomepage-DisplayCachedHomepage$
rule.<name>.shortPath               = /start
# expand parameter
rule.<name>.shortPathMatch          = ^/start$
rule.<name>.longRequest             = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-DisplayCachedHomepage
# optional parameters to overwrite global settings
rule.<name>.shortpathpattern        = ${path}-${group}-${domain}-${locale}-${appurlid}-${currency}
rule.<name>.debug                   = true
rule.<name>.replaceSlashes          = false
...

Algorithm for compacting
The .select part is matched against .selectMatch. In case of success, the long URL is transformed into the .shortpath by optionally using the .shortpathpattern.
Algorithm for expanding
The short URL is matched against .shortPathMatch. In case of success, the short URL is transformed into the .longRequest.
Optional parameters
Global parameters like .debug, .replaceSlashes etc. can be overwritten by each rule.

5.3.5 Inheritance

Rewrite rules can be overwritten. The look-up for urlrewrite.properties files is similar to the look-up for templates and pipelines. The URL handler checks all cartridges in the order of the cartridgelist.properties to build up a stack of rules. Rules in higher-level cartridges override rules with the same names in lower-level cartridges properties files. rules.clear=true will remove previously loaded rules.

5.4 Simple URL Rewriting Rules

As a default homepage rule, you may start with linking the http:// www.example.com/ URL to the ViewHomepage-DisplayCachedHomepage pipeline.

# Compacted URL: http://www.example.com/

rule.homepage.select            = ${action}
rule.homepage.selectMatch       = ^ViewHomepage-DisplayCachedHomepage$
rule.homepage.shortPath         = /
rule.homepage.shortPathMatch    = ^/$
rule.homepage.longRequest       = /WFS/PrimeTech-PrimeTechSpecials-Site/en_US/-/EUR/ViewHomepage-DisplayCachedHomepage 

When domain splitting is not enabled, all other rules should have the following parameters stored in the URL: group, domain, locale, appurlid and currency.

# Compacted URL: http://www.example.com/sitemap-A-Z-PrimeTechSpecials-WFS-en_US-myApp-USD

rule.sitemap.select           = ${action}/${p.Range}/
rule.sitemap.selectMatch      = ^ViewSitemap-BrowseCategoryRange/.+/$
rule.sitemap.shortPath        = /sitemap-${p.Range}${d.RenderType}-${domain}-${group}-${locale}-${appurlid}-${currency}
rule.sitemap.shortPathMatch   = ^/sitemap-([A-Z|0-9]-[A-Z|0-9])-([\\w\\-]+)-([\\w]+)-([\\w]+)-([\\w\\-]+)-([\\w]+)$
rule.sitemap.longRequest      = /$3/$2/$4/$5/$6/ViewSitemap-BrowseCategoryRange?Range=$1&RenderType=CategoryRange 

Due to the latest rework, the latter rule can be simplified as follows. Therefore a global pattern is defined through the use of rules.shortpathpattern. This global pattern contains a ${path} placeholder representing the part which rules are then matched.

# Compacted URL: http://www.example.com/sitemap-A-Z-PrimeTechSpecials-WFS-en_US-myApp-USD

rules.shortpathpattern = ${path}-${domain}-${group}-${locale}-${appurlid}-${currency}
## alternately
# rules.shortpathpattern = /${domain}/${group}/${locale}/${appurlid}/${currency}${path}

rule.sitemap.select           = ${action}/${p.Range}/
rule.sitemap.selectMatch      = ^ViewSitemap-BrowseCategoryRange/.+/$
rule.sitemap.shortPath        = /sitemap-${p.Range}${d.RenderType}
rule.sitemap.shortPathMatch   = ^/sitemap-([A-Z|0-9]-[A-Z|0-9])$
rule.sitemap.longRequest      = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewSitemap-BrowseCategoryRange?Range=$1&RenderType=CategoryRange

5.4.1 Semantic Information: Object Path Variables and Query Parameters

User-friendly URLs contain semantic information like the product's display name. This additional information can be located in the dictionary. The following objects are available in the standard version: ProductBO, CategoryBO or Pagelet. Further objects can be added. The rule-based URL rewrite handler allows to access that information via default Intershop Object Path variables. The example below uses a custom article name that must be placed in the dictionary whenever this rule is active. A rule takes effect when selectMatch matches the select(ed) values.

# standard:  http://..../ViewProduct-Start?SKU=SKU_1234
# rewritten: http://www.example.com/product-details/SKU_1234/car_oel_filter_green
domainsplitting.rule.productdetails1.select            = ${action}/${p.SKU}
domainsplitting.rule.productdetails1.selectMatch       = ^ViewProduct-Start/([a-zA-Z0-9\\_\\-]+)$
domainsplitting.rule.productdetails1.shortPath         = /product-details/${p.SKU}/#CustomArticleName#
domainsplitting.rule.productdetails1.shortPathMatch    = ^/product-details/([a-zA-Z0-9\\_\\-]+)/([a-zA-Z0-9\\_\\-]+)$
domainsplitting.rule.productdetails1.longRequest       = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewProduct-Start?SKU=$1

Alternatively, semantic information can be added as a query parameter (${p.param_name}). This approach comes with less flexibility for the rules and can lead to complicated (not rewritten) URLs and a lower cache performance in the production environment. Irrespective of the chosen approach, the developer who introduces new business logic and new URLs should always take care of providing semantic information for URL rewriting.

# standard:  http://..../ViewProduct-Start?SKU=SKU_1234
# rewritten: http://www.example.com/product-details/SKU_1234
domainsplitting.rule.productdetails2.select            = ${action}/${p.SKU}/
domainsplitting.rule.productdetails2.selectMatch       = ^ViewProduct-Start/([a-zA-Z0-9\\_\\-]+)/$
domainsplitting.rule.productdetails2.shortPath         = /product-details/${p.SKU}
domainsplitting.rule.productdetails2.shortPathMatch    = ^/product-details/([a-zA-Z0-9\\_\\-]+)$
domainsplitting.rule.productdetails2.longRequest       = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewProduct-Start?SKU=$1 

5.4.2 Extended Category Path Handling

Since version Enfinity Suite 6.6, categories provide additional methods for URL rewriting.

6 Domain Splitting

Basically, the domain splitting feature allows for host name parameter mapping. Domain splitting rules assume that parameters like group, domain, locale, appurlid and currency are fixed to a given hostname. Therefore, certain standard parameters can be applied whenever the hostname matches www.example.com in the following example.

domainsplitting.example_us.host = www.example.com
domainsplitting.example_us.currency = USD
domainsplitting.example_us.appurlid = -
domainsplitting.example_us.locale = en_US
domainsplitting.example_us.domain = PrimeTech-PrimeTechSpecials-Site
domainsplitting.example_us.group = WFS

Host name parameter mappings should be located centrally in /share/system/config/cluster/urlrewrite.properties (no reloading supported). For testing purposes, they can also be defined in cartridge-specific urlrewrite.properties files (reloading supported).

If there is another instance of example located in Germany, for example, the following additional domain splitting preferences can be set up:

domainsplitting.example_de.host = www.example.de (or *de*.example.com)
domainsplitting.example_de.currency = EUR
domainsplitting.example_de.appurlid = -
domainsplitting.example_de.locale = de_DE
domainsplitting.example_de.domain = PrimeTech-PrimeTechSpecials-Site
domainsplitting.example_de.group = WFS 

The resulting URL rewriting rules have domainsplitting. as prefix and are much more readable. Standard parameters can be accessed using ${parameter_name}.

domainsplitting.rule.register.select                  = ${action}
domainsplitting.rule.register.selectMatch             = ^ViewUserAccount-ShowLogin$
domainsplitting.rule.register.shortPath               = /register
domainsplitting.rule.register.shortPathMatch          = ^/register$
domainsplitting.rule.register.longRequest             = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewUserAccount-ShowLogin 

This way, URLs can be shortened drastically by hiding information via DNS name. This naming strategy is search engine friendly: human readability is improved and higher ratings in search engines can be expected.

6.1 Improved Domain Splitting

The standard domain splitting has been enhanced to support three new features:

• Concept - URL Handling (valid to 7.7)#Multiple Host Names
• Concept - URL Handling (valid to 7.7)#URL Short Path Patterns
• Concept - URL Handling (valid to 7.7)#Path Variable Alternatives

6.1.1 Multiple Host Names

It is possible to define multiple host names for one domain splitting set. This way, multiple host names can share the same settings, which reduces the number of domain splitting configurations. The different host names must be separated by spaces.

domainsplitting.host1.host=www.example.com test-example dev-example.local

Another improvement is the definition of host names which now may include port numbers. This was not possible before with URL rewriting:

domainsplitting.host1.host=www.example.com:81 www.example.com:444

For backward compatibility, the following plain host name still works by ignoring the actual port:

domainsplitting.host1.host=127.0.0.1

6.1.2 URL Short Path Patterns

Currently, the default rewritten URLs for the inTRONICS channel may have the following style:

[protocol]://[hostname][:port]/contact-${domain}-${group}-${locale}-${appurlid}-${currency}

Here, the suffix is always the same:

-${domain}-${group}-${locale}-${appurlid}-${currency}

and the actual path segment is:

/contact

This feature aims at declaring a master pattern for each path section of a URL like, for example:

rules.shortpathpattern=${path}-${domain}-${group}-${locale}-${appurlid}-${currency} 

Following this master pattern, all default parameters (e.g., domain, group, currency, ...) can be extracted initially. After this, the existing standard URL rewriting can be performed on the extracted path section:

/contact 

6.1.2.1 Regular Expressions

All placeholders have a default regular expression set as shown in the table below:

They can be overridden by following the pattern:

# default  pattern:   ${placeholdername}
# override pattern:   ${placeholdername:(regex)}

# limiting a placeholder to certain values (e.g. en_US, de_DE or fr_FR)
domainsplitting.host1.shortpathpattern=${locale:(en_US|de_DE|fr_FR)}

# path must start with a leading slash (/) - recommended for fallback pattern
domainsplitting.host1.shortpathpattern=${path:(\\/.*)}

# currency must contain exactly 3 characters, _ or digits
domainsplitting.host1.shortpathpattern=${currency:([A-Z]{3})}

# group contains up to 3 characters, _ or digits
domainsplitting.host1.shortpathpattern=${group:([\\w]{,3})}

6.1.2.2 Different Levels of Defining Short Path Patterns

When a rule is compacted or expanded, a look-up for the short path pattern is performed. This look-up uses the first found shortpathpattern to match.

The following sections list these levels in the order of their look-up priority:

1) Local- for each rule individually
A rule may provide its own shortpathpattern.

rule.home.select            = ${action}
rule.home.selectMatch       = ^ViewHomepage-DisplayCachedHomepage$
rule.home.shortPath         = /index
rule.home.shortPathMatch    = ^/index$
rule.home.longRequest       = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-DisplayCachedHomepage
rule.home.shortpathpattern  = /${locale}${path}-${domain}-${group}-${appurlid}-${currency}

2) Domain specific- specific for given host names
Definition of a short path pattern being active when domain splitting settings match. Here, the short path pattern needs to provide the parameters that are missing in the current domain splitting configuration (e.g., locale).

domainsplitting.host_1.host = www.example.de local.test-example.de
domainsplitting.host_1.shortpathpattern = /${locale}${path}
domainsplitting.host_1.currency = USD
domainsplitting.host_1.appurlid = -
### definition of locale is not necessary! - it is defined through the shortpathpattern
### domainsplitting.host_1.locale = en_US
domainsplitting.host_1.domain = inSPIRED-inTRONICS-Site
domainsplitting.host_1.group = WFS

3) Global- applying for all rules
This pattern is used when none of the above (domain specific or local) shortpathpattern is found:

# global URL pattern as ultimate fallback if no other shortpathpattern are available
rules.shortpathpattern = ${path}-${domain}-${group}-${locale}-${appurlid}-${currency}

# example rule
rule.home.select            = ${action}
rule.home.selectMatch       = ^ViewHomepage-DisplayCachedHomepage$
rule.home.shortPath         = /index
rule.home.shortPathMatch    = ^/index$
rule.home.longRequest       = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-DisplayCachedHomepage

The global shortpathpattern needs to provide the following parameters: domain, group, locale, appurlid (if different from -), and currency, whereas a domain-specific shortpathpattern may provide only the missing parameters.

6.1.3 Path Variable Alternatives

A rewritten URL, following the short path pattern /${locale}/${appurlid}${path}, may lead to a URL like this:

http:/example.ch/de_CH/mobileapp/contact 

This URL is not SEO-compliant, since the country code is included twice (ch is part of the host name and part of the URL path) and the mobile application could be abbreviated to "mobile". A better way to present this information would be the following URL:

http:/example.ch/de/mobile/contact 

To this end, it is possible to provide alternative replacements for locale, appurlid and currency. The mappings can be defined individually for each domain splitting. An example is listed in the following (see mapping comments).

# server for switzerland
domainsplitting.host_1.host = example.ch
# fixed currency
domainsplitting.host_1.currency = CHF
# fixed server group
domainsplitting.host_1.group = WFS
# fixed site
domainsplitting.host_1.domain = inSPIRED-inTRONICS-Site
# mappings for different apps
domainsplitting.host_1.appurlid.1.value = mobileapp
domainsplitting.host_1.appurlid.1.replacement = mobile
domainsplitting.host_1.appurlid.2.value = tabletapp
domainsplitting.host_1.appurlid.2.replacement = tablet
# mappings for different locales in switzerland
domainsplitting.host_1.locale.1.value = de_CH
domainsplitting.host_1.locale.1.replacement = de
domainsplitting.host_1.locale.2.value = it_CH
domainsplitting.host_1.locale.2.replacement = it
domainsplitting.host_1.locale.3.value = fr_CH
domainsplitting.host_1.locale.3.replacement = fr
# the new introduced shortpathpattern
domainsplitting.host_1.shortpathpattern = /${locale}/${appurlid}${PATH}

Using these configuration options, the following rewritten URLs are configurable:

http:/example.ch/de/mobile/contact
http:/example.ch/it/tablet/contact
http:/example.ch/fr/mobile/contact

7 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 a simple-to-use syntax was defined and is recognized inside content created with the TinyMCE text editor. The syntax of standard URLs is used whereby each link has a specific protocol set. So 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 custom links currently available are described in the table below.

In order 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 urlrewriting.properties below).

rule.cat53.select          = ${action}/#CategoryBO:Name#/
rule.cat53.selectMatch     = ^ViewStandardCatalog-Browse/.+/$
rule.cat53.shortPath       = /#CategoryBO:CatalogCategoryPath:ReversePath:DynamicPath#${d.CategoryName}${d.CatalogID}${d.CatalogCategoryID}
 ..
rule.psku3.select                 = ${action}/#ProductBO#/
rule.psku3.selectMatch            = ^ViewProduct-Start/.+/$
rule.psku3.shortPath              = /#ProductBO:Name#-zid#ProductBO:ID#
 ..
rule.page99-page.select           = ${action}/#PageletEntryPoint:DisplayName#/
rule.page99-page.selectMatch      = ^ViewContent-Start/.+$
rule.page99-page.shortPath        = /#PageletEntryPoint:DisplayName#-cms-${p.PageletEntryPointID}

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

<ISSet name="mylink" value="category://PCSystems@PrimeTech-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://PCSystems@PrimeTech-Computers?ref=summersale#specialconditions).

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

8 Parameter Whitelisting

Parameter whitelisting has been introduced to improve the page cache hit ratio in situations where unnecessary request parameters (from the start nodes' point of view) hit the Web Adapter and enforce the application server to render identical pages several times.

There are now two ways to enforce parameter whitelisting for pipeline start nodes:

• Set pipelines start nodes to be strict and define the optional and mandatory parameters for these pipelines.
• Define whitelisted parameters as part of the configuration file pipelinewhitelistparameters.properties (no need to overwrite a pipeline start node anymore).
  The configuration of a start node in pipelinewhitelistparameters.properties will always overwrite the configuration within the pipeline XML.

8.1 Configuration

To turn on the parameter whitelisting, check the urlrewrite.properties for the following setting:

# enforce whitelisted parameters
# 1. defined within pipelinewhitelistparameters.properties
# 2. setup for the pipeline startnode
# This will remove unnecessary URLquery parameters from the request to allow the page
cache to work properly
#
rules.restrictToWhitelistedParameters = true

8.1.1 Approach 1: Modify Pipeline Start Nodes

Configure the valid parameters for the start nodes for which the feature should be used.

8.1.2 Approach 2: Configure Whitelisted Parameters Using Property File

Configure the mandatory and optional paramaters of your start nodes in the file pipelinewhitelistparameters.properties according to the following example:

######################################################################################################################
##
## Config file that lists optional & mandatory parameters for pipeline startnodes.
## (used in PipelineWhitelistParameterProvider - which currently only used for rewritten URLs)
##
## syntax:
## pipelinewhitelistparameter.<Pipeline>-<StartNode>.parameters.[mandatory|optional] = <parametername1>[/<parametertype1>], <parametername2>[/<parametertype2>], ...
##
## example:
## pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String
## pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.optional = Param3/java.lang.String, Param4/java.lang.String
##
######################################################################################################################
pipelinewhitelistparameter.Whitelist_test-StrictMandatoryParams.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String

pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String
pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.optional = Param3/java.lang.String, Param4/java.lang.String

pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParamsIncludingArrays.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String[]
pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParamsIncludingArrays.parameters.optional = Param3/java.lang.String, Param4/java.lang.String[]

You can either use the cluster wide configuration file in <eserver>/share/system/config/cluster/pipelinewhitelistparameters.properties or - in case it has to be app-specific or domain-specific - in one of your project cartridges: <cartridge>/staticfiles/cartridge/config/pipelinewhitelistparameters.properties.

8.2 Error Handling

In case of an error, the restriction of whitelisted parameters does not prevent the request from being processed. That is, if a problem occurs, it will only be visible in the warning or error log of the server.

There are two possible errors:

8.2.1 Type of Parameter Is not Valid

The type of the parameter is set to a type that is not compatible with the passed request parameter (e.g., the parameter type is java.lang.Integer).

Precondition:

• Pipeline parameter type checking is activated via the property intershop.pipelines.strict.CheckParameterTypes (default location: appserver.properties, default value: false) which is set to true and the value passed through the request is a string that cannot be converted to an integer, e.g., text).

  # performs type checking on the required and
  # optional keys of a strict subpipeline
  intershop.pipelines.strict.CheckParameterTypes=true

Result:

• Only the mentioned whitelisted parameters will be passed through to the requested pipeline.
• Additionally, a message will be sent to the error log.

8.2.2 Mandatory Parameter Is not Part of the Request

A parameter that is marked as mandatory is not part of the request.

Result:

• Parameters will be sent through to the requested start node.
• Additionally, a message will be sent to the warning log indicating that a mandatory parameter is missing.

8.3 Debugging

Web Adapter: Configure the trace option to directly visualize the effect of whitelisted parameters.

$ vim /eserver1/share/system/config/cluster/webadapter.properties

############################################################################
## Tracing and Control
##
## Set a 'simple, short and unique enough' command prefix to enable the
## feature. In production systems, restrict access. Like:
##    <eserver>/httpd/conf/extra/httpd-webadapter.conf:
##       <LocationMatch ;wa_>
##          Order  Allow,Deny
##          Allow  from 10.0.0.0/8
##       </LocationMatch>
##
## When enabled, see the built-in help for more details
##    http://.../INTERSHOP/web/;wa_help

ctl.commandPrefix = wa_

Call the start node that whitelisted parameters have been configured for using the "trace option":

http://localhost/Cameras-Camcorders/1421-PrimeTechSpecials-WFS-en_US-USD;wa_trace?dummy_parameter

Alternatively, you can use wa_help to get an overview of the Web Adapter trace option:

http://localhost/Cameras-Camcorders/;wa_help;wa_trace

9 Diagrams

The different ways of compacting and expanding URLs are visualized in the following two sequence charts:

The following diagram shows the algorithm performed inside the rule class.