Hostname Aliases

A hostname alias is a way of defining alternative names for an existing website URL. You must set up and register the DNS and domain names to use these extra hostnames in aliases.

Merchants create hostname aliases for the following reasons:

Production Instance Hostname

The Production instance hostname is similar to production.realm.web.demandware.net, with an IP address such as 100.100.100.1. This hostname is used to access Business Manager and to connect to UX Studio, WebDav, and other development connections. While you can use it to view the storefront, customers must not use it to access the storefront because it isn't best practice for SEO, doesn't promote brand marketing, and is not secure.

Accessing the Storefront Homepage with Your Hostname

If you want your own hostname, such as www.mydomain.com, to directly access the storefront homepage and link to an SSL certificate, you must do the following:
  1. Purchase a domain, and configure your DNS (Domain Name Service) for that domain to define a hostname.
  2. Obtain an SSL certificate containing that name, or multiple names from a certificate authority to be used on your storefront. Each certificate installed needs a unique IP address. The first certificate installed shares the IP address with the B2C Commerce hostname. For example, if the B2C Commerce hostname is production.realm.web.demandware.net and the IP address is 100.100.100.1, the first certificate installed gets the IP address 100.100.100.1. If a second certificate is installed it gets a new IP address, such as 100.100.100.2. You must also ensure that your DNS is updated with the IP of the corresponding hostnames.
  3. Add the hostname to your hostname alias file as part of a rule.
  4. If your host is listed in Business Manager: site > SEO > Aliases, and only one locale is used for the site, you can create links to the home page that are search-friendly, because they don't require additional information to determine the locale.

Terminology

URL syntax in this topic uses the following terms:

Element Description
Entered URL URL originally entered by the customer.
Host Name Part of the URL that indicates the host name. For example: www.sitegenesis.com.
Site path Optional slash-delimited URL segment that is appended to the host name. The site path enables B2C Commerce to differentiate between multiple sites using the same host name. For example, the site path might be UK for a site used in the United Kingdom (http://www.sitegenesis.com/UK) or US for a site used in the United States (http://www.sitegenesis.com/US). A site path can include multiple slashes and can be anything you want (one/two/three/N).
Locale Optional locale identifier that can be specified in mapping rules. A locale configured in a mapping rule will be used if the hostname (or the hostname plus the site-path) matches the beginning portion of the entered URL. For each entered URL, B2C Commerce determines the correct locale by examining the hostname alias files, looking for a corresponding mapping rule, and falling back to the default locale configured for the site if a corresponding mapping rule isn't found.
Path Part of the URL that indicates the path to the page. The path is logically appended to the locale (if there is one), to the site path (if there is one), or to the host name. For example: /womens/accessories/promopage.html.

Hostname Alias File

The hostname alias file defines what hostnames/domains are supported by B2C Commerce. It also defines what pipelines or controllers are triggered for a specific URL. This file enables a Production instance with multiple IP addresses to provide different storefront content for multiple domains per site or multiple sites per realm. This file is required for a Production instance launch.

For more specific information on mappings, see URL Redirects.

You can create a set of rules that controls how different URLs are processed by B2C Commerce. These rules use the JSON (Java Script Object Notation) format (see Json.Org).

The alias file should include the proper https-host. The https-host must reflect the host name.

For example, www.mysite.com maps as:

{ "__version": "1", "settings": { "http-host": "www.mysite.com", "https-host": "www.mysite.com" } }

For .demandware.net hosts, use the "-" URL in the alias, for example:

{ "__version": "1", "settings": { "http-host": "development-web-mysite.demandware.net", "https-host": "development-web-mysite.demandware.net" } }

See Configuring a Hostname Alias.

You can also configure your hostname alias file to avoid multiple entry points and duplicate URLs, thus increasing the SEO value of your storefront site. See the Mapping Rule Syntax section below.

For additional information on how B2C Commerce constructs URLs, see URL Rules URL Syntax.

Note: The file format allows colons for property value assignments instead of equal signs. Although equal signs are allowed for backward compatibility, colons are recommended because they are valid JSON and don't cause problems if you choose to validate your file in an external JSON debugger.

File Format

The following code shows the basic file format:

{"__version": "1", 
"settings": { 
     "http-host": "httphostname", 
     "https-host": "httpshostname", 
     "site-path": "sitepath", 
     "default" : "defaultValue",
     "site-path-trailing-slash" : "yes", } 
"hostName1": [
   { mappingRule1 },
   { mappingRuleN }
 ],
"hostNameN": [
   { mappingRule1 },
   { mappingRuleN }
]
}

The parameters are as follows:

Parameter Description
version Required. Currently the value of this property must be 1. This value indicates the syntax version of the file. If this is changed to any other number, all entries are ignored.
settings*

Optional. When you set this property, you can specify the following:

  • httpHostName: preferred HTTP hostname, for example, www.sitegenesis.com.
  • httpsHostName: preferred HTTPS hostname, for example, www.sitegenesis.com. This setting is required if you want your site to be accessible through a secure channel.
  • sitePath: slash-delimited URL segment that logically extends the httpHostName and the httpsHostName (for example, EU) to help B2C Commerce differentiate multiple sites using the same hostname.
  • site-path-trailing-slash: Optional. A trailing slash is added (or not) to the redirected site path. See the example below.
  • defaultValue: boolean value (true|false) indicating whether the site should be the default site used for the host name if the entered URL doesn't contain a matching site path, for example, if the URL is a hostname-only URL without a path, such as http://www.sitegenesis.com. If you do not specify defaultValue, it's implicitly set to false. If the entered URL omits a site path but still includes a path after the hostname, for example, www.sitegenesis.com/mens, B2C Commerce uses the site whose defaultValue is true to handle the request.
Note: You don't have to set defaultValue to true to handle hostname-only requests. For example, for a site, you can omit the sitePath and provide only the httpHostName and the httpsHostName values.
hostName Hostname in the entered URL. You can have multiple host names, enabling the site to handle requests for multiple host names. For each host name, you can include multiple mapping rules.
*The settings property works only when there is one primary domain on a site, to which all other hostnames redirect. If the site supports multiple domains or hostnames, it's best to leave settings undefined and comment this entire section out. You should use this property if you want all of your sites to use the same host.

File Example

The following code represents a simple alias file to use on a Production instance. Every Production alias file must include the production.demandware address for your Production instance and your own DNS hostname address. The production.demandware address can also include the realm or name of a partner who is implementing the site.
{
    "__version": "1",

    "www.mybrand.com" : [{"pipeline": "Home-Show" }],

    "production.demandware.net" : [{"pipeline": "Home-Show" }],

    "mybrand.com": [{"host": "www.mybrand.com", "path":"/"}]

}

Mapping Rule Overview

There should be at least one mapping rule in the alias file for every hostname or domain name for which you have a storefront content, and that has an IP address in your DNS that corresponds to one of the IP addresses of the production instance. For example:
"www.mybrand.com" : [{"pipeline": "Home-Show" }],
For some host names or common base domain names, a redirect to the proper hostname is configured. This lets the site accept connections for the name, but redirect or change the URL to a different hostname more appropriate for the site. This is typically used to force a visitor to a hostname with a corresponding SSL certificate. For example:
"mybrand.com": [
{ "host": "www.mybrand.com", "path":"/" }]
The alias file can also be used to direct users to a specific pipeline or landing page based on the hostname entered in the URL. This enables a single site to host micro sites for other domains, and is more typically used for calling alternative cartridge pipelines or controllers for use in applications such as mobile applications, with hostnames such as m.mybrand.com.
{
  "outlet.mybrand.com": [
    {
      "pipeline": "Search-Show",
      "params": { "cgid": "category-subcategory-outlet" }
    }
  ],
  "m.mybrand.com": [
    {
      "pipeline": "mHome-Show"
    }
  ],
  "www.mybrand.com": [
    {
      "if-agent-contains": ["iphone", "ipod", "android"],
      "host": "m.mybrand.com"
    }
  ]
]

When using a filter such as if-agent-contains, the JSON format doesn't allow an ELSE statement inside a code block; it only executes the one line host:, so you need another block for www to handle regular browsers that do not match mobile.

Warning:

If the hostname alias file contains a JSON error, Business Manager notifies you of the error, but saves your changes to the file. At run time, however, the file isn't used if an error exists inside it. You should Debug the File using a separate tool to ensure that it's valid before you save it in Business Manager.

In previous versions, you set the http and https config for aliases in the Settings tab under Manage Sites. This tab is now obsolete. However, it still exists in Business Manager to support legacy implementations. If there is data in the fields in the Manage Sites Settings tab in addition to the JSON format alias file, the URLUtils() method behaves problematically. The Settings tab fields must be blank for a JSON alias file to be used.
Note: If you are migrating from the legacy implementation, changes to the settings don't take effect until an alias file for the corresponding site is saved. After removing data from the Settings tab, you must navigate to SEO, open the alias file, and save it to activate your changes.
Important:

It is not possible to set up a URL redirect or mappings for the following paths because the keywords dw, _dw, and s are reserved by B2C Commerce.

http://hostname/dw
http://hostname/_dw
http://hostname/s

Mapping Rule Syntax

Each mapping rule is defined by a set of attributes and looks like the following:

{
   "www.my-host.com":[{"pipeline":"Home-Show", "apply-to-host-only-request-with-params":"true"}] 
   "name": "mobile",
   "if-agent-contains": ["iphone","ipod"],
   "if-site-path": "DE",
   "host": "m.shop.com",
   "path": "index.html"
   "pipeline": "Summer-Start",
   "locale": "de",
   "params": {...},   
}

The parameters are as follows:

Parameter Description
apply-to-host-only-request-with-params

Optional. Using this parameter, you can control B2C Commerce behavior using the configuration in your aliases file, shown as follows, and perform hostname redirects for these requests directly:

"apply-to-host-only-request-with-params": "true"
When perform hostname redirects for these requests directly, B2C Commerce retains the request parameter and inserts the configured parameter in the hostname destination URL. When the request parameter and the configured parameter identifier are equal, the request parameter is preferred. See the examples below.

See Creating Home Page Links.

See Dynamic Mappings.
description

Optional. Define if B2C Commerce adds a trailing slash for generated URLs ending with a site path (for example, if using the B2C Commerce Script API dw.web.URLUtils.home()).

If defined yes or no, B2C Commerce automatically redirects incoming requests to the configured site path.

entry-point-destination Optional. Use with entry-point-pipelines to automatically redirect requests to avoid duplicate home page URLs.
entry-point-pipelines Optional. Use with entry-point-destination to automatically redirect requests to avoid duplicate home page URLs. Entry point pipelines can point to controllers and pipelines.
host

Optional. The name of the host to which the request is redirected.

Note: When configuring a hostname redirect, you typically use a rule like this: {"host":"my.host.com", "path":"uk"} or {"host":"my.host.com", "pipeline":"Home-Show"}. When you have a path and pipeline, the redirect is unclear because requests with old-hostname + path are redirected to this new-hostname + path, which is used for host-only requests. So, when you have these two parameters, the pipeline is preferred.
if-agent-contains Optional. An IF condition to indicate that the following rule is only executed if the attribute condition is met. The attribute condition is an optional list of strings. If the attribute isn't provided, the rule is always selected. This is intended to allow redirects to different URLs for different devices.
if-site-path

Optional. When this property is set, B2C Commerce checks its value against the site path in the entered URL, looking for a match. If it finds a match, B2C Commerce uses the mapping rule. However, in this case, B2C Commerce recognizes only the name, locale, pipeline, and params properties. It ignores the host, path, and if-agent-contains properties.

This property is also checked when B2C Commerce generates storefront URLs. For URL generation, B2C Commerce uses the first mapping rule that matches the current hostname and locale. If the matching mapping rule specifies a value for the if-site-path property, the site path is added to the generated URL.

Note: The if-site-path and site-path parameters are only valid in the corresponding section, where site-path is a setting and if-site-path is a hostname rule. B2C Commerce generates and consumes URLs based on the configured if-site-path or site-path.
locale Optional. The locale to use when mapping to a pipeline or to a site path.
Name Optional. The name for the rule.
params Optional. Parameters to add to the pipeline.
path Optional. The path that the customer is redirected to via a permanent 301 redirect. To redirect the customer, B2C Commerce constructs a URL by appending the value of the path property to the value of the host property. However, if the host property isn't configured, B2C Commerce ignores the path property. Also, B2C Commerce adds the value of the path property to the value of the host property only if the entered URL is a hostname-only request; otherwise, B2C Commerce adds the path extracted from the request URL to the value of the host property.
pipeline Optional. A pipeline triggered by the hostName which is used if no host is provided. Pipeline rules are only used if no host is supplied. You can use the locale and params syntax to specify a locale and parameters for the file.
site-path-trailing-slash Optional. A trailing slash is added (or not) to the redirected site path. See the example below.

Examples

Example 1: Controlling the Site Path Trailing Slash

You can control the site path trailing slash for each site path with the site-path-trailing-slash setting.

Start by configuring the preferred HTTP/HTTPS site hostname, as follows:

"settings" : { "http-host" : "www.your-http-hostname.com", "https-host" : "www.your-https-hostname.com",
 "site-path": "en",
 "site-path-trailing-slash" : "yes" } 

Then define the hostname rules, as follows:

"www.your-hostname.com" : [
 { "locale" : "default" },
 { "if-site-path": "en", "site-path-trailing-slash" : "yes", "locale" : "en" },
 { "if-site-path": "de", "site-path-trailing-slash" : "no", "locale" : "de" } ] 

Requests are automatically redirected as shown here:

from to
www.your-http-hostname.com/en redirects www.your-http-hostname.com/en/
www.your-https-hostname.com/en redirects www.your-https-hostname.com/en/
www.your-hostname.com/en redirects www.your-hostname.com/en/
www.your-hostname.com/de/ www.your-hostname.com/de
Note: If you don't define this configuration, URLs are generated without a site path and no redirect is made.

Example 2: using the apply-to-host-only-request-with-params setting

This attribute enables you to forward hostname requests with parameters to the configured pipeline, for example:

"www.my-host.com":[{"pipeline":"Home-Show",
"apply-to-host-only-request-with-params":"true"}] 

This example forwards the requests www.my-host.com/ and www.my-host.com/?param=aValue to the Home-Show pipeline and preserves the original URL parameters.

Performing hostname redirects Directly

Using this parameter, you can perform hostname redirects for these requests directly. B2C Commerce retains the request parameter and inserts the configured parameter in the hostname destination URL. When the request parameter and the configured parameter identifier are equal, the request parameter is preferred.

This is the configuration in the alias file:

"www.your-hostname.com" :
[ { "host": "www.your-other-hostname.com", "path": "/", "params" : {"cfgParam":"aOtherValue"}} },
 { "apply-to-host-only-request-with-params": "true" }]

With this configuration, the following request:

www.your-hostname.com/?reqParam=aValue

Is redirected to the following:

www.your-other-hostname.com/?reqParam=aValue&cfgParam=aOtherValue

Example 3: integrate default HTTP and HTTPS host Names

The following example configures the main HTTP and HTTPS hostnames for the production instance. The settings section is optional.

"settings": {
       "http-host": "www.sitegenesis.com",
       "https-host": "secure.sitegenesis.com"
       }
],

Example 4: Redirect from Alternate URL to Preferred Domain

The following example is a rule that redirects the alternate URL sitegenesis.com to the preferred domain. If a customer enters sitegenesis.com as their URL (http://sitegenesis.com/*), where * is any path, they are redirected via a 301 redirect to http://www.sitegenesis.com/*.

"sitegenesis.com": [
       {
       "host": "www.sitegenesis.com",
       }
],

Example 5: Redirect from Misspelled URL to Preferred Domain

This example shows redirect from the misspelled URL sitegensis.com to www.sitegenesis.com. If a customer enters sitegensis.com as their URL (http://sitegensis.com/*) they are redirected via a 301 redirect to www.sitegenesis.com.

"sitegensis.com": [
       {
          "host": "www.sitegenesis.com",
       }
],

Example 6: Use Preferred Locale with Localized Host Name

This example shows how to associate locale with a localized URL www.sitegenesis.de.

"www.sitegenesis.de": [
       {
          "locale": "de_DE",
       }
],

Example 7: Redirect from Landing Page Link to Category

This example shows a hostname-only URL http://electronics.sitegenesis.com/ that results in a call to the Search-Show pipeline with a category ID parameter of electronics. This can be used in marketing emails to direct a customer to a specific category or page.

"electronics.sitegenesis.com": [
       {
         "pipeline": "Search-Show",
         "params" : {"cgid"="electronics"}
       }
],

Example 8: redirect based on client device

Host redirect is based on the user agent header. With each rule, it's possible to associate precondition based on content of "user-agent" http header. In the example below an HTTP requests with "User-Agent" header containing "iPhone" or "iPod" will be redirected (301) to apple.sitegenesis.com and those with "blackberry" to bb.sitegenesis.com.

"www.sitegenesis.com": [
      {
         "if-agent-contains": ["iphone","ipod"],
         "host": "apple.sitegenesis.com",
      },
      {
         "if-agent-contains": ["blackberry"],
         "host": "bb.sitegenesis.com",
      }
],

Example 9: Three Sites Sharing Single Host Name

In this example, three existing sites previously used different host names. Because each of these sites supports a single locale, you don't have to specify the locale in your mapping rules. Your goal is to have all three sites share the host name (www.my-site.com) but use different site paths to differentiate themselves:

  • Site 1 in the past used www.my-site.uk and you want to change it to www.my-site.com/UK.
  • Site 2 in the past used www.my-site.com and you want to change it to www.my-site.com/US.
  • Site 3 in the past used www.my-site.de and you want to change it to www.my-site.com/DE.

You also want B2C Commerce to redirect URLs containing old hostnames to the new hostname plus site path values.

To accomplish these goals, you configure the hostname alias file for site 1 as follows:

"settings" : 
{
     "http-host" : "www.my-site.com",
     "https-host" : "www.my-site.com", 
     "site-path" : "UK", 
     "default" : "false"
}

"www.my-site.uk": 
[       
        {
            "host" : "www.my-site.com", "path" : "UK"            
        }
] 

Next, you configure the hostname alias file for site 2 as follows:

"settings" : 
{
     "http-host" : "www.my-site.com",
     "https-host" : "www.my-site.com", 
     "site-path" : "US", 
     "default" : "true"
}

Finally, you configure the hostname alias file for site 3 as follows:

"settings" : 
{
     "http-host" : "www.my-site.com",
     "https-host" : "www.my-site.com", 
     "site-path" : "DE", 
     "default" : "false"
}

"www.my-site.de": 
[       
        {
            "host" : "www.my-site.com", "path" : "DE"            
        }
] 

Example 10: a Single Site Supporting Multiple Host Names and Locales

When you want to redirect from domain A to domain B with the same site-path mapping for both domains, you must configure if-site-path conditions for both domains.

In this example, you have a single site that supported multiple host names in the past, each of which supported a single locale. As in the previous example, you want B2C Commerce to redirect the old hostnames to the new hostname plus site path values:

  • The existing host name www.my-site.uk (whose locale is en_UK) should now redirect to www.my-site.com/UK.
  • The existing host name www.my-site.com (whose locale is en_US, the default locale) should now redirect to www.my-site.com/US.
  • The existing host name www.my-site.de (whose locale is de_DE) should now redirect to www.my-site.com/DE.

To accomplish these goals, you configure the hostname alias file for the site as follows:

"settings" : 
{
     "http-host" : "",
     "https-host" : "", 
     "site-path" : "", 
     "default" : ""
},

"www.my-site.com": 
[       
        {
            "locale" : "en_US",
        },
        {
            "locale" : "de_DE",
                   "if-site-path" : "DE"
        },
        {
            "locale" : "en_US",
                   "if-site-path" : "US"
        },
        {
            "locale" : "en_UK",
                   "if-site-path" : "UK"
        },
], 

"www.my-site.de": 
[       
        {
            "host" : "www.my-site.com", "path" : "DE"            
        }
], 

"www.my-site.uk": 
[       
        {
            "host" : "www.my-site.com", "path" : "UK"            
        }
]

Example 11: Two Sites with Multiple Hosts and Locales

In this example, you want two sites (site 1 and site 2) to work with the multiple host names and locales. Both sites acknowledge the host names www.my-site.eu and www.my-site.com.

For the first host name (www.my-site.eu), you want to specify the following:

  • The host name www.my-site.eu should work by itself without a site path. B2C Commerce should direct the URL to site 1, and the default locale should be en.
  • The URL segment www.my-site.eu/DE should direct the URL to site 1, and the locale should be de.
  • The URL segment www.my-site.eu/FR should direct the URL to site 1, and the locale should be fr.
  • The URL segment www.my-site.eu/US should direct the URL to site 2, and the locale should be en.

For the second host name (www.my-site.com), you want to specify the following:

  • The host name www.my-site.com should work by itself without a site path. B2C Commerce should direct the URL to site 2, and the default locale should be en.
  • The URL segment www.my-site.com/FR should direct the URL to site 2, and the locale should be fr.
  • The URL segment www.my-site.com/UK should direct the URL to site 1, and the locale should be en.
  • The URL segment www.my-site.com/DE should direct the URL to site 1, and the locale should be de.

In addition the above goals, you want to add the EXAMPLE site path to both the www.my-site.eu and the www.my-site.com host names. For this site path, the locale should be en, and the configuration should direct the URL to the Example-DoSomething pipeline, which will take the following parameters:

  • cgid ― This parameter is set to the value "exampleCategory."
  • color ― This parameter is set to the value "blue."

To accomplish these goals, you configure the hostname alias file for site 1 as follows:

"settings" : 
{
     "http-host" : "",
     "https-host" : "", 
     "site-path" : "", 
     "default" : ""
},

"www.my-site.eu": 
[       
        {
            "locale" : "en",
        },
        {
            "locale" : "de",
                   "if-site-path" : "DE"
        },
        {
            "locale" : "fr",
                   "if-site-path" : "FR"
        },
        {
            "locale" : "en",
                   "if-site-path" : "EXAMPLE",
                   "pipeline" : "Example-DoSomething",
                   "params" : {"cgid":"exampleCategory", "color":"blue" }
        }
], 

"www.my-site.com": 
[       
        {
            "locale" : "de",
                   "if-site-path" : "DE"
        },
        {
            "locale" : "en",
                   "if-site-path" : "UK"
        }
]

Next, you configure the hostname alias file for site 2 as follows:

"settings" : 
{
     "http-host" : "",
     "https-host" : "", 
     "site-path" : "", 
     "default" : ""
},

"www.my-site.eu": 
[       
        {
            "locale" : "en",
                   "if-site-path" : "US"
        }
], 

"www.my-site.com": 
[       
        {
            "locale" : "en",
        },
        {
            "locale" : "fr",
                   "if-site-path" : "FR"
        },
        {
            "locale" : "en",
                   "if-site-path" : "EXAMPLE",
                   "pipeline" : "Example-DoSomething",
                   "params" : {"cgid":"exampleCategory", "color":"blue" }
        }
]

The following table shows how these configurations cause B2C Commerce to handle different entered URLs:

Entered URL Site Locale Pipeline Parameters
www.my-site.eu 1 en Default-Start  
www.my-site.eu/DE 1 de Default-Start  
www.my-site.eu/FR 1 fr Default-Start  
www.my-site.eu/US 2 en Default-Start  
www.my-site.eu/EXAMPLE 1 en Example-DoSomething cgid=exampleCategory&color=blue
www.my-site.com 2 en Default-Start  
www.my-site.com/UK 1 en Default-Start  
www.my-site.com/FR 2 fr Default-Start  
www.my-site.com/EXAMPLE 2 en Example-DoSomething cgid=exampleCategory&color=blue

Debugging the Hostname File as JSON

To make debugging easier, you should choose to use an external JSON debugger, such as the one available at http://www.jsonlint.com/. There are many other tools like this available to test the file.

The B2C Commerce hostname file syntax is inspired by JSON, but isn't strictly JSON. There are several items in the file syntax that are not valid JSON that you should change before using a debugger:
  • use colons rather than equal signs when specifying properties. Equal signs are not valid JSON, although they are supported in the hostname syntax
  • remove all comments in your file, as comments are not valid JSON.
  • remove commas after host entries, as commas are not valid JSON. They are required for the B2C Commerce hostname file, however, so remember to replace them after debugging your file.

Don't try to debug the hostname alias file in Business Manager through trial and error. If the file contains any JSON errors, the file is ignored and therefore any configured hostnames fail on the instance. Make sure that the file is valid JSON before saving it in Business Manager.

Testing the Hostname Configuration

Alias configurations can be complex on a Production instance and should be tested before they are added - and not just for syntax. If you don't want to configure and register the DNS and domain names for your test environment, you can configure domain names on your local machine. This is also an option if no domain names are available for your test environment. To test your configuration:

Hostname Alias Processing

B2C Commerce performs two different types of host name alias processing: handling entered URLs, and generating storefront URLs. To handle an entered URL, B2C Commerce examines the entered URL, and dispatches the request to the appropriate site for further processing. During storefront URL generation, B2C Commerce constructs URLs that are visible to customers.

Handling entered URLs

When B2C Commerce receives an entered URL from the customer, B2C Commerce checks all hostname alias files for all sites in your organization, looking for a suitable mapping.

  1. Is there a match for both the hostName and sitePath inside a settings property?
    • Yes - use the corresponding site (the site whose host name alias file contains the matching settings property) to handle the URL, and then continue to step 5.
    • No - continue to step 2.
  2. Outside of any settings property, is there a match for both the hostName and the sitePath (specified in the if-site-path property)?
    • Yes - use the corresponding site to handle the URL, and then continue to step 5.
    • No - continue to step 3.
  3. Inside the settings property, is there a match for hostName?
    • Yes - check to see if the defaultValue is true, and if it is, use the corresponding site to handle the URL, and continue to step 5. If no site with a match for hostName sets the defaultValue to true, use the first site in the sites list to handle the URL, and continue to step 5.
    • No - continue to step 4.
  4. Outside of any settings property, is there a match for just the hostName?
    • Yes - continue to step 6.
    • No - send an error message to the customer indicating that the requested resource could not be found. Skip all of the remaining steps in this process.
  5. Was the matching hostName and sitePath (if any) found in the settings property?
    • Yes - examine the remaining portion of the entered URL (the portion after the hostName and sitePath, if any) to determine the correct locale and nature of the requested resource (that is, to determine whether the URL specifies a category, content asset, or pipeline). If the entered URL specifies only the hostName and sitePath, or only the hostName, execute the Default-Start pipeline and return the response to the customer. Otherwise, retrieve the requested resource (executing a pipeline if necessary) and return the requested resource to the customer. If no locale is specified, use the default locale for the site when retrieving the requested resource. Skip all of the remaining steps in this process.
    • No - continue to step 6.
  6. Does the mapping rule contain an if-site-path property?
    • Yes - examine the remaining portion of the entered URL (the portion after the hostName and sitePath) to determine the nature of the requested resource (that is, is the URL specifying a category, content asset, or pipeline). If the remaining portion of the entered URL specifies the name of a category, content asset, or pipeline, retrieve the requested resource (executing the pipeline if necessary). Otherwise, examine the mapping rule to determine the values of the optional name, locale, pipeline, and params properties. Ignore all other property values (for example, ignore the if-agent-contains property). Use the name, locale, pipeline, and params property values to determine how to handle the request. If the entered URL specifies only the hostName and sitePath, check to see if the pipeline and params properties are set; if so, execute the configured pipeline using the configured params (if any); if the pipeline and param properties are not set, execute the Default-Start pipeline, and return the response to the customer. If no locale is specified, use the default locale for the site when retrieving the requested resource. Skip all of the remaining steps in this process.
    • No - continue to step 7.
  7. Is the first mapping rule an if-agent-contains rule?
    • Yes - continue to step 8.
    • No - process the first mapping rule. Because B2C Commerce only processes the first successful alias it finds, if-agent-contains must be included as the first mapping in a rule or it's never reached.
  8. Is the if-agent-contains condition true?
    • Yes - then process the mapping rule containing the if-agent-contains rule.
    • No - process the rule or condition after the rule associated with the previous if-agent-contains rule.
  9. Does the entered URL only contain the hostName?
    • Yes - the entered URL is a host-only URL that looks like this: http://www.sitegenesis.com/.

      • If the rule specifies a pipeline property value, forward the request to the pipeline using the pipeline, locale, and params properties.
      • If the rule specifies a host property value, redirect to the specified host.
      • If the rule provides a path, construct a redirect URL by appending the value from the provided path parameter to the value of the host property. If no value is configured for the host property, ignore the path property.
      • If the rule doesn't provide any parameters, forward the request to the Default-Start pipeline.
    • No - the entered URL contains at least a partial path and looks like this: http://www.sitegenesis.com/electronics

      • If the rule provides a host property value, replace the URL host with the host value and use the rest of the path in the entered URL to construct a 301 redirect.
      • If the rule provides a path but no host property value, the path value is ignored.
Note:

In order for the above process to work correctly, if you specify the same host name in the settings property of multiple sites, set the default property to true for only one site.

Generating Storefront URLs

When generating storefront URLs, B2C Commerce adds the appropriate site path to the generated URL. B2C Commerce determines the site path in the following way for a given hostname and locale. If the settings property specifies a value for the site-path property, B2C Commerce uses the specified value as the site path for the default locale (the configured default locale for the site). If the settings property doesn't specify a value for the site-path property, B2C Commerce uses the value of the locale property (or the locale property plus the if-site-path property) to determine the site path, as follows: